adk-perseus-context 0.1.1

Deterministic live context for Google ADK agents — compiled by Perseus, injected as system instruction.

ADK Perseus Context

Deterministic live context for Google ADK agents — compiled by 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 — 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

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:

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)

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:

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:

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 for the backing context engine.