AAIS — Adaptive Assistant Intelligence System

Behavior enforced, not implied.

---

What Is This?

AAIS is a local-first assistant runtime where behavior is governed by explicit law, not left to inference.

Every request passes through a bridge-enforced ingress layer. Every decision leaves a trace. When the system reroutes, pauses, or blocks — you see why.

It ships with:

• Bridge-enforced ingress — fail-closed by default, no silent pass-through
• Signed, time-bound attestation — nonce-backed, replay and tamper rejection built in
• Governed memory and workflow paths — bounded authority per layer, no cross-layer drift
• Visible operator traces — why something passed, was blocked, or was downgraded This is not "trust me." It is "test it."

---

Why Is This Different?

Most assistant projects optimize for output first. AAIS optimizes for behavior first.

That means:

• One clear operating contract per turn
• Normal work and risky or experimental work stay separated
• The system shows when it reroutes, pauses, or blocks — it does not hide decisions
• Operator control is preserved, not abstracted away The core doctrine is Stabilize and Free: stability before freedom. The system earns more responsibility by staying inside clear rules, explaining its behavior, and failing in a controlled way. If it cannot do that, it slows down, asks for confirmation, or stops.

---

Quick Start

pip install -e .
python -m aais start --data-dir ./.runtime/aais-data

Then open:

Surface	URL
App	http://127.0.0.1:8000/app
Jarvis Console	http://127.0.0.1:8000/app/jarvis
Health	http://127.0.0.1:8000/health

Before launching (optional preflight):

python -m aais prepare --force-build --data-dir ./.runtime/aais-data
python -m aais doctor --data-dir ./.runtime/aais-data

Frontend dev server (if not using the packaged shell):

# From /frontend
npm install && npm run dev

Surfaces at localhost:3000/jarvis, localhost:3000/workbench, localhost:3000/memory.

---

Requirements

Use requirements.txt for standard local setup. The other requirements files cover specific environments:

File	Use
requirements.txt	Standard local
requirements-local.txt	Local with dev extras
requirements-laptop.txt	Constrained/laptop env
requirements-advanced.txt	Full feature set
requirements-training.txt	Training pipeline only

---

Optional: Claude Provider

Claude support ships with the standard Python requirements.

ANTHROPIC_API_KEY=your_key_here
AAIS_CLAUDE_MODEL=claude-sonnet-4-20250514       # optional override
AAIS_ENABLE_CLAUDE_AUTO_ROUTING=true              # routes eligible turns automatically

To pin Claude instead of auto-routing, start a session with provider_mode=claude_first or select it in the Jarvis Console provider controls.

---

Repository Structure

aais/                  Core runtime
api/                   API surface
app/                   Packaged shell and workflow infrastructure
src/                   jarvis_operator.py, api.py — main entry points
docs/
  spine/               Canonical project explanation
  runtime/             Runtime and system references
  contracts/           Laws and contracts
  subsystems/          Subsystem-specific packs
  audit/               Status and audit material
  _archive/            Lineage and reference — not active authority
  _future/             Planned — not live
engine/                Internal foundation layer
forge/                 Bounded contractor lane
evolve_engine/         Outcome-based adaptation layer
evals/                 Evaluation harness
tests/                 Test suite

Only docs/ (excluding _archive/ and _future/) is authoritative for runtime understanding.

---

Key Internal Layers

Layer	Role
Jarvis	Main authority lane — operator-facing ingress and runtime control
Forge	Bounded contractor lane — isolated code execution
OTEM	Bounded task and memory support
Workflow shell	Packaged app route layer
Evolve engine	Learns from outcomes — does not alter role definitions

---

What to Read Next

1. AAIS Human Guide
2. AAIS AI Operating Contract
3. AAIS Master Spec
4. AAIS Runtime Guide
5. AAIS Documentation Map

---

Project Laws

Document	What It Governs
README Law v1	How documentation is written and maintained
External Suggestion Admission Rule	How external input enters the system
ARIS Runtime Contract	Embedded repo-intelligence law
AAIS Cognitive Bridge Runtime Law	Bridge ingress and attestation rules

The full repo operating law is in REPO_LAWBOOK.md.

---

Security

See SECURITY.md for the disclosure policy.

---

License

Apache 2.0