Step-by-step path from install to a reviewable session receipt. Full doc map: INDEX.md. For membrane detail see using-aura.md; for terms see concepts.md.
git clone https://github.com/ARPAHLS/aura.git
cd aura
python -m venv .venv
# Windows: .venv\Scripts\activate
pip install -e ".[dev]"Confirm the CLI and resolved paths:
aura version
aura config show
aura paths| Path | Default | Override |
|---|---|---|
| Agent profiles | {AURA_HOME}/agents/ |
AURA_HOME env or aura --home |
| Session exports | {AURA_HOME}/sessions/ |
same |
| Project storage | global ~/.aura/ |
aura paths set-storage project + aura.project.yaml |
Use a dedicated home for experiments: AURA_HOME=/tmp/aura-demo aura paths.
AURA is the coat around your loop — not the loop itself.
| Posture | You want | Typical wiring |
|---|---|---|
| Audit (loose) | Record what happened; rules optional | spectrum.level: low or default emit-only — example 08 |
| Prescriptive (tight) | Declared steps, gates, conformance on close | spectrum.level: mid/high + sequencer + tool host + rules + CI receipt check |
| Tailored | Observers + full bind | spectrum.level: full + Monitor/Break/Limit — example 07, example 10 |
At high / full, profiles with a spectrum block also default to verified operator required at session open (#73) — configure an IdP adapter or set spectrum.identity_required: false.
→ using-aura.md — Choose a posture · aura-levels.md
Stack-specific bodies (Ollama, OpenAI, Skillware registry) live under integrations/. Core patterns live under examples/.
Create an agent with stable audit anchors:
aura agent create research-bot \
--ref acme/research-bot \
--purpose "Research and draft outreach"| Field | Role |
|---|---|
agent_ref |
Human/CI anchor (tenant/slug) |
aura_id |
Internal ULID (auto unless you set --aura-id) |
policy_version |
Tie runs to a policy snapshot (profile or per-session) |
purpose |
Declared intent — appears in profile and spine |
rules |
Constitution — confirm_before, allow_tools, deny_tools, token limits, capability_scope, schema_check |
variables.schema_refs |
Named JSON Schema specs per tool — auto-wired at spectrum high/full (#78) |
capabilities[] |
Named intents + secret refs (broker injects at egress; never store values) — capabilities.md |
ids |
Your external IDs (company, vendor assistant id) — AURA does not replace them |
ids.operator (optional) |
Human/service principal when using an identity adapter — see integrations/identity |
Update later: aura agent set research-bot --ref acme/research-bot --variable model=gpt-4o-mini.
→ trust-paths.md · concepts.md — Agent
Pick how your loop executes inside the session:
| Body style | When | Entry |
|---|---|---|
| Emit-only | Custom script; you emit spine events yourself | examples/08-emit-only-loop |
| Tool host | Skills/tools at egress; membrane enforces rules | SkillwareHost or any ToolHost — reference-tool-host-capstone.md |
| Sequencer | Declared step order + gates | 04-sequencer-pipeline |
| Stack integration | Ollama / cloud API as body | integrations/README.md |
Minimal SDK pattern (audit posture):
from aura import agent, configure
configure()
ag = agent("research-bot")
with ag.session(mode="script") as run:
run.emit("turn.start", {"input": "hello"})
run.emit("turn.end", {"output": "done", "tokens": 42})
print(run.session_id, run.exports)Run a script under an agent profile:
aura run research-bot path/to/script.pyWhen a rule requires confirmation, satisfy it in code and record the approver:
run.approve(request_id, principal="operator@corp")The principal appears in the audit trail, summary, and OTel export as aura.principal.
CLI after close:
aura logs aura_sess_xxxxxxxxxxxx
aura report show aura_sess_xxxxxxxxxxxx
aura report show aura_sess_xxxxxxxxxxxx --json→ using-aura.md — Session close and export
On session close (default), AURA writes:
| Artifact | Use |
|---|---|
{session_id}.jsonl |
Hash-chained event trail |
{session_id}.summary.json |
Conformance + AuditReport |
{session_id}.otel.jsonl |
Span-style export (on close; refresh with export-otel) |
aura export aura_sess_xxxxxxxxxxxx
aura export-otel aura_sess_xxxxxxxxxxxx
aura verify chain ~/.aura/sessions/aura_sess_xxxxxxxxxxxx.jsonl
aura compare sess_a sess_bInspect verdict (pass / warn / fail), findings, and hash_chain_valid before treating a run as complete. A conformance pass can still warn when the report finds advisory issues.
Fail the job when the hash chain or report verdict is unacceptable:
pytest --ignore=tests/integration
aura verify chain "$SESSION_JSONL" || exit 1
aura report show "$SESSION_ID" --json | jq -e '.audit_report.verdict != "fail"'Use project-scoped storage in CI: AURA_HOME=$RUNNER_TEMP/aura.
Run in order from repo root after pip install -e .:
| Step | Example | Teaches |
|---|---|---|
| 1 | 01-minimal-loop | Audit posture — emit + export |
| 2 | 02-guarded-tools | Rules, approval gates, allow/deny |
| 3 | 03-task-mode | Task mode + complete_goal() |
| 4 | 04-sequencer-pipeline | Prescriptive pipeline + mock host |
| 5 | 05-skillware-skill-types | ToolHost + three skill categories |
| 6 | 06-skillware-sequencer-chain | Declarative chain + conditional when |
| 7 | 07-observer-presets | Monitor + Break + Limit; spectrum.services[] wiring |
| 8 | 08-emit-only-loop | Loose coat — no tool host |
| 9 | 09-audit-pipeline | Export slice — report, compare, OTel assert, verify |
| 10 | 10-observer-metrics-snapshot | Tailored coat — observer metrics snapshot |
| 11 | 11-scheduled-agent-slo | Goal drift + schedule SLO — nickel cron north star |
| 12 | 12-escalation-playbooks | Escalation playbooks — triggers + nudge/pause/email/custom |
| 14 | 14-capability-broker | Named intents, secret refs, egress inject (#48) |
Capstone checklist: reference-tool-host-capstone.md.
Not required for first successful run:
- Run auth / gatekeeper coat — GH #56
Goals and schedules — shipped via example 11 and goal_drift / schedule_slo presets (#46).
Escalation playbooks — example 12; profile escalations[] (#47).
Capability broker — example 14; profile capabilities[] (#48).
- getting-started.md — install snippets
- using-aura.md — SDK, CLI, membrane
- integrations/README.md — pick your stack
- INDEX.md — full doc map