Metadata-Version: 2.4
Name: adk-perseus-context
Version: 0.1.0
Summary: Deterministic live context for Google ADK agents — compiled by Perseus, injected as system instruction.
Project-URL: Homepage, https://github.com/Perseus-Computing-LLC/adk-perseus-context
Project-URL: Repository, https://github.com/Perseus-Computing-LLC/adk-perseus-context
Project-URL: Bug Tracker, https://github.com/Perseus-Computing-LLC/adk-perseus-context/issues
Author-email: Thomas Connally <51974392+tcconnally@users.noreply.github.com>
License: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: google-adk>=1.0.0
Requires-Dist: perseus-ctx>=1.0.10
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Description-Content-Type: text/markdown

# ADK Perseus Context

Deterministic live context for [Google ADK](https://github.com/google/adk-python)
agents — compiled by [Perseus](https://github.com/Perseus-Computing-LLC/perseus)
and injected straight into your agent's system instruction.

Perseus is an open-source (MIT) **context compiler**. It resolves directives like
`@file`, `@search`, and `@memory` into one deterministic, byte-stable context
string at inference time — **no retrieval index, no embeddings, no LLM
round-trip.** This package wires that compiler into ADK as a first-class
extension point.

> **Perseus is not memory or RAG.** It *assembles* context deterministically.
> For persistent cross-session agent memory, see the companion package
> [`adk-mimir-memory`](https://github.com/Perseus-Computing-LLC/adk-mimir-memory)
> — Perseus and Mimir compose ("own your context" + "own your memory").

## Why a context compiler?

| Approach | Index / embeddings | LLM round-trip | Output stability | Coverage |
|---|---|---|---|---|
| Naive "dump everything" | ❌ | ❌ | Stable | Full, but bloated |
| RAG / vector retrieval | ✅ required | sometimes | Varies per query | Top-k (can miss facts) |
| **Perseus compile** | ❌ none | ❌ none | **Byte-identical** | **Full, deterministic** |

The edge is **determinism + full coverage at a fixed compiled size** — the same
inputs always produce the same context, with no retrieval tax. Less-but-better
context is also a measurable *quality* win, not just a cost one.

## Installation

```bash
pip install adk-perseus-context
```

Requires Python 3.10+, `google-adk>=1.0.0`, and `perseus-ctx>=1.0.10` (the
Context Adapter SDK). Both are pulled in automatically.

## Quick start

### Runner-wide (plugin)

Inject one context across **every** agent driven by a `Runner`:

```python
from google.adk.agents import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from adk_perseus_context import PerseusContextPlugin

agent = Agent(name="assistant", model="gemini-flash-latest", instruction="Help the user.")

runner = Runner(
    agent=agent,
    app_name="my_app",
    session_service=InMemorySessionService(),
    plugins=[PerseusContextPlugin("context.perseus")],  # file path or inline @perseus source
)
```

### Single agent (callback)

```python
from google.adk.agents import Agent
from adk_perseus_context import perseus_before_model_callback

agent = Agent(
    name="assistant",
    model="gemini-flash-latest",
    instruction="Help the user.",
    before_model_callback=perseus_before_model_callback("context.perseus"),
)
```

Either way, the compiled Perseus context is appended to the request's system
instruction (via ADK's `LlmRequest.append_instructions`) on every model call.

## Per-session context

Override the source per session through session state — useful when each user or
task needs a different workspace or directive set:

```python
session = await runner.session_service.create_session(
    app_name="my_app",
    user_id="user",
    state={
        "_perseus_source": "@perseus\n@file AGENTS.md\n@memory deployment",
        "_perseus_workspace": "/path/to/project",
    },
)
```

State keys are exported as `adk_perseus_context.STATE_SOURCE` and
`STATE_WORKSPACE`. A per-session source takes precedence over the static one.

## Inline vs. file sources

`source` is either a path to a `.perseus` file or an inline source string that
starts with `@perseus`:

```python
PerseusContextPlugin("@perseus\n\nYou are a concise assistant. @file README.md")
```

For a file source, the workspace defaults to the file's directory so relative
`@include` / `@file` paths resolve.

## Fail-open by default

If Perseus is missing or a compile raises, the request proceeds **without**
injected context and a warning is logged, so a context problem never takes your
agent down. Pass `fail_open=False` to make such errors propagate instead.

## How it works

```
                       before_model_callback
┌─────────────┐     ┌─────────────────────────┐     ┌──────────────┐
│  ADK Runner │ ──▶ │  PerseusContextPlugin    │ ──▶ │  LlmRequest  │
│  / Agent    │     │  perseus.compile_context │     │  system_     │
└─────────────┘     │  (deterministic, local)  │     │  instruction │
                    └─────────────────────────┘     └──────────────┘
```

The plugin/callback calls `perseus.compile_context(source)` — Perseus's Context
Adapter SDK "resolve once" primitive — and appends the result to the system
instruction. Perseus owns deterministic assembly; ADK owns orchestration.

## Compose with Mimir

Perseus and Mimir are designed to compose: Mimir provides persistent, encrypted
memory; Perseus pulls hot memory into a compiled context via `@memory`
directives. Use `adk-mimir-memory` for the memory backend and this package for
the context layer.

## License

MIT — see [Perseus](https://github.com/Perseus-Computing-LLC/perseus) for the
backing context engine.
