adk-perseus-context 0.1.0__tar.gz

adk_perseus_context-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install
+        # Tests stub the `perseus` module, so the runtime perseus-ctx dependency
+        # is installed --no-deps-style: only google-adk + the test tooling are
+        # needed to run the suite.
+        run: |
+          pip install google-adk pytest pytest-asyncio
+          pip install -e . --no-deps
+      - name: Test
+        run: pytest -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build
+        run: pip install build==1.2.2.post1
+
+      - name: Build
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/adk-perseus-context
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

adk_perseus_context-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.env
+.pytest_cache/

adk_perseus_context-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Perseus Computing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adk_perseus_context-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+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.

adk_perseus_context-0.1.0/README.md

@@ -0,0 +1,140 @@
+# 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.

adk_perseus_context-0.1.0/adk_perseus_context/__init__.py

@@ -0,0 +1,28 @@
+"""adk-perseus-context — deterministic live context for Google ADK agents.
+
+Perseus (github.com/Perseus-Computing-LLC/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 wraps
+that compiler as an ADK extension point so the compiled context lands in your
+agent's system instruction on every model call.
+
+Two entry points:
+
+- ``PerseusContextPlugin`` — a ``BasePlugin`` that injects a Perseus context
+  across every agent in a ``Runner``.
+- ``perseus_before_model_callback`` — a per-agent ``before_model_callback``.
+
+Both build on Perseus's Context Adapter SDK (``perseus.compile_context``,
+perseus-ctx >= 1.0.10).
+"""
+
+from .callback import perseus_before_model_callback
+from .plugin import STATE_SOURCE, STATE_WORKSPACE, PerseusContextPlugin
+
+__all__ = [
+    "PerseusContextPlugin",
+    "perseus_before_model_callback",
+    "STATE_SOURCE",
+    "STATE_WORKSPACE",
+]

adk_perseus_context-0.1.0/adk_perseus_context/_resolve.py

@@ -0,0 +1,73 @@
+"""Resolve a Perseus source to its compiled context string.
+
+This is the one place that touches Perseus. It is imported lazily by the plugin
+and the callback so that merely importing ``adk_perseus_context`` never requires
+Perseus to be present until a context is actually compiled.
+
+Perseus owns deterministic context assembly; everything here is a thin, fail-safe
+wrapper around its public ``compile_context`` API (Context Adapter SDK, Perseus
+>= 1.0.10). If Perseus is older and only exposes ``render_source``, an inline
+source still works via a minimal fallback.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+logger = logging.getLogger("adk_perseus_context")
+
+
+class PerseusUnavailableError(RuntimeError):
+    """Raised when the ``perseus`` package cannot be imported."""
+
+
+def _import_perseus():
+    try:
+        import perseus  # noqa: PLC0415 - lazy by design
+    except Exception as e:  # pragma: no cover - exercised only without the dep
+        raise PerseusUnavailableError(
+            "adk-perseus-context requires the 'perseus-ctx' package "
+            "(>=1.0.10 for the Context Adapter SDK). Install it with "
+            "`pip install perseus-ctx`."
+        ) from e
+    return perseus
+
+
+def compile_source(
+    source: str,
+    *,
+    cfg: Optional[dict[str, Any]] = None,
+    workspace: Optional[str] = None,
+) -> str:
+    """Compile a Perseus ``source`` (inline ``@perseus`` text or a file path).
+
+    Returns the deterministic compiled context string. Raises
+    :class:`PerseusUnavailableError` if Perseus is not installed; lets any
+    Perseus compile error propagate so callers can decide whether to fail open.
+    """
+    perseus = _import_perseus()
+
+    compile_context = getattr(perseus, "compile_context", None)
+    if compile_context is not None:
+        return compile_context(source, cfg=cfg, workspace=workspace)
+
+    # Fallback for Perseus < 1.0.10 (no Context Adapter SDK): inline sources only.
+    render_source = getattr(perseus, "render_source", None)
+    if render_source is None:  # pragma: no cover - extremely old perseus
+        raise PerseusUnavailableError(
+            "Installed 'perseus-ctx' exposes neither compile_context nor "
+            "render_source; upgrade to perseus-ctx>=1.0.10."
+        )
+    is_inline = isinstance(source, str) and source.lstrip().startswith("@perseus")
+    if not is_inline:
+        raise PerseusUnavailableError(
+            "File-path sources need perseus-ctx>=1.0.10 (compile_context). "
+            "Upgrade perseus-ctx, or pass an inline '@perseus ...' source."
+        )
+    config = cfg
+    if config is None:
+        import copy  # noqa: PLC0415
+
+        config = copy.deepcopy(getattr(perseus, "DEFAULT_CONFIG", {}))
+    return render_source(source, config, workspace)

adk_perseus_context-0.1.0/adk_perseus_context/callback.py

@@ -0,0 +1,62 @@
+"""``perseus_before_model_callback`` — a per-agent ``before_model_callback``.
+
+Use this when you want a Perseus context applied to a single agent rather than
+every agent in a Runner:
+
+    from google.adk.agents import Agent
+    from adk_perseus_context import perseus_before_model_callback
+
+    agent = Agent(
+        name="assistant",
+        model="gemini-flash-latest",
+        before_model_callback=perseus_before_model_callback("context.perseus"),
+    )
+
+For a Runner-wide context across many agents, use ``PerseusContextPlugin``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from ._resolve import PerseusUnavailableError, compile_source
+
+logger = logging.getLogger("adk_perseus_context")
+
+
+def perseus_before_model_callback(
+    source: str,
+    *,
+    cfg: Optional[dict[str, Any]] = None,
+    workspace: Optional[str] = None,
+    fail_open: bool = True,
+):
+    """Build an agent-level ``before_model_callback`` that injects a Perseus context.
+
+    Args:
+        source: Inline ``@perseus`` source string, or a path to a ``.perseus`` file.
+        cfg: Optional Perseus config dict (defaults to Perseus's ``DEFAULT_CONFIG``).
+        workspace: Workspace root for relative ``@include`` paths.
+        fail_open: If ``True`` (default), a missing Perseus install or compile
+            error logs a warning and lets the request proceed; if ``False``, it
+            propagates.
+
+    Returns:
+        An async ``(callback_context, llm_request)`` callable suitable for
+        ``Agent(before_model_callback=...)``.
+    """
+
+    async def _callback(callback_context, llm_request):
+        try:
+            context = compile_source(source, cfg=cfg, workspace=workspace)
+        except (PerseusUnavailableError, Exception) as e:  # noqa: BLE001
+            if fail_open:
+                logger.warning("Perseus context injection skipped: %s", e)
+                return None
+            raise
+        if context and context.strip():
+            llm_request.append_instructions([context])
+        return None
+
+    return _callback

adk_perseus_context-0.1.0/adk_perseus_context/plugin.py

@@ -0,0 +1,78 @@
+"""``PerseusContextPlugin`` — inject a deterministically compiled Perseus context
+into every model request of an ADK ``Runner``.
+
+A Perseus source (inline ``@perseus`` text or a path to a ``.perseus`` file) is
+compiled with :func:`perseus.compile_context` and appended to the request's
+system instruction via ``LlmRequest.append_instructions`` — the supported,
+type-safe way to add system instructions in ADK.
+
+Use this when you want one context applied across all agents driven by a Runner.
+For a single agent, prefer :func:`adk_perseus_context.perseus_before_model_callback`.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from google.adk.plugins import BasePlugin
+
+from ._resolve import PerseusUnavailableError, compile_source
+
+logger = logging.getLogger("adk_perseus_context")
+
+# Session-state keys for per-session overrides (read from callback_context.state).
+STATE_SOURCE = "_perseus_source"
+STATE_WORKSPACE = "_perseus_workspace"
+
+
+class PerseusContextPlugin(BasePlugin):
+    """Compile a Perseus context once per model request and inject it.
+
+    Args:
+        source: Inline ``@perseus`` source string, or a path to a ``.perseus``
+            file. May be ``None`` if every session supplies its own source via
+            the ``_perseus_source`` state key.
+        cfg: Optional Perseus config dict. Defaults to Perseus's ``DEFAULT_CONFIG``.
+        workspace: Workspace root for resolving relative ``@include`` paths. For a
+            file source it defaults to the file's directory.
+        fail_open: If ``True`` (default), a missing Perseus install or a compile
+            error logs a warning and lets the request proceed without injected
+            context. If ``False``, the error propagates.
+        name: Unique plugin identifier within the Runner.
+    """
+
+    def __init__(
+        self,
+        source: Optional[str] = None,
+        *,
+        cfg: Optional[dict[str, Any]] = None,
+        workspace: Optional[str] = None,
+        fail_open: bool = True,
+        name: str = "perseus_context",
+    ) -> None:
+        super().__init__(name=name)
+        self.source = source
+        self.cfg = cfg
+        self.workspace = workspace
+        self.fail_open = fail_open
+
+    async def before_model_callback(self, *, callback_context, llm_request):
+        state = getattr(callback_context, "state", None) or {}
+        source = state.get(STATE_SOURCE, self.source)
+        workspace = state.get(STATE_WORKSPACE, self.workspace)
+        if not source:
+            return None
+
+        try:
+            context = compile_source(source, cfg=self.cfg, workspace=workspace)
+        except (PerseusUnavailableError, Exception) as e:  # noqa: BLE001
+            if self.fail_open:
+                logger.warning("Perseus context injection skipped: %s", e)
+                return None
+            raise
+
+        if context and context.strip():
+            llm_request.append_instructions([context])
+        # Return None so the model call proceeds normally.
+        return None

adk_perseus_context-0.1.0/examples/context.perseus

@@ -0,0 +1,5 @@
+@perseus
+
+You are a workspace-aware assistant for the Perseus Computing demo project.
+
+Be concise. Cite file paths when you reference code.

adk_perseus_context-0.1.0/examples/runner_plugin_example.py

@@ -0,0 +1,75 @@
+"""Runnable example: a Perseus-compiled context injected into an ADK agent.
+
+Two ways to wire it up are shown:
+
+  1. PerseusContextPlugin  — one context across every agent in a Runner.
+  2. perseus_before_model_callback — one context for a single agent.
+
+Set GOOGLE_API_KEY (or configure another ADK model provider) before running:
+
+    pip install adk-perseus-context
+    python examples/runner_plugin_example.py
+"""
+
+import asyncio
+import os
+
+from google.adk.agents import Agent
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.genai import types
+
+from adk_perseus_context import PerseusContextPlugin, perseus_before_model_callback
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+CONTEXT = os.path.join(HERE, "context.perseus")
+
+MODEL = "gemini-flash-latest"
+
+
+def build_runner_with_plugin() -> Runner:
+    """Inject the Perseus context across all agents via a Runner-wide plugin."""
+    agent = Agent(name="assistant", model=MODEL, instruction="Help the user.")
+    return Runner(
+        agent=agent,
+        app_name="perseus_ctx_app",
+        session_service=InMemorySessionService(),
+        plugins=[PerseusContextPlugin(CONTEXT)],
+    )
+
+
+def build_runner_with_callback() -> Runner:
+    """Inject the Perseus context for a single agent via before_model_callback."""
+    agent = Agent(
+        name="assistant",
+        model=MODEL,
+        instruction="Help the user.",
+        before_model_callback=perseus_before_model_callback(CONTEXT),
+    )
+    return Runner(
+        agent=agent,
+        app_name="perseus_ctx_app",
+        session_service=InMemorySessionService(),
+    )
+
+
+async def main() -> None:
+    runner = build_runner_with_plugin()  # or build_runner_with_callback()
+    session = await runner.session_service.create_session(
+        app_name="perseus_ctx_app", user_id="user"
+    )
+    msg = types.Content(role="user", parts=[types.Part.from_text(text="Who are you?")])
+    async for event in runner.run_async(
+        user_id="user", session_id=session.id, new_message=msg
+    ):
+        if event.content and event.content.parts:
+            for part in event.content.parts:
+                if part.text:
+                    print(part.text)
+
+
+if __name__ == "__main__":
+    if not os.environ.get("GOOGLE_API_KEY"):
+        print("Set GOOGLE_API_KEY to run this example against Gemini.")
+    else:
+        asyncio.run(main())

adk_perseus_context-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "adk-perseus-context"
+version = "0.1.0"
+authors = [
+    { name = "Thomas Connally", email = "51974392+tcconnally@users.noreply.github.com" },
+]
+description = "Deterministic live context for Google ADK agents — compiled by Perseus, injected as system instruction."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "google-adk>=1.0.0",
+    "perseus-ctx>=1.0.10",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio"]
+
+[project.urls]
+Homepage = "https://github.com/Perseus-Computing-LLC/adk-perseus-context"
+Repository = "https://github.com/Perseus-Computing-LLC/adk-perseus-context"
+"Bug Tracker" = "https://github.com/Perseus-Computing-LLC/adk-perseus-context/issues"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

adk_perseus_context-0.1.0/tests/test_plugin.py

@@ -0,0 +1,136 @@
+"""Tests for adk-perseus-context.
+
+These tests stub the ``perseus`` package with a fake ``compile_context`` so they
+run without perseus-ctx installed, but exercise the *real* ADK ``LlmRequest`` and
+its ``append_instructions`` injection path.
+"""
+
+import sys
+import types
+
+import pytest
+from google.adk.models import LlmRequest
+
+from adk_perseus_context import (
+    PerseusContextPlugin,
+    perseus_before_model_callback,
+)
+from adk_perseus_context import _resolve
+
+
+@pytest.fixture
+def fake_perseus(monkeypatch):
+    """Install a fake ``perseus`` module exposing ``compile_context``."""
+    mod = types.ModuleType("perseus")
+
+    def compile_context(source, cfg=None, workspace=None, max_tier=3):
+        # Echo the inputs so assertions can verify they were threaded through.
+        ws = f"|ws={workspace}" if workspace else ""
+        return f"COMPILED::{source}{ws}"
+
+    mod.compile_context = compile_context
+    monkeypatch.setitem(sys.modules, "perseus", mod)
+    return mod
+
+
+class _Ctx:
+    """Minimal stand-in for ADK's CallbackContext (only ``.state`` is read)."""
+
+    def __init__(self, state=None):
+        self.state = state or {}
+
+
+@pytest.mark.asyncio
+async def test_plugin_injects_into_system_instruction(fake_perseus):
+    plugin = PerseusContextPlugin("@perseus\n\nhello")
+    req = LlmRequest()
+    result = await plugin.before_model_callback(
+        callback_context=_Ctx(), llm_request=req
+    )
+    assert result is None  # never short-circuits the model call
+    assert req.config.system_instruction == "COMPILED::@perseus\n\nhello"
+
+
+@pytest.mark.asyncio
+async def test_plugin_appends_to_existing_instruction(fake_perseus):
+    plugin = PerseusContextPlugin("@perseus\n\nhello")
+    req = LlmRequest()
+    req.config.system_instruction = "preexisting"
+    await plugin.before_model_callback(callback_context=_Ctx(), llm_request=req)
+    assert req.config.system_instruction == "preexisting\n\nCOMPILED::@perseus\n\nhello"
+
+
+@pytest.mark.asyncio
+async def test_session_state_override(fake_perseus):
+    plugin = PerseusContextPlugin("@perseus\n\ndefault")
+    req = LlmRequest()
+    ctx = _Ctx(
+        {"_perseus_source": "@perseus\n\noverride", "_perseus_workspace": "/proj"}
+    )
+    await plugin.before_model_callback(callback_context=ctx, llm_request=req)
+    assert req.config.system_instruction == "COMPILED::@perseus\n\noverride|ws=/proj"
+
+
+@pytest.mark.asyncio
+async def test_no_source_is_noop(fake_perseus):
+    plugin = PerseusContextPlugin()  # no static source, no state source
+    req = LlmRequest()
+    await plugin.before_model_callback(callback_context=_Ctx(), llm_request=req)
+    assert req.config.system_instruction is None
+
+
+@pytest.mark.asyncio
+async def test_empty_compiled_context_is_noop(monkeypatch):
+    mod = types.ModuleType("perseus")
+    mod.compile_context = lambda *a, **k: "   "  # whitespace only
+    monkeypatch.setitem(sys.modules, "perseus", mod)
+    plugin = PerseusContextPlugin("@perseus\n\n")
+    req = LlmRequest()
+    await plugin.before_model_callback(callback_context=_Ctx(), llm_request=req)
+    assert req.config.system_instruction is None
+
+
+@pytest.mark.asyncio
+async def test_fail_open_when_perseus_unavailable(monkeypatch):
+    # Force the import to fail.
+    monkeypatch.setitem(sys.modules, "perseus", None)
+    plugin = PerseusContextPlugin("@perseus\n\nhello", fail_open=True)
+    req = LlmRequest()
+    result = await plugin.before_model_callback(
+        callback_context=_Ctx(), llm_request=req
+    )
+    assert result is None
+    assert req.config.system_instruction is None
+
+
+@pytest.mark.asyncio
+async def test_fail_closed_raises(monkeypatch):
+    def boom(*a, **k):
+        raise RuntimeError("compile blew up")
+
+    mod = types.ModuleType("perseus")
+    mod.compile_context = boom
+    monkeypatch.setitem(sys.modules, "perseus", mod)
+    plugin = PerseusContextPlugin("@perseus\n\nhello", fail_open=False)
+    req = LlmRequest()
+    with pytest.raises(RuntimeError, match="compile blew up"):
+        await plugin.before_model_callback(callback_context=_Ctx(), llm_request=req)
+
+
+@pytest.mark.asyncio
+async def test_callback_factory_injects(fake_perseus):
+    cb = perseus_before_model_callback("@perseus\n\nfrom-callback")
+    req = LlmRequest()
+    result = await cb(_Ctx(), req)  # agent-level callback is positional
+    assert result is None
+    assert req.config.system_instruction == "COMPILED::@perseus\n\nfrom-callback"
+
+
+def test_resolve_fallback_to_render_source(monkeypatch):
+    """Perseus < 1.0.10 (render_source only) still works for inline sources."""
+    mod = types.ModuleType("perseus")
+    mod.DEFAULT_CONFIG = {}
+    mod.render_source = lambda src, cfg, ws: f"RENDERED::{src}"
+    monkeypatch.setitem(sys.modules, "perseus", mod)
+    out = _resolve.compile_source("@perseus\n\nx")
+    assert out == "RENDERED::@perseus\n\nx"