Project Key: aware Source: https://github.com/GoodCISO/aware License: Apache-2.0

AWARE v2.0 — Compliance infrastructure for autonomous AI agents, with a self-improving feedback loop. The v2 pipeline (Phase 1 → 5) is in active development. v1.0.0 (the bio-inspired routing + compliance layer) is shipped to GitHub and continues to run on its own port set (3000, 3001). v2 lives in the 18xxx port range and is the focus of this README.

AWARE is open-source autonomous compliance infrastructure for AI agents.

Autonomous AI agents operate across organisational boundaries, spawn child agents, and make independent decisions. Existing compliance frameworks — SOC 2 checklists, ISO 27001 templates, periodic audits — assume human oversight at every step. They don't apply to systems that act autonomously.

AWARE is different. It's infrastructure that makes compliance happen on its own:

• Every agent gets a cryptographic identity it can't fake
• Every action is evaluated against policy before it executes
• Revocation cascades automatically when an agent is compromised — kill the parent, the children go too
• Full audit trails build themselves — every decision, every context access, every escalation
• (v2) Every preference-pair disagreement becomes DPO training data — the system improves itself from real production traffic

AWARE implements T0–T4 constraint levels — five enforcement tiers every agent is defined on before it's allowed to act. Agents self-enforce the constraint level you assign. The tiers are defined in src/server.js and surfaced in src/ui/src/components/ConstraintEnforcementView.js:

• T0 — Audit Trail. Every action is logged. Foundational, always on.
• T1 — Crypto Identity. Every agent gets a non-human identity it can't fake. Foundational, always on.
• T2 — Guardrailed. Operational policies constrain what the agent can do.
• T3 — Policy-Driven. Advanced governance — full policy enforcement, including rate limits and decision routing.
• T4 — Autonomous. Full self-operation under declared constraints.

Core thesis: Bio-inspired coordination algorithms are the right primitive for autonomous agent orchestration and compliance. Pheromone-based routing, distributed consensus, and self-healing topologies translate directly to agent governance.

AWARE ships with built-in mapping to five major AI and security compliance frameworks. The mapper (src/compliance/framework-mapper.js) is the source of truth — every AWARE control is registered against the relevant control IDs in each framework.

Use src/compliance/framework-mapper.js as the source of truth for which AWARE controls map to which framework IDs. The companion compliance matrix at docs/compliance-matrix.md documents the full mapping in human-readable form.

AWARE 1.0 was the bio-inspired routing + compliance layer (Phases 1–4 of the v1 plan, all shipped). AWARE 2.0 extends that with a 5-stage self-improving feedback loop:

┌──────────────────────────────────────────────────────────────────────┐
│  1. Coordinator       routes /coordinate calls, picks tier,          │
│                        enforces budget + cost cap + kill switch     │
│                                                                      │
│  2. Conversation      logs every /coordinate to Postgres             │
│     Logger            (aware_conversations + aware_preference_pairs) │
│                                                                      │
│  3. PRM Score Cache   caches PRM judge scores by content hash        │
│                        (aware_prm_cache, 30-day TTL default)         │
│                                                                      │
│  4. AZR Self-Play     runs AZR task proposer/solver on Modal A100    │
│                        (gated by `--profile training`)               │
│                                                                      │
│  5. DPO Trainer       packages preference pairs → DPO dataset →      │
│                        submits Modal QLoRA job on trained-model           │
└──────────────────────────────────────────────────────────────────────┘

Each stage writes to Postgres; the next stage consumes what the previous wrote. When the loop closes (Phase 4 evaluation harness, not done), we'll have a system that improves itself from real production traffic with no operator intervention.

Detailed design: see redacted-internal-doc (v2 architecture + where each phase stands today).

Requires: Docker, Node 22+, curl, npm, jq (for the bring-up script).

# 1. Clone + enter
git clone https://github.com/GoodCISO/aware
cd aware

# 2. Copy the env template
cp deploy/env.example .env
$EDITOR .env   # uncomment + fill in what you have; defaults are safe for dev

# 3. Validate the config parses
npm run config:validate

# 4. (Optional) Run the test suite — should be green
npm test

# 5. Bring up the v2 stack
./scripts/aware-up

