agnara
Health Uyari
- License — License: Apache-2.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 5 GitHub stars
Code Gecti
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Python 3.14+ backend capability framework for applications and AI agents. Protocol-neutral business operations with explicit HTTP and MCP adapters, machine-readable contracts, policies and invocation lifecycle.
Agnara
Agnara is a Python capability runtime. Applications define a capability once
and expose it through transport adapters without making HTTP, MCP or another
protocol the semantic source of truth.
Why Agnara
Agnara lets one application capability serve direct Python callers and explicit
transport exposures without putting protocol objects in the business model.
The execution kernel uses only the Python standard library and requires Python
3.14 or newer. The seven official distributions share one version. The
published baseline is 1.0.3; subsequent development changes are recorded underCHANGELOG.md [Unreleased].
pip install "agnara==1.0.3"
Install agnara-http, agnara-mcp, agnara-cli or agnara-telemetry at the
same version when an application uses those surfaces. The published 1.0.3agnara-a2a and agnara-events packages reserve names without runtime APIs.
This checkout adds a provisional A2A surface under
ADR 0099; see the
maturity matrix for its evidence and limitations.
For AI coding agents
Agnara's public documentation is intended for both people and coding agents.
Start with llms.txt, the generated full corpus,
selection guidance, the
official learning path and runnable examples.
The machine index provides versioned topic routing.
The documentation MCP is specified, not deployed.
Copyable project instruction:
Use Agnara 1.0.3 for this project on Python >=3.14. Before writing code, read
the official llms.txt and agent implementation guide. Use public APIs only,
follow official runnable examples, preserve policies and lifecycle, and test
the installed packages. Do not invent framework APIs or assume unreleased
checkout fixes are present in published 1.0.3.
Capability model
- Capabilities are application behaviour; routes and tools are exposures.
- The kernel is transport-neutral and uses only the Python standard library.
- Reflection and dependency graphs compile before invocation.
- Policies, schemas, errors and telemetry use protocol-neutral contracts.
Read VISION.md, PRINCIPLES.md and
ARCHITECTURE.md for the governing model. The supported
imports and compatibility rules are in PUBLIC_API.md and
the generated API reference.
Quick start
import asyncio
from agnara import Agnara, Risk, StandardEffect
from agnara.di import DIContainer, DIRegistry, provider
from agnara.execution import ExecutionContext, ExecutionPlan, Invocation, invoke_result
from agnara import Principal
class Ledger:
def refund(self, payment_id: str, amount_cents: int) -> str:
return f"refunded {amount_cents} cents for {payment_id}"
@provider()
def provide_ledger() -> Ledger:
return Ledger()
app = Agnara("billing")
@app.capability(
description="Refund a captured payment.",
scopes=("billing:write",),
effects=(StandardEffect.FINANCIAL_WRITE,),
risk=Risk.HIGH,
)
def refund(payment_id: str, amount_cents: int, ledger: Ledger) -> str:
return ledger.refund(payment_id, amount_cents)
async def main() -> None:
capabilities = app.compile()
dependencies = DIRegistry()
dependencies.bind(Ledger, provide_ledger)
plan = ExecutionPlan.compile(capabilities["billing.refund"], dependencies)
container = DIContainer(dependencies)
try:
outcome = await invoke_result(
plan,
ExecutionContext(
Invocation(plan.definition.id, {"payment_id": "pay_123", "amount_cents": 2500}, {}),
container,
principal=Principal("quickstart", scopes={"billing:write"}),
),
)
print(outcome)
finally:
await container.aclose()
asyncio.run(main())
The plan evaluates declared scopes before invoking the handler. The principal
comes from the application or host that authenticated the caller. Risk and
effect metadata describe the capability; they do not grant authorization.
Surfaces and limits
| Distribution | Current role |
|---|---|
agnara |
Capability registry, compiled plans, DI, policy, canonical outcomes, streaming, direct idempotency and introspection. |
agnara-http |
ASGI HTTP, OpenAPI, documentation UIs, filtered discovery, Explorer and SSE. |
agnara-mcp |
Version-pinned MCP tool projection, authorization and invocation for the documented subset. |
agnara-cli |
Project/app scaffolding, inspection, graph, context and OpenAPI export commands. |
agnara-telemetry |
Explicit OpenTelemetry metrics and tracing hooks; the application owns its SDK and exporter. |
agnara-a2a |
Unreleased provisional complete-result profile; published 1.0.3 has no runtime API. |
agnara-events |
Reserved namespace with no public runtime API. |
Compiled snapshots and policies remain transport neutral. Streaming is pull
based in the kernel and has an HTTP SSE projection; it is not projected by the
MCP or reserved packages. Idempotency is explicit for direct complete-result
calls and is not an HTTP or MCP request-key feature. Confirmation requires an
application verifier. Introspection applies visibility rules before exporting
data; hiding an operation in a browser UI is not authorization.
Agnara can run standalone, inside a host framework, or beside host routes.
The host keeps ownership of authentication, routing, persistence and lifecycle.
See interoperability, security and
the threat model for evidence and limits.
Operations and documentation
The schema contracts guide demonstrates strict
Python input, explicit JSON conversion and declared output validation.
The dependency injection guide demonstrates explicit
bindings, scoped reuse and owned generator resource cleanup.
The invocation telemetry guide demonstrates paired events,
correlation identity, runtime outcomes and observer ownership.
The deadline and cancellation guide demonstrates monotonic
budgets, cancellation propagation and owned resource cleanup.
The nested invocation guide provides a runnable
example of calling another capability while enforcing each capability's scopes.
The direct idempotency guide demonstrates explicit
success reuse, conflicts and per-principal authorization.
The confirmation guide demonstrates verifier-backed
approval evidence and authorization before effects.
The MCP tools guide demonstrates discovery and invocation
through the official client, with scope denial and resource cleanup.
The HTTP SSE guide demonstrates typed events, failure
boundaries and resource cleanup with a server-free ASGI example.
The introspection guide demonstrates per-viewer
discovery publication and independent invocation authorization.
The CLI and scaffolding guide covers generated projects.
The container guide covers the reference runtime and
digest pinning. Documentation map identifies the
owner of each current contract. Public API stability is governed bydocs/public-api.json; the quality gates and
contribution guide describe verification and review.
Development
Read the Code of Conduct and
Accessibility Statement for community expectations,
known accessibility limits and public or private reporting options.
uv sync
uv run ruff check .
uv run ruff format --check .
uv run ty check
uv run pytest
Publication is a reviewed dispatch from main. The workflow verifies the
complete distribution set before it creates a tag; see
docs/MAINTAINERS_RELEASE.md.
The reference container is published to GHCR and Docker Hub separately from
the Python distributions. PyPI is the Python package index; immutable release
tags and the mutable :edge image have different purposes. See the container
guide before pinning a deployment.
License
Apache-2.0. See LICENSE.
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi