aegis-gateway-sdk 2.0.0a0__tar.gz

aegis_gateway_sdk-2.0.0a0/.gitignore

@@ -0,0 +1,100 @@
+# Node/npm local installs
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-store/
+
+# Local environment files
+.env
+.env.*
+!.env.example
+
+## jj
+.jj
+
+# Codex local configuration
+.codex/
+AGENTS.md
+
+# Claude Flow runtime data
+.claude-flow/data/
+.claude-flow/logs/
+CLAUDE.md
+.claude
+.claude-flow
+
+# MCP
+.mcp.json
+ruvector.db
+
+# ruflo agents
+.agents
+.swarm
+.agentdb
+agentdb.db
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Created by https://www.toptal.com/developers/gitignore/api/visualstudiocode
+# Edit at https://www.toptal.com/developers/gitignore?templates=visualstudiocode
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+.vscode
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+.ionide
+
+### Misc files
+gemma4
+.postman/
+.openclaude/
+postman/
+
+### OpenClaude
+.openclaude-profile.json
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+*.egg
+.venv/
+.uv-cache/
+.tmp/
+.ruff_cache/
+
+# Docker
+.docker/
+
+### Build plans
+BUILD_PLAN.md
+CLAUDE.md
+PROJECT_SPEC.md
+AMEND_PLAN.md
+SOURCE_OF_TRUTH.md
+repo-seed/
+.import_linter_cache/
+site/
+
+# End of https://www.toptal.com/developers/gitignore/api/visualstudiocode

aegis_gateway_sdk-2.0.0a0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: aegis-gateway-sdk
+Version: 2.0.0a0
+Summary: Aegis v2 — first-party Python SDK (sync + async clients).
+Project-URL: Homepage, https://github.com/e-choness/aegis
+Project-URL: Repository, https://github.com/e-choness/aegis
+Project-URL: Issues, https://github.com/e-choness/aegis/issues
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2

aegis_gateway_sdk-2.0.0a0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "aegis-gateway-sdk"
+version = "2.0.0a0"
+description = "Aegis v2 — first-party Python SDK (sync + async clients)."
+license = { text = "MIT" }
+requires-python = ">=3.12"
+
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2",
+]
+
+[project.urls]
+Homepage = "https://github.com/e-choness/aegis"
+Repository = "https://github.com/e-choness/aegis"
+Issues = "https://github.com/e-choness/aegis/issues"
+
+[tool.uv.sources]
+# No workspace dependencies — the SDK is standalone.
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aegis_sdk"]

aegis_gateway_sdk-2.0.0a0/src/aegis_sdk/__init__.py

@@ -0,0 +1,16 @@
+"""Aegis v2 Python SDK — sync and async clients."""
+
+from __future__ import annotations
+
+from aegis_sdk.client import AegisClient, AsyncAegisClient
+from aegis_sdk.models import ResumeResponse, RunCreateResponse, RunStatusResponse
+
+__all__ = [
+    "AegisClient",
+    "AsyncAegisClient",
+    "ResumeResponse",
+    "RunCreateResponse",
+    "RunStatusResponse",
+]
+
+__version__ = "2.0.0a0"

aegis_gateway_sdk-2.0.0a0/src/aegis_sdk/client.py