# 6. Verify health
curl -sS http://localhost:18080/health
# {"ok":true,"status":"live"}

To also start the trainer poller (Phase 3 AZR self-play):

./scripts/aware-up --profile training

The trainer stays in disabled-by-config state until you set AWARE_TRAINER_ENABLED=1 in .env AND run the one-time Modal deploy:

MODAL_PROFILE=goodciso modal deploy training/run.py

See docs/sop/sop-phase-3-azr-self-play.json for the full operator-action sequence.

Done (v2.0, code-complete, tests green, on feature/aware-2.0):

• Phase 1: Coordinator Foundation (537ea66)
• Phase 1 polish: ADR (internal) centralised config + config:show / config:validate (05a41ff)
• Phase 2.1: Conversation Logger (Postgres-backed) (be382b5)
• Phase 2.2: PRM Score Cache (Postgres + content-hash) (2a093cf)
• Phase 2.3: Budget Watchdog (rolling window, soft + hard cap) (e990303 + bf6d560)
• Phase 3: AZR Self-Play on Modal (sandbox + trainer poller + config) (c572bfd)
• Phase 3 follow-up: real modal@0.8.0 JS SDK surface + trained-model base model (6ff1cd2)
• R2: real JS SDK surface, @app.function() deploy wrapper, real-SDK bring-up smoke (cbf5511 + 6f15240)
• Phase 4 first slice: outcome filter + real DPO dataset packaging (89238df + bfe7a5b)
• Phase 5 R1: deploy/env.example (24 v2 env vars documented) (d58c4b8) — this commit
• Phase 5 R3: scripts/aware-up single-command bring-up (5fa4f9a) — this commit

In progress / not done:

• Phase 4 remaining: AZR results table + cross-join, coordinator weight-reload hook, evaluation harness, benchmark delta vs. base model
• Phase 5 remaining: fresh-VM-in-30-min test, test coverage ≥80%, dev guide, security audit (bandit/npm audit/gitleaks/trivy), single-binary packaging

Status tracking: every phase closure is recorded in redacted-internal-doc and mirrored to redacted-host-config/sops/. Every phase has a SOP in docs/sop/.

Test coverage: c8 measures v2 source paths only (coordinator, gateway, db, trainer, budget, config — not v1). Run npm run coverage for the full report, npm run coverage:summary for a quick per-file table. Current numbers (commit d32d653): 88.42% lines above the ADR (internal) ≥80% gate. Bring-up smoke 8i (BRINGUP_FULL=1) enforces the gate.

Security audit: scripts/security-scan.sh runs Bandit (Python AST), npm audit (Node CVEs), gitleaks (git history), and Trivy (filesystem + Dockerfile) and produces a combined security-audit-report.txt + .json. Each tool degrades gracefully (skips with warning) if not installed. Default is warn-only; --strict promotes warnings to errors. Bring-up smoke 8k (BRINGUP_FULL=1) runs it with --strict.

       Telegram / A2A / curl
                │
                ▼
   ┌──────────────────────────┐
   │  Gateway  :18080         │  ← BFF / proxy, kill switch, CORS, request log
   └──────────┬───────────────┘
              │  /coordinate → COORDINATOR_URL
              ▼
   ┌──────────────────────────┐
   │  Coordinator :18081      │  ← tier routing (online/hybrid/offline)
   │   - budget watchdog      │     cost cap, soft + hard limit
   │   - PRM score cache      │     content-hash keyed, 30-day TTL
   │   - conversation logger  │     aware_conversations + preference pairs
   │   - awareness scoring    │     tier fallthrough with PRM judge
   └──────────┬───────────────┘
              │
              ├──→ Ollama sidecar :11434  (qwen2.5:7b, local fallback)
              ├──→ the provider API            (primary tier, env-var token)
              └──→ <secondary-llm> API            (final fallback)

   ┌──────────────────────────┐         ┌──────────────────────────┐
   │  Postgres  :18432        │         │  Redis  :18379           │
   │   - aware_conversations  │         │   - rate limits          │
   │   - aware_preference_pairs│        │   - session state        │
   │   - aware_prm_cache      │         └──────────────────────────┘
   └──────────┬───────────────┘
              │
              ▼  (poller, --profile training)
   ┌──────────────────────────┐         ┌──────────────────────────┐
   │  Trainer poller          │ ──submit──▶ │  Modal                │
   │   - outcome filter       │             │   - AZR self-play      │
   │   - DPO dataset packager │             │   - QLoRA on trained-model  │
   │   - Modal client (real)  │             │   - weights → /root/   │
   └──────────────────────────┘             └──────────────────────────┘

