Metadata-Version: 2.4
Name: hexicodes
Version: 0.2.0
Summary: Minimal contract-driven coding-agent runtime + CLI
Author: Antonio Ognio
Maintainer: Antonio Ognio
License: MIT
Project-URL: Homepage, https://hexi.readthedocs.io
Project-URL: Documentation, https://hexi.readthedocs.io
Project-URL: Source, https://github.com/hexi-codes/hexi
Project-URL: Issues, https://github.com/hexi-codes/hexi/issues
Keywords: ai,agent,coding-agent,cli,developer-tools,hexagonal-architecture,openrouter,typer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer<1,>=0.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: rich<15,>=13.7
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Provides-Extra: openrouter-http
Requires-Dist: requests<3,>=2.31; extra == "openrouter-http"
Provides-Extra: openrouter-sdk
Requires-Dist: openrouter<1,>=0.6.0; extra == "openrouter-sdk"
Provides-Extra: openrouter
Requires-Dist: requests<3,>=2.31; extra == "openrouter"
Requires-Dist: openrouter<1,>=0.6.0; extra == "openrouter"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.2; extra == "dev"
Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"
Requires-Dist: requests<3,>=2.31; extra == "dev"
Requires-Dist: responses<1,>=0.25; extra == "dev"
Requires-Dist: respx<1,>=0.21; extra == "dev"
Dynamic: license-file

# Hexi v0.2.0

![Hexi Saturn Hexagon](https://raw.githubusercontent.com/aognio/hexi/main/assets/images/hexi-saturn-hexagon-1024x1024.png)

Hexi is a minimal, contract-driven (hexagonal) coding-agent runtime and CLI.
It runs exactly one agent step per invocation against a local git repository.

## Test Drive (5 Minutes)
Run this in any local git repo you can safely modify.

1. Install Hexi:
```bash
pip install -e .
```
Optional OpenRouter support:
```bash
pip install -e ".[openrouter]"
```

2. Initialize Hexi files:
```bash
hexi init
```

3. Onboard provider/model and key:
```bash
hexi onboard
```
When prompted, pick any provider. For OpenRouter providers, install the optional extra and provide `OPENROUTER_API_KEY`.

4. Verify setup:
```bash
hexi doctor
```
Expected: provider/model printed and `Doctor check passed`.

5. Run one agent step:
```bash
hexi run "Add one tiny test for an existing function and run pytest"
```

6. Inspect what changed:
```bash
hexi diff
tail -n 20 .hexi/runlog.jsonl
```

7. If you want to switch providers later:
```bash
hexi onboard
```
Re-run onboarding to update `.hexi/local.toml`.

## What it is
- Python package (PyPI distribution): `hexicodes`
- Core contracts in `hexi.core`
- Side-effect adapters in `hexi.adapters`
- One-step execution with structured event logging to `.hexi/runlog.jsonl`

## What it is not
- No daemon, no background workers, no web UI
- No MCP server and no SQLite in v0.2.0
- No multi-agent orchestration


## Install
```bash
pip install -e .
```

### OpenRouter support (optional)
- HTTP adapter only (`openrouter_http` provider):
```bash
pip install -e ".[openrouter-http]"
```
- SDK adapter only (`openrouter_sdk` provider):
```bash
pip install -e ".[openrouter-sdk]"
```
- Both OpenRouter adapters:
```bash
pip install -e ".[openrouter]"
```

Dev/test dependencies:
```bash
pip install -e ".[dev]"
```

## CLI
- `hexi --help` or `hexi help` : show command help
- `hexi --version` or `hexi version` : print installed version
- `hexi init` : create `.hexi/config.toml`, `.hexi/local.toml`, `.hexi/runlog.jsonl`
- `hexi onboard` : interactive setup for provider/model and optional local key paste
- `hexi new` : scaffold a project from built-in Hexi templates (non-interactive by default)
- `hexi demo` : fancy interactive flow with random/model-generated ideas and template scaffolding
- `hexi run "<task>"` : execute one agent step and emit structured events
- `hexi apply --plan plan.json` : execute a validated ActionPlan file directly (debug/replay mode)
- `hexi diff` : show current git diff
- `hexi doctor` : verbose diagnostics; use `--probe-model` for live “What model are you?” check
- `hexi plan-check --file plan.json` : validate/troubleshoot ActionPlan JSON directly

## Documentation (MkDocs + Read the Docs)
Build docs locally:
```bash
pip install -e ".[docs]"
mkdocs serve
```

Read the Docs config is in `.readthedocs.yml`.

## Configuration design choices
Hexi uses layered TOML configuration:
1. `.hexi/config.toml` (repo defaults)
2. `.hexi/local.toml` (local machine overrides)
3. Environment variables (recommended for secrets)

For secrets, env vars are preferred. `hexi onboard` can write keys to `.hexi/local.toml` for local/testing convenience.

## Config shape (`.hexi/config.toml`)
```toml
[model]
provider = "openai_compat" # openrouter_http | openrouter_sdk | openai_compat | anthropic_compat
model = "gpt-4o-mini"

[providers.openrouter_http]
base_url = "https://openrouter.ai/api/v1"
api_style = "openai" # openai | anthropic

[providers.openrouter_sdk]
base_url = "https://openrouter.ai/api/v1"

[providers.openai_compat]
base_url = "https://api.openai.com/v1"

[providers.anthropic_compat]
base_url = "https://api.anthropic.com"

[policy]
allow_commands = ["git status", "git diff", "pytest", "python -m pytest"]
max_diff_chars = 4000
max_file_read_chars = 4000
```

## Local override example (`.hexi/local.toml`)
```toml
[model]
provider = "openrouter_http"
model = "anthropic/claude-sonnet-4-6"

[providers.openrouter_http]
api_style = "anthropic"

[secrets]
openrouter_api_key = "..."
```

## Env vars
- `OPENROUTER_API_KEY` for `openrouter_http` and `openrouter_sdk`
- `OPENAI_API_KEY` for `openai_compat`
- `ANTHROPIC_API_KEY` for `anthropic_compat`

## Packaging
- Distribution name: `hexicodes`
- Console script: `hexi`
- Optional extras:
  - `openrouter-http`
  - `openrouter-sdk`
  - `openrouter`
  - `docs`
  - `dev`

## Included example projects
- `examples/todo_refiner` : minimal CLI-wrapper agent integration
- `examples/embedded_step` : direct embedded `RunStepService` usage
- `examples/policy_loop` : multi-step user-gated loop using repeated `hexi run`

## Example ActionPlans (`hexi apply`)
- `examples/action_plans/read_only.json` : inspect file + emit progress
- `examples/action_plans/write_file.json` : create a file in-repo
- `examples/action_plans/run_tests.json` : run `pytest -q`
- `examples/action_plans/mixed_step.json` : read + write + run + emit

Try one now:
```bash
hexi plan-check --file examples/action_plans/mixed_step.json
hexi apply --plan examples/action_plans/mixed_step.json --task "ActionPlan debug run"
```

## Included Hexi-native templates
- `templates/hexi-python-lib` : tested library starter with Hexi wiring
- `templates/hexi-fastapi-service` : FastAPI service starter with Hexi wiring
- `templates/hexi-typer-cli` : Typer CLI starter with Hexi wiring
- `templates/hexi-data-job` : data job starter with dry-run and Hexi wiring
- `templates/hexi-agent-worker` : embedded Hexi runtime starter

## Provenance

Made with ❤️ from 🇵🇪. El Perú es clave 🔑.