@@ -0,0 +1,217 @@
+"""Sync and async Aegis API clients."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+import httpx
+
+from aegis_sdk.models import ResumeResponse, RunCreateResponse, RunStatusResponse
+
+
+class AegisClient:
+    """Synchronous Aegis API client."""
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8767",
+        api_key: str = "",
+        *,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        headers: dict[str, str] = {}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        kwargs: dict[str, Any] = {"base_url": base_url, "headers": headers}
+        if transport is not None:
+            kwargs["transport"] = transport
+        self._client = httpx.Client(**kwargs)
+
+    def create_run(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        route: str = "default",
+        background: bool = False,
+        approvers: list[str] | None = None,
+    ) -> RunCreateResponse:
+        body = {
+            "messages": messages,
+            "route": route,
+            "background": background,
+            "approvers": approvers or [],
+        }
+        resp = self._client.post("/v1/runs", json=body)
+        resp.raise_for_status()
+        return RunCreateResponse(**resp.json())
+
+    def get_run(self, run_id: str) -> RunStatusResponse:
+        resp = self._client.get(f"/v1/runs/{run_id}")
+        resp.raise_for_status()
+        return RunStatusResponse(**resp.json())
+
+    def resume_run(self, run_id: str, decision: str) -> ResumeResponse:
+        resp = self._client.post(f"/v1/runs/{run_id}/resume", json={"decision": decision})
+        resp.raise_for_status()
+        return ResumeResponse(**resp.json())
+
+    def list_runs(
+        self,
+        *,
+        principal: str | None = None,
+        route: str | None = None,
+        since: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, str] = {}
+        if principal:
+            params["principal"] = principal
+        if route:
+            params["route"] = route
+        if since:
+            params["since"] = since
+        resp = self._client.get("/v1/audit", params=params)
+        resp.raise_for_status()
+        result: list[dict[str, Any]] = resp.json()["runs"]
+        return result
+
+    def chat(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        model: str = "default",
+    ) -> dict[str, Any]:
+        body = {"model": model, "messages": messages, "stream": False}
+        resp = self._client.post("/v1/chat/completions", json=body)
+        resp.raise_for_status()
+        result: dict[str, Any] = resp.json()
+        return result
+
+    def stream_chat(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        model: str = "default",
+    ) -> Iterator[dict[str, Any]]:
+        body = {"model": model, "messages": messages, "stream": True}
+        with self._client.stream("POST", "/v1/chat/completions", json=body) as resp:
+            resp.raise_for_status()
+            for line in resp.iter_lines():
+                if line.startswith("data: "):
+                    data = line[6:]
+                    if data.strip() == "[DONE]":
+                        break
+                    yield json.loads(data)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> AegisClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncAegisClient:
+    """Asynchronous Aegis API client."""
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8767",
+        api_key: str = "",
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        headers: dict[str, str] = {}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        kwargs: dict[str, Any] = {"base_url": base_url, "headers": headers}
+        if transport is not None:
+            kwargs["transport"] = transport
+        self._client = httpx.AsyncClient(**kwargs)
+
+    async def create_run(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        route: str = "default",
+        background: bool = False,
+        approvers: list[str] | None = None,
+    ) -> RunCreateResponse:
+        body = {
+            "messages": messages,
+            "route": route,
+            "background": background,
+            "approvers": approvers or [],
+        }
+        resp = await self._client.post("/v1/runs", json=body)
+        resp.raise_for_status()
+        return RunCreateResponse(**resp.json())
+
+    async def get_run(self, run_id: str) -> RunStatusResponse:
+        resp = await self._client.get(f"/v1/runs/{run_id}")
+        resp.raise_for_status()
+        return RunStatusResponse(**resp.json())
+
+    async def resume_run(self, run_id: str, decision: str) -> ResumeResponse:
+        resp = await self._client.post(f"/v1/runs/{run_id}/resume", json={"decision": decision})
+        resp.raise_for_status()
+        return ResumeResponse(**resp.json())
+
+    async def list_runs(
+        self,
+        *,
+        principal: str | None = None,
+        route: str | None = None,
+        since: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, str] = {}
+        if principal:
+            params["principal"] = principal
+        if route:
+            params["route"] = route
+        if since:
+            params["since"] = since
+        resp = await self._client.get("/v1/audit", params=params)
+        resp.raise_for_status()
+        result: list[dict[str, Any]] = resp.json()["runs"]
+        return result
+
+    async def chat(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        model: str = "default",
+    ) -> dict[str, Any]:
+        body = {"model": model, "messages": messages, "stream": False}
+        resp = await self._client.post("/v1/chat/completions", json=body)
+        resp.raise_for_status()
+        result: dict[str, Any] = resp.json()
+        return result
+
+    async def stream_chat(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        model: str = "default",
+    ) -> AsyncIterator[dict[str, Any]]:
+        body = {"model": model, "messages": messages, "stream": True}
+        async with self._client.stream("POST", "/v1/chat/completions", json=body) as resp:
+            resp.raise_for_status()
+            async for line in resp.aiter_lines():
+                if line.startswith("data: "):
+                    data = line[6:]
+                    if data.strip() == "[DONE]":
+                        break
+                    yield json.loads(data)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncAegisClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()

aegis_gateway_sdk-2.0.0a0/src/aegis_sdk/models.py

@@ -0,0 +1,35 @@
+"""Pydantic models for Aegis API request/response shapes."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class RunCreateRequest(BaseModel):
+    messages: list[dict[str, str]]
+    route: str = "default"
+    approvers: list[str] = []
+    background: bool = False
+
+
+class RunCreateResponse(BaseModel):
+    run_id: str
+    response: str | None
+    principal_id: str
+    events: list[dict[str, object]]
+    status: str
+
+
+class RunStatusResponse(BaseModel):
+    run_id: str
+    route: str
+    principal_id: str
+    status: str
+    approvers: list[str]
+
+
+class ResumeResponse(BaseModel):
+    run_id: str
+    status: str
+    response: str | None
+    events: list[dict[str, object]]