Key files:

• src/coordinator/ — coordinator HTTP service
• src/gateway/ — gateway HTTP service (BFF)
• src/budget/ — Phase 2.3 budget watchdog
• src/prm-cache/ — Phase 2.2 PRM score cache
• src/logger/ — Phase 2.1 conversation logger
• src/trainer/ — Phase 3 + 4 trainer poller + outcome filter
• training/run.py — Modal QLoRA training function (operator deploys once)
• eval/ — Phase 4 evaluation harness (scaffold, not started)
• redacted-internal-doc — the v2 architecture decision
• redacted-internal-doc — centralised config (Phase 1 polish)

AWARE/
├── src/                  # v2 source (coordinator, gateway, logger, etc.)
├── training/             # Modal training function (Python)
├── eval/                 # Phase 4 evaluation harness (scaffold)
├── deploy/               # env.example, compose fragments
├── docker/               # Dockerfiles (coordinator, gateway, training)
├── scripts/              # aware-up, bring-up-coordinator.sh
├── config/               # modal-training.json + v2 runtime config
├── docs/
│   ├── adr/              # architecture decision records (reserved directory; current design notes in `redacted-internal-doc`)
│   ├── sop/              # Standard Operating Procedures per phase
│   └── EVOLUTION-BRIEF.md
├── redacted-internal-doc             # closure status of every phase
├── README.md             # this file
├── docker-compose.yml    # v1.0.0 stack (legacy, port 3000/3001)
├── docker-compose.coordinator.yml   # v2 stack (port 18080-18432)
├── .env.example          # v1.0.0 env reference (legacy)
├── deploy/env.example    # v2 env reference (24 vars)
└── package.json          # v2 Node deps

v1 (shipped): Node.js, Express.js, React, Material-UI, Docker, Nginx, Raft Consensus, Ant Colony Optimization. Ports 3000/3001/80/443/5001.

v2 (in development): Node 22, Postgres 16, Redis 7, Ollama (qwen2.5:7b), Modal (trained-model + A100-80GB), the provider M3 (primary), fallback model (fallback). Ports 18080/18081/11434/18432/18379.

Boundaries:

• Plugin SDK boundary: v2 extensions cross into core through <runtime>/plugin-sdk/* only (inherited from , not v1).
• Channel boundary: v1 Telegram bot is in src/agent.js; v2 channels (Telegram, A2A) live in src/channels/.
• Protocol boundary: gateway schema is contract — additive evolution only.

• Status: redacted-internal-doc — closure status of every phase
• v2 architecture: redacted-internal-doc
• Dev guide: CONTRIBUTING.md — for anyone reading or modifying v2 source
• Dev deep dive: docs/dev/architecture.md — pipeline, data flow, trainer lifecycle
• v1 evolution brief: docs/EVOLUTION-BRIEF.md
• SOPs: docs/sop/ — per-phase operator procedures
• SOP mirror: redacted-host-config/sops/ (canonical SOP store)
• Changelog: CHANGELOG.md
• Compliance matrix (v1): docs/compliance-matrix.md

Plus v2: the self-improving DPO loop means the system gets better the more you use it, without the operator shipping new model versions manually.

AMRO-S (arXiv:2603.12933) — Efficient and Interpretable Multi-Agent LLM Routing via Ant Colony Optimisation:

• Pheromone-based path selection across layered AI agent graphs
• Task-specific pheromone specialists prevent cross-task interference
• Quality-gated evolution reinforces only high-quality routing trajectories
• 4.7x speedup over existing multi-agent routing with better accuracy

What AMRO-S does NOT address (AWARE's differentiation): security heuristics, identity governance, kill switches, compliance mapping, blast radius containment. And in v2: preference-pair collection, DPO self-training, and the evaluation harness that closes the loop.