Self‑Aware Agent (SAA)

SAA is a Python CLI project exploring a simple idea: an agent should manage its own context.

Instead of blindly injecting all chat history, tool schemas, and skill docs into every model call, SAA treats context as an inventory:

• everything has provenance (where it came from)
• everything has a cost (token budget)
• inclusion is intentional (policy + justification)

Start here:

• docs/SPIRIT.md — the “why” and design principles
• docs/IMPLEMENTATION_PLAN.md — concrete milestones + CLI surface
• docs/FRAMEWORK_EVALUATION.md — framework tradeoffs for this goal
• docs/RELATED_WORK.md — similar work and references

Local setup (conda)

This repo uses a local conda environment at ./env (do not commit it).

conda activate ./env
python -m pip install -e ".[openai]"
saa init
saa doctor

If you just want to smoke-test the scaffold without installing:

PYTHONPATH=src python3 -m saa doctor

Run with OpenAI

Set your API key and run a task:

cp .env.example .env
# edit .env, then:
saa run "Summarize docs/SPIRIT.md in 5 bullets"

Environment variables (loaded automatically from ./.env if present):

• SAA_API_KEY (recommended) or OPENAI_API_KEY
• SAA_ENDPOINT / SAA_BASE_URL (for OpenAI-compatible providers) or OPENAI_BASE_URL
• SAA_MODEL or OPENAI_MODEL
• SAA_DEBUG (set 1/true/on) to print tool calls and context-pool snapshots to stderr
• SAA_TIMEOUT_S (default: 30) and SAA_MAX_RETRIES (default: 0) to fail fast on bad endpoints

Note: SAA uses the Responses API tool loop by default, and automatically falls back to Chat Completions tool-calling on providers that 404 on /responses.

Use --dry-run to inspect the exact prompt payload (including selected context ids) without making a network call.

What exists today

The current code is a scaffold: it implements a minimal “context registry” and a deterministic selection report so the design can be exercised end-to-end before adding an LLM backend.