aegis_gateway_sdk-2.0.0a0/tests/test_async_client.py

@@ -0,0 +1,130 @@
+"""Async client integration tests against the ASGI app (PROJECT_SPEC D10).
+
+Gate: DC uv run pytest sdk/python -q
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from aegis_core.pipeline.executor import PipelineExecutor
+from aegis_core.testing.providers import FakeProvider
+from aegis_sdk import AsyncAegisClient
+from aegis_server.app import create_app
+from aegis_server.auth import ApiKeyAuthenticator
+from aegis_server.keys import KeyStore
+from aegis_server.store.run_store import InMemoryRunStore
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_transport() -> tuple[httpx.ASGITransport, str]:
+    """Build an ASGI transport and return (transport, api_key)."""
+    fake = FakeProvider(complete_response="sdk response")
+    ex = PipelineExecutor()
+    ex.register("default", provider=fake)
+    ks = KeyStore()
+    api_key = ks.create(principal_id="sdk-user", team="t")
+    store = InMemoryRunStore()
+    app = create_app(ex, authenticator=ApiKeyAuthenticator(ks), run_store=store)
+    return httpx.ASGITransport(app=app), api_key  # type: ignore[arg-type]
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_async_create_run_returns_response() -> None:
+    """AsyncAegisClient.create_run() returns a RunCreateResponse with status."""
+    transport, api_key = _make_transport()
+    async with AsyncAegisClient("http://test", api_key, transport=transport) as client:
+        result = await client.create_run([{"role": "user", "content": "hello"}])
+    assert result.run_id
+    assert result.status == "completed"
+    assert result.response == "sdk response"
+
+
+@pytest.mark.asyncio
+async def test_async_create_run_background_returns_pending() -> None:
+    """AsyncAegisClient.create_run(background=True) returns status=pending."""
+    transport, api_key = _make_transport()
+    async with AsyncAegisClient("http://test", api_key, transport=transport) as client:
+        result = await client.create_run(
+            [{"role": "user", "content": "hi"}], background=True
+        )
+    assert result.status == "pending"
+    assert result.response is None
+
+
+@pytest.mark.asyncio
+async def test_async_get_run_returns_status() -> None:
+    """AsyncAegisClient.get_run() polls run status."""
+    transport, api_key = _make_transport()
+    async with AsyncAegisClient("http://test", api_key, transport=transport) as client:
+        created = await client.create_run([{"role": "user", "content": "hi"}])
+        polled = await client.get_run(created.run_id)
+    assert polled.run_id == created.run_id
+    assert polled.status == "completed"
+    assert polled.route == "default"
+
+
+@pytest.mark.asyncio
+async def test_async_list_runs_returns_entries() -> None:
+    """AsyncAegisClient.list_runs() returns audit records."""
+    transport, api_key = _make_transport()
+    async with AsyncAegisClient("http://test", api_key, transport=transport) as client:
+        await client.create_run([{"role": "user", "content": "audit test"}])
+        runs = await client.list_runs()
+    assert len(runs) == 1
+    assert runs[0]["principal_id"] == "sdk-user"
+
+
+@pytest.mark.asyncio
+async def test_async_list_runs_filter_by_route() -> None:
+    """AsyncAegisClient.list_runs(route=...) filters results."""
+    transport, api_key = _make_transport()
+    async with AsyncAegisClient("http://test", api_key, transport=transport) as client:
+        await client.create_run([{"role": "user", "content": "x"}], route="default")
+        runs = await client.list_runs(route="default")
+        no_runs = await client.list_runs(route="nonexistent")
+    assert len(runs) == 1
+    assert no_runs == []
+
+
+@pytest.mark.asyncio
+async def test_async_chat_returns_completion() -> None:
+    """AsyncAegisClient.chat() calls /v1/chat/completions and returns JSON."""
+    transport, api_key = _make_transport()
+    async with AsyncAegisClient("http://test", api_key, transport=transport) as client:
+        result = await client.chat([{"role": "user", "content": "hi"}], model="default")
+    assert "choices" in result
+    assert result["choices"][0]["message"]["content"] == "sdk response"
+
+
+@pytest.mark.asyncio
+async def test_async_stream_chat_yields_chunks() -> None:
+    """AsyncAegisClient.stream_chat() yields parsed SSE chunks."""
+    transport, api_key = _make_transport()
+    chunks: list[dict[str, object]] = []
+    async with AsyncAegisClient("http://test", api_key, transport=transport) as client:
+        async for chunk in client.stream_chat(
+            [{"role": "user", "content": "stream"}], model="default"
+        ):
+            chunks.append(chunk)
+    assert len(chunks) >= 1
+    assert any(c.get("object") == "chat.completion.chunk" for c in chunks)
+
+
+@pytest.mark.asyncio
+async def test_async_unauthenticated_raises() -> None:
+    """AsyncAegisClient without a key gets a 401 HTTPStatusError."""
+    transport, _key = _make_transport()
+    async with AsyncAegisClient("http://test", "", transport=transport) as client:
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            await client.create_run([{"role": "user", "content": "hi"}])
+    assert exc_info.value.response.status_code == 401

aegis_gateway_sdk-2.0.0a0/tests/test_sync_client.py

@@ -0,0 +1,195 @@
+"""Sync client unit tests — HTTP layer mocked (PROJECT_SPEC D10).
+
+Gate: DC uv run pytest sdk/python -q
+"""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+
+from aegis_sdk import AegisClient
+from aegis_sdk.models import ResumeResponse, RunCreateResponse, RunStatusResponse
+
+
+def _mock_response(status_code: int, body: object) -> MagicMock:
+    resp = MagicMock(spec=httpx.Response)
+    resp.status_code = status_code
+    resp.json.return_value = body
+    resp.raise_for_status = MagicMock()
+    if status_code >= 400:
+        resp.raise_for_status.side_effect = httpx.HTTPStatusError(
+            "error", request=MagicMock(), response=resp
+        )
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# create_run
+# ---------------------------------------------------------------------------
+
+
+def test_sync_create_run_posts_to_v1_runs() -> None:
+    """create_run() sends POST /v1/runs and returns RunCreateResponse."""
+    body = {
+        "run_id": "r1",
+        "response": "hello",
+        "principal_id": "u",
+        "events": [],
+        "status": "completed",
+    }
+    client = AegisClient("http://test", "key")
+    with patch.object(client._client, "post", return_value=_mock_response(200, body)) as mock_post:
+        result = client.create_run([{"role": "user", "content": "hi"}])
+    mock_post.assert_called_once()
+    call_kwargs = mock_post.call_args
+    assert "/v1/runs" in call_kwargs.args[0]
+    assert isinstance(result, RunCreateResponse)
+    assert result.run_id == "r1"
+    assert result.status == "completed"
+
+
+def test_sync_create_run_background_flag() -> None:
+    """create_run(background=True) sends background=true in body."""
+    body = {
+        "run_id": "r2",
+        "response": None,
+        "principal_id": "u",
+        "events": [],
+        "status": "pending",
+    }
+    client = AegisClient("http://test", "key")
+    with patch.object(client._client, "post", return_value=_mock_response(200, body)) as mock_post:
+        result = client.create_run([{"role": "user", "content": "hi"}], background=True)
+    sent_json = mock_post.call_args.kwargs["json"]
+    assert sent_json["background"] is True
+    assert result.status == "pending"
+
+
+# ---------------------------------------------------------------------------
+# get_run
+# ---------------------------------------------------------------------------
+
+
+def test_sync_get_run_gets_v1_runs_id() -> None:
+    """get_run() sends GET /v1/runs/{run_id} and returns RunStatusResponse."""
+    body = {
+        "run_id": "r1",
+        "route": "default",
+        "principal_id": "u",
+        "status": "completed",
+        "approvers": [],
+    }
+    client = AegisClient("http://test", "key")
+    with patch.object(client._client, "get", return_value=_mock_response(200, body)) as mock_get:
+        result = client.get_run("r1")
+    mock_get.assert_called_once_with("/v1/runs/r1")
+    assert isinstance(result, RunStatusResponse)
+    assert result.run_id == "r1"
+
+
+# ---------------------------------------------------------------------------
+# resume_run
+# ---------------------------------------------------------------------------
+
+
+def test_sync_resume_run_posts_decision() -> None:
+    """resume_run() sends POST /v1/runs/{id}/resume with decision in body."""
+    body = {"run_id": "r1", "status": "completed", "response": "ok", "events": []}
+    client = AegisClient("http://test", "key")
+    with patch.object(client._client, "post", return_value=_mock_response(200, body)) as mock_post:
+        result = client.resume_run("r1", "approved")
+    call_url = mock_post.call_args.args[0]
+    assert "/v1/runs/r1/resume" in call_url
+    sent_json = mock_post.call_args.kwargs["json"]
+    assert sent_json["decision"] == "approved"
+    assert isinstance(result, ResumeResponse)
+
+
+# ---------------------------------------------------------------------------
+# list_runs
+# ---------------------------------------------------------------------------
+
+
+def test_sync_list_runs_calls_audit_endpoint() -> None:
+    """list_runs() calls GET /v1/audit and returns the runs list."""
+    body = {"runs": [{"run_id": "r1", "status": "completed"}]}
+    client = AegisClient("http://test", "key")
+    with patch.object(client._client, "get", return_value=_mock_response(200, body)) as mock_get:
+        runs = client.list_runs()
+    mock_get.assert_called_once()
+    assert "/v1/audit" in mock_get.call_args.args[0]
+    assert len(runs) == 1
+
+
+def test_sync_list_runs_passes_filters() -> None:
+    """list_runs(principal=..., route=...) passes query params."""
+    body = {"runs": []}
+    client = AegisClient("http://test", "key")
+    with patch.object(client._client, "get", return_value=_mock_response(200, body)) as mock_get:
+        client.list_runs(principal="alice", route="default")
+    params = mock_get.call_args.kwargs.get("params", {})
+    assert params["principal"] == "alice"
+    assert params["route"] == "default"
+
+
+# ---------------------------------------------------------------------------
+# chat
+# ---------------------------------------------------------------------------
+
+
+def test_sync_chat_posts_to_chat_completions() -> None:
+    """chat() sends POST /v1/chat/completions."""
+    body = {
+        "id": "c1",
+        "object": "chat.completion",
+        "created": 0,
+        "model": "default",
+        "choices": [{"index": 0, "message": {"role": "assistant", "content": "hi"}, "finish_reason": "stop"}],
+        "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2},
+    }
+    client = AegisClient("http://test", "key")
+    with patch.object(client._client, "post", return_value=_mock_response(200, body)) as mock_post:
+        result = client.chat([{"role": "user", "content": "hi"}])
+    assert "/v1/chat/completions" in mock_post.call_args.args[0]
+    assert result["choices"][0]["message"]["content"] == "hi"
+
+
+# ---------------------------------------------------------------------------
+# stream_chat
+# ---------------------------------------------------------------------------
+
+
+def test_sync_stream_chat_yields_parsed_chunks() -> None:
+    """stream_chat() parses SSE lines and yields dicts."""
+    chunk1 = json.dumps({"object": "chat.completion.chunk", "choices": [{"delta": {"content": "hello"}}]})
+    sse_lines = [f"data: {chunk1}", "data: [DONE]"]
+
+    mock_resp = MagicMock()
+    mock_resp.__enter__ = lambda s: s
+    mock_resp.__exit__ = MagicMock(return_value=False)
+    mock_resp.raise_for_status = MagicMock()
+    mock_resp.iter_lines.return_value = iter(sse_lines)
+
+    client = AegisClient("http://test", "key")
+    with patch.object(client._client, "stream", return_value=mock_resp):
+        chunks = list(client.stream_chat([{"role": "user", "content": "hi"}]))
+
+    assert len(chunks) == 1
+    assert chunks[0]["object"] == "chat.completion.chunk"
+
+
+# ---------------------------------------------------------------------------
+# error propagation
+# ---------------------------------------------------------------------------
+
+
+def test_sync_create_run_raises_on_401() -> None:
+    """create_run() raises HTTPStatusError on 401."""
+    client = AegisClient("http://test", "badkey")
+    with patch.object(client._client, "post", return_value=_mock_response(401, {"detail": "Unauthorized"})):
+        with pytest.raises(httpx.HTTPStatusError):
+            client.create_run([{"role": "user", "content": "hi"}])