hexicodes 0.1.0__tar.gz

hexicodes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Ognio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hexicodes-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: hexicodes
+Version: 0.1.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/antonioognio/hexi
+Project-URL: Issues, https://github.com/antonioognio/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.1.0
+
+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.1.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 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`
+
+## 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 🔑.

hexicodes-0.1.0/README.md

@@ -0,0 +1,184 @@
+# Hexi v0.1.0
+
+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.1.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 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`
+
+## 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 🔑.

hexicodes-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hexicodes"
+version = "0.1.0"
+description = "Minimal contract-driven coding-agent runtime + CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Antonio Ognio" }]
+maintainers = [{ name = "Antonio Ognio" }]
+keywords = [
+  "ai",
+  "agent",
+  "coding-agent",
+  "cli",
+  "developer-tools",
+  "hexagonal-architecture",
+  "openrouter",
+  "typer"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Software Development :: Testing"
+]
+dependencies = [
+  "typer>=0.12,<1",
+  "httpx>=0.27,<1",
+  "rich>=13.7,<15",
+  "tomli>=2.0.1; python_version < '3.11'"
+]
+
+[project.optional-dependencies]
+openrouter-http = ["requests>=2.31,<3"]
+openrouter-sdk = ["openrouter>=0.6.0,<1"]
+openrouter = [
+  "requests>=2.31,<3",
+  "openrouter>=0.6.0,<1"
+]
+docs = [
+  "mkdocs>=1.6,<2",
+  "mkdocs-material>=9.5,<10"
+]
+dev = [
+  "pytest>=8.2,<9",
+  "pytest-asyncio>=0.23,<1",
+  "requests>=2.31,<3",
+  "responses>=0.25,<1",
+  "respx>=0.21,<1"
+]
+
+[project.urls]
+Homepage = "https://hexi.readthedocs.io"
+Documentation = "https://hexi.readthedocs.io"
+Source = "https://github.com/antonioognio/hexi"
+Issues = "https://github.com/antonioognio/hexi/issues"
+
+[project.scripts]
+hexi = "hexi.cli:app"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+license-files = ["LICENSE"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

hexicodes-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hexicodes-0.1.0/src/hexi/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.1.0"

hexicodes-0.1.0/src/hexi/adapters/__init__.py

@@ -0,0 +1,21 @@
+from .event_log_jsonl import JsonlRunlogEventSink
+from .events_console import ConsoleEventSink
+from .exec_local import LocalExec
+from .memory_file import FileMemory
+from .model_anthropic_compat import AnthropicCompatModel
+from .model_openai_compat import OpenAICompatModel
+from .model_openrouter_http import OpenRouterHTTPModel
+from .model_openrouter_sdk import OpenRouterSDKModel
+from .workspace_local_git import LocalGitWorkspace
+
+__all__ = [
+    "JsonlRunlogEventSink",
+    "ConsoleEventSink",
+    "LocalExec",
+    "FileMemory",
+    "AnthropicCompatModel",
+    "OpenAICompatModel",
+    "OpenRouterHTTPModel",
+    "OpenRouterSDKModel",
+    "LocalGitWorkspace",
+]

hexicodes-0.1.0/src/hexi/adapters/event_log_jsonl.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from hexi.core.domain import Event
+from hexi.core.schemas import event_to_dict
+
+
+class JsonlRunlogEventSink:
+    def __init__(self, runlog_path: Path) -> None:
+        self.runlog_path = runlog_path
+
+    def emit(self, event: Event) -> None:
+        self.runlog_path.parent.mkdir(parents=True, exist_ok=True)
+        with self.runlog_path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(event_to_dict(event), ensure_ascii=True) + "\n")

hexicodes-0.1.0/src/hexi/adapters/events_console.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import json
+
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.text import Text
+
+from hexi.core.domain import Event
+
+_EVENT_STYLES: dict[str, tuple[str, str]] = {
+    "progress": ("cyan", "⏳"),
+    "question": ("yellow", "❓"),
+    "review": ("magenta", "🔎"),
+    "artifact": ("green", "📦"),
+    "error": ("red", "✖"),
+    "done": ("bright_blue", "✔"),
+}
+
+
+class ConsoleEventSink:
+    def __init__(self) -> None:
+        self.console = Console()
+
+    def emit(self, event: Event) -> None:
+        color, icon = _EVENT_STYLES.get(event.type, ("white", "•"))
+        title = Text(f"{icon} {event.type.upper()}", style=f"bold {color}")
+        subtitle = "blocking" if event.blocking else "non-blocking"
+
+        lines = [Text(event.one_line_summary, style="bold")]
+        if event.payload:
+            payload_str = json.dumps(event.payload, ensure_ascii=True, indent=2)
+            lines.append(Text(""))
+            lines.append(Syntax(payload_str, "json", word_wrap=True))
+
+        self.console.print(Panel.fit(Group(*lines), title=title, subtitle=subtitle, border_style=color))

hexicodes-0.1.0/src/hexi/adapters/exec_local.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import shlex
+import subprocess
+
+from hexi.core.domain import Policy
+from hexi.core.policy import command_allowed
+
+
+class LocalExec:
+    def run(self, command: str, policy: Policy) -> tuple[int, str, str]:
+        if not command_allowed(command, policy):
+            raise PermissionError(f"command is not allowlisted: {command}")
+        args = shlex.split(command)
+        proc = subprocess.run(args, capture_output=True, text=True, check=False)
+        return proc.returncode, proc.stdout[-8000:], proc.stderr[-8000:]