Historical Reference Application #001
Agnara: 0.1.0a2 Python: 3.14+ Interface: CLI Focus: Capabilities + Validation + Canonical Execution
A small, intentionally simple application that preserves and demonstrates the capabilities available in the early public releases of the Agnara framework.
Agnara Task Intelligence is the first project in the Agnara Historical Reference Application series (Historical Reference Application #001). It preserves a reproducible example of building against the public agnara==0.1.0a2 PyPI release.
Historical Reference Application: #001
Application: Agnara Task Intelligence
Application version: 0.1.0
Agnara version: 0.1.0a2
Python requirement: >=3.14
Initially validated interpreter: CPython 3.14.4
Agnara source: PyPI
Primary capability: task_intelligence.analyze_task
Primary interface: CLI
This reference application demonstrates the following core Agnara capabilities:
- Capability registration and metadata (
scopes,risk,idempotent) - Schema inference from Python type hints
- Execution plan compilation
- Canonical invocation and execution context
- Canonical
SuccessandFailureoutcomes - Native input validation (e.g., rejecting an
intwhen astris expected) - Completely transport-agnostic execution
The application separates the human interface (CLI) from capability execution:
flowchart TD
CLI["CLI input"] --> INV["Invocation"]
INV --> CTX["ExecutionContext"]
CTX --> PLAN["ExecutionPlan"]
PLAN --> CAP["task_intelligence.analyze_task"]
CAP --> RESULT["TaskAnalysis"]
RESULT --> OUTCOME["Success / Failure"]
This project explicitly reflects the scope of Agnara 0.1.0a2. It does not demonstrate HTTP, MCP, A2A, or Event transports, as those features are out of scope for this specific historical baseline.
- Python >= 3.14 (tested with CPython 3.14.4)
- Pip
On Windows, ensuring you use the correct Python version (since multiple versions might exist):
py -3.14 --version
py -3.14 -m venv .venv
.venv\Scripts\activate
python --version
python -m pip install --upgrade pip
pip install -r requirements.txt
python app.pyOn Linux/macOS:
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txtpython app.pyLow Risk Task:
Describe a software task: Create a contact page
Output will indicate complexity: low, risk: low, and requires_review: False.
High Risk Task:
Describe a software task: Implement OAuth authentication, database migration and payment security
Output will indicate complexity: high, risk: high, and requires_review: True.
If you programmatically pass an invalid payload like {"task": 12345} instead of a string, Agnara natively handles it and returns a canonical failure:
Failure code: invalid_input
Message: expected str, got int
- Python Annotation: Type hints define the expected data.
- Agnara Schema: Agnara infers the schema from the annotations.
- ExecutionPlan: The app compiles the capabilities into a plan.
- Invocation: A payload is sent to the capability.
- Validation: Agnara validates the payload against the schema.
- Capability: The logic is executed.
- Success / Failure: A canonical result is returned.
This repository intentionally preserves the Agnara 0.1.0a2 core execution baseline.
Its scope is limited to capability registration, schema inference, execution plans, canonical invocation, native input validation, metadata, scopes, risk, and Success/Failure outcomes.
More advanced Agnara concepts are demonstrated in subsequent Historical Reference Applications as the framework evolves.
This repository is intentionally kept focused rather than continuously upgraded to newer Agnara capabilities.
See AGENTS.md for rules on maintaining this repository with AI coding agents.
See CONTRIBUTING.md.
See SECURITY.md.
Licensed under the Apache License 2.0.