astromesh

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build & Development

```bash
uv sync                              # Install base dependencies
uv sync --extra all                  # Install all optional backends
uv run uvicorn astromesh.api.main:app --reload  # Run API server (port 8000)
```

### Dependencias: `uv.lock` está versionado

Hay cuatro proyectos uv independientes, cada uno con su lock: la raíz,
`astromesh-node/`, `astromesh-cli/` y `astromesh-orbit/`. CI los instala con
`uv sync --locked`, que **falla** si el lock quedó desincronizado de su
`pyproject.toml`.

Si cambiás dependencias en un `pyproject.toml`, corré `uv lock` **en ese mismo
directorio** y commiteá el lock junto al cambio. Para subir una dependencia a
propósito: `uv lock --upgrade-package <nombre>`.

Esto es deliberado: antes CI resolvía fresco en cada corrida y el gate se rompía
por calendario, no por commits — ruff 0.16 entró solo y dejó rojo cualquier PR
sin que cambiara una línea de código. Ver `docs/DEBT.md`.

The API app runs an ASGI **lifespan** that bootstraps `AgentRuntime` and wires route modules (same idea as `astromeshd`). Use `ASTROMESH_CONFIG_DIR` to point at a config tree; set `ASTROMESH_SKIP_RUNTIME=1` to skip bootstrap (tests).

**Logging:** `astromesh.logging_config.setup_logging()` runs on API import. Default `ASTROMESH_LOG_LEVEL=DEBUG` (detailed). Quieter: `INFO` or `WARNING`. Third-party noise capped with `ASTROMESH_LOG_THIRDPARTY_LEVEL` (default `WARNING`). Disable setup: `ASTROMESH_LOG_CONFIGURE=0`. Uvicorn access/error log level is still controlled by `uvicorn --log-level`.

Python 3.12+ required. Package manager is `uv`, build system is `hatchling`.

### Rust Native Extensions (optional)

```bash
pip install maturin
maturin develop --release            # Build Rust extensions into astromesh._native
cargo test                           # Run Rust unit tests
cargo check                          # Verify Rust compiles
```

Rust extensions provide 5-50x speedup for CPU-bound paths. Without them, Python fallback is used automatically. Set `ASTROMESH_FORCE_PYTHON=1` to disable native extensions at runtime.

## Tests

```bash
uv run pytest -v                          # All tests
uv run pytest tests/test_whatsapp.py      # Single file
uv run pytest tests/test_api.py -k "test_health"  # Single test
uv run pytest --cov=astromesh             # With coverage
```

Pytest runs with `asyncio_mode = "auto"` — async test functions work without decorators. Use `respx` for mocking HTTP calls. `httpx.ASGITransport` does not run lifespan by default; shared `client` in `tests/conftest.py` wraps the app with `asgi-lifespan` so the runtime is initialized like production.

## Linting

```bash
uv run ruff check astromesh/ tests/          # Lint
uv run ruff format --check astromesh/ tests/ # Format — the gate CI actually runs
uv run ruff format astromesh/ tests/         # Format — writes the fix
```

Line length: 100. Target: Python 3.12.

**`ruff check` passing does NOT mean CI is green.** `.github/workflows/ci.yml:48`
runs `ruff format --check` as its own step, and a file that lints clean can still
be unformatted. This is measured, not theoretical: the merge of the confirmation
gate went red on `Format check` with both test files lint-clean, and cost an extra
commit on `develop`. Run the `--check` form before pushing, or `ruff format` and
commit what it rewrites. The same pairing guards `astromesh_orbit/` (`ci.yml:114`)
and `astromesh_glyph/` (`ci.yml:142`).

## Docker

```bash
cd docker && docker compose up -d         # Full stack (API + Ollama + Postgres + Redis + monitoring)
```

## Architecture

4-layer design where everything flows through the Agent Runtime:

```
API Layer (FastAPI REST + WebSocket)
    → Runtime Engine (AgentRuntime loads YAML → Agent instances)
        → Core Services (ModelRouter, MemoryManager, ToolRegistry, PromptEngine, GuardrailsEngine)
            → Infrastructure (Providers, Memory Backends, Orchestration Patterns, Channels, RAG, MCP)
```

**Agent execution pipeline:** Query → input guardrails → build memory context → render Jinja2 prompt → orchestration pattern (ReAct/PlanAndExecute/etc.) → model router → tool calls → output guardrails → persist memory → response.

### Key abstractions

- **ProviderProtocol** (`astromesh/providers/base.py`): Runtime-checkable Protocol that all LLM providers implement. Methods: `complete()`, `stream()`, `health_check()`, `supports_tools()`, `estimated_cost()`.
- **AgentRuntime** (`astromesh/runtime/engine.py`): Bootstraps agents from `config/agents/*.agent.yaml`, wires up all services. Call `runtime.run(agent_name, query, session_id)`.
- **ModelRouter** (`astromesh/core/model_router.py`): Routes to providers using strategies (cost_optimized, latency_optimized, quality_first, round_robin). Has circuit breaker (3 failures → 60s cooldown).
- **ToolRegistry** (`astromesh/core/tools.py`): Registers tools as internal (Python), MCP, webhook, or RAG. Handles permissions, rate limiting, and schema generation for LLM function calling.
- **OrchestrationPattern** (`astromesh/orchestration/patterns.py`): Abstract base for ReAct, PlanAndExecute, ParallelFanOut, Pipeline, Supervisor, Swarm.
- **MemoryManager** (`astromesh/core/memory.py`): Manages 3 memory types — conversational (chat history), semantic (vector embeddings), episodic (event logs). Strategies: sliding_window, summary, token_budget.

### Agent YAML schema

Agents are defined in `config/agents/*.agent.yaml` with schema `apiVersion: astromesh/v1, kind: Agent`. Spec sections: `identity`, `model` (primary + fallback + routing), `prompts` (Jinja2 system prompt), `orchestration` (pattern + iterations + timeout), `tools`, `memory`, `guardrails`, `permissions`.

### API routes

Routes inject runtime via `set_runtime()` called during bootstrap. Pattern: each route module exposes a `router` (APIRouter) and a `set_runtime(runtime)` function.

- `/v1/agents/{name}/run` — Execute agent (POST)
- `/v1/ws/agent/{name}` — WebSocket streaming
- `/v1/channels/whatsapp/webhook` — WhatsApp webhook (GET verify + POST messages)
- `/v1/memory/`, `/v1/tools/`, `/v1/rag/` — Supporting endpoints

### Channels

Channel adapters live in `astromesh/channels/`. Config in `config/channels.yaml` with env var references (`${VAR_NAME}`). WhatsApp uses background tasks for agent execution to respond to Meta within 5s.

## Conventions

- Conventional commits: `feat:`, `fix:`, `chore:`, `test:`, `docs:`
- Versioning: semver with `v` prefix tags (v0.1.0, v0.2.0)
- Main branch: `develop`
- All async: providers, tools, memory backends, and route handlers are async
- Config from env vars for secrets, YAML files for structure

## Changelog Rule

**MANDATORY:** Before creating any commit with type `feat:`, `fix:`, or `refactor:`, you MUST update `CHANGELOG.md` first using the `/changelog-automation` skill. Add the change under the `## [Unreleased]` section in the appropriate subsection (Added, Changed, Fixed). If the `[Unreleased]` section doesn't exist, create it below the header. Follow the [Keep a Changelog](https://keepachangelog.com/) format. Group entries under `### Added (Backend)`, `### Added (Astromesh Forge)`, `### Changed`, `### Fixed`, etc. as appropriate. Never commit a `feat`/`fix`/`refactor` change without its changelog entry in the same commit or an immediately preceding commit.

## Release Checklist

This is a monorepo of **independently versioned packages**. They are NOT kept in sync with each
other — only bump what actually changed.

**Releasing the core (`astromesh`)** — these two files are the same package, so they move together
(`cz bump` does both; they are commitizen's `version_files`):
- `pyproject.toml` → `version` (two occurrences: `[project]` and `[tool.commitizen]`)
- `astromesh/__init__.py` → `__version__`

Then add the `CHANGELOG.md` section (`## [vX.Y.Z] - YYYY-MM-DD`, moving what sits under
`[Unreleased]`) and tag `vX.Y.Z` (annotated). Pushing the tag publishes to PyPI.

**Los lockfiles también se mueven.** Desde que `uv.lock` está versionado, bumpear el core
cambia además `uv.lock`, `astromesh-node/uv.lock` y `astromesh-cli/uv.lock`, porque los tres
registran la versión de `astromesh` (los dos últimos lo referencian como editable `../`).
Corré `uv lock` en esos tres directorios y commitealos con el release, o CI falla en
`uv sync --locked`. `astromesh-orbit` no lo referencia y no se toca.

**Sub-packages release on their own cadence**, each with its own version file and release commit
(e.g. `chore(release): astromesh-adk 0.1.9`) — do not bump them just because the core moved:
Each Python sub-package keeps its `pyproject.toml` `version` and its package `__init__.py`
`__version__` in step with each other (nothing automates this — commitizen only covers the core):
- `astromesh-adk/` → `astromesh_adk/__init__.py` (also has its own `CHANGELOG.md`)
- `astromesh-orbit/` → `astromesh_orbit/__init__.py` (also has its own `CHANGELOG.md`)
- `astromesh-node/` → `src/astromesh_node/__init__.py`
- `astromesh-cli/` → `astromesh_cli/__init__.py`
- `astromesh-forge/package.json` (npm; no Python version file. Dormant since 0.23.0 — bump only if
  Forge actually changed)

**Downstream:** `astromesh-os` (separate repo) pins a core release tag in `runtime.pin` and builds
the image from it. Its CI cannot resolve uv path sources (`build-deb.sh` uses pip) and its boot gate
is what catches a runtime that imports but does not start — so verify a tag builds before pinning it.

More agent context in monaccode/astromesh

11 other files this repository gives its agents.