# Agentic OS Lab — AI Teachers

An original educational, **local-only**, standard-library Python control-plane demonstration for the free course at https://aiteachers.cc/academy/agentic-os/

**What it does:** Simulates a planner, a worker that writes a local draft, an independent deterministic verifier, a strict policy gate, a daily estimated spend ledger, a separate human-audit step, a narrow trust policy and a re-verification heartbeat.

**What it does not do:** Call Claude or any other model; access the internet, Gmail, websites, payment systems, git or production; send emails; run shell commands; upload personal data; securely isolate processes; enforce your actual API bill; or autonomously improve code. All costs are explicitly simulated. Do not put real customer information in these demonstration fixtures or the training ledger.

## Run in five steps

Requires Python 3.10+ only. Download all four files (agentic_os.py, constitution.json, demo-safe.json, demo-injection.json) into the same directory.

~~~bash
# 1. Prepare a local-only run using fictional records.
python3 agentic_os.py --state ./lab-state run --task demo-safe.json

# 2. Independently recheck the stored evidence.
python3 agentic_os.py --state ./lab-state monitor

# 3. After a person actually reviews the evidence, record their decision.
python3 agentic_os.py --state ./lab-state audit \
  --task-id feedback-safe-001 --reviewer learner --result pass

# 4. A hostile instruction hidden in untrusted data should fail its check.
python3 agentic_os.py --state ./lab-state run --task demo-injection.json

# 5. Inspect task counts, estimated spend, human audits and trust state.
python3 agentic_os.py --state ./lab-state report
~~~

The --state directory is created locally. Use an absolute path if needed. To rerun a task deliberately, **give the fixture a different unique id**; duplicates fail closed.

### Experiment: enforce a budget

Copy the policy file, lower daily_budget_usd to 0.001 and max_estimated_task_usd to 0.001, then run a new fixture ID using --policy ./tight-constitution.json. The expected result is BLOCKED_BUDGET and no simulated charge. The numbers represent **reserved estimates**, not actual Anthropic charges.

### Experiment: prove that the model cannot self-promote

A completed draft cannot itself earn trusted status. A human must explicitly audit each unique run. The example policy illustrates 20 audited runs at >=95% pass rate, but **these numbers are learning thresholds, not production safety guidance**. A failed audit revokes eligibility and needs human investigation. Even eligible demo tasks cannot post or spend money.

### Architecture

- **Planner:** pure function emitting task intent and references, no tools.
- **Worker:** deterministic draft writer, operating on fictional structured records.
- **Verifier:** independently compares quotes, source IDs, coverage and policy.
- **Gate:** checks permitted task types, estimated daily spend and no external actions.
- **Human review:** explicit audit command, with recorded reviewer label.
- **Monitor:** rechecks saved evidence only; does not visit external systems.

In a real Agentic OS each role needs its own scoped identity or sandbox, provenance-aware durable storage, logging, hard API-call admission controls, incident response, and rate/cost reconciliation with the provider. This demo intentionally does not implement those.

## Connecting actual Claude safely

1. Start with **read-only** sources and draft-only outputs.
2. Replace execute_draft with a separately isolated, narrowly scoped model adapter that returns a typed output and real token usage. Do not give it shell access or production credentials by default.
3. Add hard per-request max_tokens plus your own admission controller with atomic usage reservations and periodic reconciliation to actual provider billing. API task_budget is **advisory**, not a hard spend limit; it is not supported on Claude Code or Cowork surfaces.
4. Keep the verifier's source access and evidence checks independent of the worker. Store signed or otherwise access-controlled events for audit.
5. Check the model, tool and pricing documentation on the day you deploy. As of Oct 25, 2026, claude-fable-5-1 is a higher-cost option; start with less expensive evaluated models for ordinary steps.
6. Require explicit human permission before connecting email, payment, publishing, deployment or destructive file operations.

Official references:
- https://platform.claude.com/docs/en/models/overview
- https://platform.claude.com/docs/en/about-claude/pricing
- https://platform.claude.com/docs/en/build-with-claude/task-budgets
- https://platform.claude.com/docs/en/build-with-claude/prompt-caching

## 30-day learning rollout

| Window | Outcome | Evidence |
|---|---|---|
| Days 1–7 | Define one loop and no-write policy | Baseline, approval map, budget estimate |
| Days 8–14 | Run supervised examples | Reviewer notes, pass/fail cases |
| Days 15–21 | Stress-test missing, hostile and contradictory inputs | Exceptions, repairs, net work |
| Days 22–30 | Decide go, hold or stop | Cost per accepted result and human sign-off |

**License:** Original AI Teachers training example. Free to adapt for learning. Supplied as-is without operational, financial, legal or security guarantees.