HelixAgent

Durable autonomous-agent runtime in Python: a bounded plan/execute/observe/replan loop with governed tools, approval gates, and SQLite checkpoints for resumable runs. FastAPI service with Prometheus + OpenTelemetry, optional C++ acceleration with Python fallback, and reproducible benchmarks.

HelixAgent is a durable Python agent runtime built around a bounded plan/execute/observe/replan loop with governed tools, approval gates, and SQLite checkpoints. Its included planner is deterministic and rule-based; the planner protocol is extensible, but no model provider is implemented. Optional C++ cosine similarity degrades gracefully to a scale-stable Python fallback when the shared library is unavailable.

Features

• Bounded autonomous execution: A typed plan/execute/observe/replan loop enforces iteration and tool-call budgets.
• Deterministic planning and native acceleration: The typed planner protocol uses a rule-based default, while ctypes optionally loads a C++ cosine-similarity library.
• Resilient fallbacks: Python planning and vector implementations keep the agent usable without native artifacts.
• FastAPI service: /, /health, and /predict endpoints with generated OpenAPI documentation.
• Observability: Prometheus metrics and OpenTelemetry instrumentation are attached to the API.
• Interactive demo: A Streamlit interface exercises the same agent runtime.
• Container delivery: Multi-stage Docker build, compiled C++ extension, non-root runtime, and container health check.
• Automated assurance: Python 3.10/3.11 tests, coverage artifacts, API and Streamlit smoke tests, container validation, CodeQL, Gitleaks, Trivy, dependency auditing, and CycloneDX SBOM generation.
• Durable autonomy: Budgeted plan/execute/observe/replan runs, SQLite checkpoints, retries, tool timeouts, explicit approval gates, and resumable run APIs.

Architecture

Client / Streamlit
        |
        v
     FastAPI  ----> Prometheus + OpenTelemetry
        |
        v
 Autonomous runtime ----> SQLite checkpoints
   |        |       |
   |        |       +--> Governed tool registry + approval gates
   |        +----------> C++ vector library -> Python fallback
   +-------------------> Planner protocol -> deterministic default

The runtime separates policy from mechanism: planners propose typed tasks, the runtime owns budgets and state transitions, the registry owns tool risk and timeout policy, and the store owns durability. This keeps a future model planner from bypassing execution invariants.

Concern	Design decision	Operational tradeoff
Recovery	Checkpoint every run transition in SQLite	Simple single-node durability; distributed workers require leases and a shared store
Safety	Pause write/destructive tools for explicit approval	Safer default with additional operator latency
Runaway control	Bound iterations, tool calls, retries, and tool duration	Predictable cost; a valid long task may exhaust its budget
Planner extensibility	Typed Planner protocol with rule-based default	Credential-free execution; no model provider is implemented
Native acceleration	Optional C++ cosine similarity with Python fallback	Portable behavior with environment-dependent performance

Runtime invariants are covered by tests: terminal states are persisted, denied tools are never executed, budget exhaustion fails closed, retries are bounded, and timeout responses do not wait for a slow handler. The database location is configurable with HELIXAGENT_RUN_DB; the container uses the writable non-root path /app/data/helixagent_runs.db.

Research metrics and benchmarks

The benchmark is a deterministic microbenchmark of orchestration plus SQLite checkpoints. It does not include network search, model inference, or provider latency.

Metric	Reference result
Successful runs	200/200 (100%)
End-to-end latency, p50	7.798 ms
End-to-end latency, p95	8.629 ms
Checkpoint read latency, p50	0.092 ms
Checkpoint read latency, p95	0.119 ms
Sequential throughput	125.666 runs/s

Reference environment: Python 3.12.13, Windows 11 build 26200, AMD64; 20 warmups, 200 measured runs, two deterministic tasks per run, measured July 22, 2026. These are reference observations, not production SLOs or cross-hardware claims. Reproduce locally with:

python -m benchmarks.autonomy_runtime --iterations 200 --warmup 20

See benchmark methodology and limitations for metric definitions and the evaluation boundary. CI also uploads a fresh benchmark-results.json artifact on Python 3.11.

Evidence boundaries

The CI matrix exercises Python 3.10 and 3.11 quality/tests, container API health, and Streamlit startup; security and supply-chain workflows run separately. Runtime contract coverage includes terminal-run idempotence, approval gating, bounded retries and budgets, persisted failure for unknown tools, and Python vector fallback properties. The C++ path remains optional and environment-dependent, so native-enabled parity is not claimed.

For the full claim-to-evidence map, invariant definitions, and reproducible statistical primitives, see claims matrix, runtime invariants, and evaluation notes.

Quick start

Requires Python 3.10 or newer.

git clone https://github.com/CoreyLeath-code/HelixAgent.git
cd HelixAgent
python -m venv .venv

Activate the environment, then install and run the API:

pip install -r requirements.txt
uvicorn api.main:app --reload

Open Swagger UI, or verify the service:

curl http://localhost:8000/health
curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Compare vectors and summarize the result."}'

Run the Streamlit demo locally:

streamlit run streamlit_app.py

Test and container workflows

pip install -r requirements-dev.txt
pytest tests -v --cov=agent --cov=api --cov=src --cov-report=term-missing
ruff check api agent src tests streamlit_app.py
python -m benchmarks.autonomy_runtime --iterations 200 --warmup 20
docker build -t helixagent .
docker run --rm -p 8000:8000 helixagent

Project map

api/                 FastAPI application and monitoring
agent/               Autonomous runtime, planner/tool contracts, and optional C++
src/                 Data and application services
tests/               Unit, API, and data-processing tests
.github/workflows/   CI, security, and release automation
docs/                Engineering and deployment notes

Project status

HelixAgent is an engineering portfolio project and reference implementation, not a managed commercial AI platform. The repository focuses on modularity, graceful degradation, observable services, automated validation, and secure delivery.

See Autonomous runtime, Security, Contributing, Changelog, and deployment hygiene.