Metadata-Version: 2.5
Name: agnara
Version: 0.1.0a3
Summary: Capability-first, transport-neutral execution kernel for Agnara.
Project-URL: Homepage, https://github.com/Blandskron/agnara
Project-URL: Repository, https://github.com/Blandskron/agnara
Author-email: Agnara Maintainers <maintainers@agnara.dev>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# agnara

> **Capability-native Python for the agentic era.**

Agnara is a Python 3.14-native capability framework for services meant to be
consumed by humans, applications and AI agents without making HTTP the centre
of the architecture. A capability is declared once, with its effects, risk and
confirmation requirements, and later exposed through whichever protocol the
caller needs.

This distribution is `agnara`, the capability-first, transport-neutral
execution kernel: the capability model, registry, execution context,
dependency graph, policies, execution planning and canonical errors. It
depends on nothing but the standard library.

## Status: alpha

`0.1.0a3` is the integration alpha, following the first published version
`0.1.0a2`. It adds protocol-neutral introspection, discovery filtering and
stronger telemetry contracts. Publication of this version is pending until
the release workflow completes. It is **not
production-ready**, the public API may change without a deprecation cycle, and
it makes no claim of protocol conformance, benchmark leadership or security
guarantees.

## Install

```bash
pip install agnara==0.1.0a3
```

Requires CPython 3.14 or newer.

## Quick start

```python
import asyncio

from agnara import Agnara, Risk, StandardEffect
from agnara.core.di import DIContainer, DIRegistry
from agnara.execution import (
    ExecutionContext,
    ExecutionPlan,
    Invocation,
    invoke_result,
)

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) -> str:
    return f"refunded {amount_cents} cents for {payment_id}"


async def main() -> None:
    capabilities = app.compile()
    dependencies = DIRegistry()
    plan = ExecutionPlan.compile(capabilities["billing.refund"], dependencies)

    outcome = await invoke_result(
        plan,
        ExecutionContext(
            Invocation(
                capability_id=plan.definition.id,
                payload={"payment_id": "pay_123", "amount_cents": 2500},
                metadata={},
            ),
            DIContainer(dependencies),
        ),
    )
    print(outcome)


asyncio.run(main())
```

The declared function is returned unchanged, so it stays directly callable and
directly testable. Registration is a side effect on the application, not a
transformation of the function.

## What this release includes

- capability declaration and a deterministic, freezable registry;
- stable capability identity, plus effect, risk, idempotency and confirmation
  metadata;
- a schema port with a standard-library adapter and compiled per-parameter
  input validation;
- dependency injection with compile-time graph validation and scoped
  resolution;
- execution plans, direct invocation and optional monotonic deadlines;
- protocol-neutral policies, principals and scope evaluation;
- canonical `Success` / `Failure` outcomes with stable failure codes;
- protocol-neutral introspection snapshots and explicit discovery visibility;
- structured execution telemetry hooks with per-invocation identity.

## What it does not include

The HTTP/ASGI, OpenAPI, MCP and CLI adapters exist in the Agnara repository but
are **not** published to PyPI by the `0.1.0a3` workflow. Build them from the
repository when needed. The OpenTelemetry bridge is also repository-only;
events and A2A remain placeholders.

## Frozen value semantics

Core value types such as `CapabilityId` and `CapabilityDefinition` are
immutable and slotted. Assigning or deleting either a declared field or an
unknown attribute raises `dataclasses.FrozenInstanceError`; a typo never
attaches new state and does not leak CPython's internal slots error.

## Confirmation boundary

Capabilities declared with `confirmation="required"` need an
application-provided `ConfirmationVerifier` when their `ExecutionPlan` is
compiled. Each invocation may carry an explicit opaque `ConfirmationEvidence`
on `ExecutionContext`; values in generic invocation metadata are not approval.

The verifier receives the exact capability id, invocation, and principal and
owns authenticity, input canonicalization, expiry, and replay protection.
Missing evidence terminates execution with an interaction request. Rejected
evidence terminates it as forbidden. Both outcomes occur before dependency
construction or handler effects, and `invoke_result()` maps them to stable
protocol-neutral failure codes.

## Telemetry hooks

The core port is `agnara.execution.TelemetryHook`, with synchronous
`on_invocation_start(InvocationStartEvent)` and
`on_invocation_terminal(InvocationTerminalEvent)` callbacks. Register observers
with `ExecutionPlan.compile(definition, registry, hooks=[observer])`; inheriting
from the protocol is optional. Events expose capability, invocation and tracking identity;
terminal events also contain monotonic duration and execution outcome, without
handler inputs, returned payloads or exception objects.

Both plan construction paths copy the hook collection to a tuple. Missing or
non-callable callbacks, coroutine functions and generator functions fail at
startup with `DefinitionError`. This validation is included in `0.1.0a3`. Valid callbacks accept one event, return `None` synchronously
and must not block. Their ordinary exceptions are ignored during execution.

Observers own synchronization of their mutable state and must keep their
callbacks stable after compilation. Tracking IDs are caller-provided and may
repeat; they are not unique span identifiers and should contain no secrets.
Exporter startup, flushing and shutdown belong to adapters, not the core
runtime. The separate `agnara-telemetry` package provides metrics and tracing
hooks over an application-supplied meter and tracer. It is not published to PyPI.

**Migration from 0.1.0a2:** code constructing `InvocationStartEvent` or
`InvocationTerminalEvent` must supply the new required `invocation_id`. Use the
same identity for matching start/terminal events; `tracking_id` is not unique.
Hooks that only read events are unaffected. Plans without hooks skip event
construction entirely.

## Links

- Source, architecture and decision records:
  <https://github.com/Blandskron/agnara>
- Changelog:
  <https://github.com/Blandskron/agnara/blob/main/CHANGELOG.md>
- Architecture:
  <https://github.com/Blandskron/agnara/blob/main/ARCHITECTURE.md>
- Longer example:
  <https://github.com/Blandskron/agnara/blob/main/examples/quickstart.py>

## License

Apache License 2.0.
