AINE — AI-Native Engineering Platform

Operational infrastructure for autonomous software development. Not a chatbot. Not an agent. A runtime for orchestrating specialized agents under deterministic, observable, event-capable workflows.

Naming. This project is AINE (the platform/engine). HookClose is the historical repo name — same thing, kept only for the repo URL and metric namespaces until renamed. See NAMING.md for the full decision.

1. Purpose

AINE is a shared operational runtime that lets specialized AI agents:

• generate code autonomously
• review pull requests automatically
• run, repair and validate tests
• coordinate across multi-agent workflows
• execute 24/7 with operational memory
• emit and react to events
• run inside isolated sandboxes
• be observed end-to-end via OpenTelemetry

The platform is vendor-agnostic (LLM providers, VCS, storage are adapters), deterministic-first (state machines drive behavior; LLMs are tools, not the runtime), and event-capable (every state transition is an emittable event).

2. Architectural Pillars

Dependency direction

  adapters/  api/  tasks/        <-- frameworks & I/O
        |
        v
  runtime/  scheduler/  sandbox/ <-- orchestration
        |
        v
  workflows/  agents/  memory/   <-- application
        |
        v
  contracts/  events/            <-- domain (no deps on anything above)

No module may import from a layer above its own.

3. Bounded Contexts

See specs/bounded-contexts.md for context maps.

4. Tech Stack

• Python 3.11+, fully typed (mypy strict).
• FastAPI — HTTP surface for the runtime.
• PostgreSQL 16 + pgvector — relational + vector storage.
• Redis 7 — broker, cache, pub/sub.
• Celery 5 — durable task execution.
• SQLAlchemy 2.0 async — ORM + UoW.
• Pydantic v2 — schemas, settings, validation.
• OpenTelemetry — traces, metrics, logs.
• Docker Compose — local-first dev.
• Ruff + mypy + pytest — quality gates.

5. Local bootstrap

# Linux/macOS
./scripts/bootstrap.sh

# Windows (PowerShell)
./scripts/bootstrap.ps1

Then:

docker compose up -d
# API:        http://localhost:8000/health
# Flower:     http://localhost:5555
# OTEL UI:    http://localhost:16686

6. Layout

.
├── runtime/         kernel, lifecycle, FastAPI surface
├── agents/          agent descriptors & registry (no logic yet)
├── contracts/       Protocols — the project's API surface
├── events/          domain events
├── workflows/       deterministic state machines
├── memory/          episodic + semantic + operational
├── sandbox/         isolated execution
├── observability/   tracing/metrics/logs/audit
├── scheduler/       cron + triggers
├── tasks/           Celery scaffolding
├── adapters/        outbound integrations
├── infra/           postgres/redis/otel configs
├── docker/          Dockerfiles
├── specs/           architecture & ADRs
├── reviews/         review templates
├── scripts/         bootstrap & ops
├── tests/           unit / integration / contract
├── docker-compose.yml
├── pyproject.toml
└── README.md

7. Engineering

make dev      # set up dev env + hooks
make check    # lint + typecheck + tests (the CI gate)

8. Status

Runtime core in progress. Foundation (contracts, events, deterministic workflows, sandbox, memory, observability primitives, scheduler, tasks) is in place. Operational engineering (CI/CD, tooling, runtime-state persistence) is established. Providers, routing, workers, chaining, and self-healing are being built in phases — see ROADMAP.md. Build state lives in SYSTEM_STATE.json.

Deployment: VPS deployment is gated until the local runtime core is stable (queues, workers, routing, retry loops, chaining all verified).