ariacompute-agent 0.17.0__tar.gz

ariacompute_agent-0.17.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: ariacompute-agent
+Version: 0.17.0
+Summary: Aria agent SDK - mirrors the OpenAI Agents SDK (Agent / Runner.run / Runner.run_streamed / function_tool / Session) on top of the aria-agent-cloud beta Agents API.
+License: MIT
+Keywords: agent,agents-sdk,aria,ariacompute,openai
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# `ariacompute-agent`
+
+The Aria agent SDK for Python. The API mirrors the
+[OpenAI Agents SDK](https://developers.openai.com/api/docs/guides/agents/quickstart)
+(`Agent`, `Runner.run`, `Runner.run_streamed`, `function_tool`, `Session`) and
+talks to an `aria-agent-cloud` deployment through its **beta Agents** REST API.
+
+```bash
+pip install ariacompute-agent
+```
+
+```python
+import asyncio
+
+from ariacompute_agent import Agent, Runner
+
+
+async def main() -> None:
+    agent = Agent(
+        name="History tutor",
+        instructions="Answer history questions clearly and concisely.",
+        model="gpt-4o-mini",
+    )
+    result = await Runner.run(agent, "When did the Roman Empire fall?")
+    print(result.final_output)
+
+
+asyncio.run(main())
+```
+
+## Tools
+
+```python
+from ariacompute_agent import function_tool
+
+
+@function_tool
+def history_fun_fact() -> str:
+    """Return a short history fact."""
+    return "Sharks are older than trees."
+
+
+agent = Agent(name="History tutor", tools=[history_fun_fact])
+```
+
+The cloud executes tools inside its own sandbox, so only the schema
+(`name` / `description` / `parameters`) is sent to the server.
+
+## Streaming
+
+```python
+streamed = await Runner.run_streamed(agent, "Tell me something surprising")
+async for ev in streamed.events:
+    if ev["type"] == "agent.turn.output_text.delta":
+        print(ev["delta"], end="")
+result = await streamed.completed
+print(result.final_output)
+```
+
+Frames use the `agent.*` envelope; `agent.turn.completed` (or
+`agent.turn.failed`) is the **only** terminal event — there is no
+`data: [DONE]` sentinel.
+
+## Sessions
+
+```python
+session = Session.create(agent)
+await Runner.run(agent, "hello", session=session)
+await Runner.run(agent, "and then?", session=session)
+```
+
+## Configuration
+
+| Option | Environment variable | Default |
+| --- | --- | --- |
+| `base_url` | `ARIA_AGENT_BASE_URL` | `http://localhost:3000` |
+| `api_key` | `ARIA_AGENT_API_KEY` | _(none)_ |
+| `beta_header` | – | `agents=v1` (`OpenAI-Beta`) |
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```

ariacompute_agent-0.17.0/README.md

@@ -0,0 +1,84 @@
+# `ariacompute-agent`
+
+The Aria agent SDK for Python. The API mirrors the
+[OpenAI Agents SDK](https://developers.openai.com/api/docs/guides/agents/quickstart)
+(`Agent`, `Runner.run`, `Runner.run_streamed`, `function_tool`, `Session`) and
+talks to an `aria-agent-cloud` deployment through its **beta Agents** REST API.
+
+```bash
+pip install ariacompute-agent
+```
+
+```python
+import asyncio
+
+from ariacompute_agent import Agent, Runner
+
+
+async def main() -> None:
+    agent = Agent(
+        name="History tutor",
+        instructions="Answer history questions clearly and concisely.",
+        model="gpt-4o-mini",
+    )
+    result = await Runner.run(agent, "When did the Roman Empire fall?")
+    print(result.final_output)
+
+
+asyncio.run(main())
+```
+
+## Tools
+
+```python
+from ariacompute_agent import function_tool
+
+
+@function_tool
+def history_fun_fact() -> str:
+    """Return a short history fact."""
+    return "Sharks are older than trees."
+
+
+agent = Agent(name="History tutor", tools=[history_fun_fact])
+```
+
+The cloud executes tools inside its own sandbox, so only the schema
+(`name` / `description` / `parameters`) is sent to the server.
+
+## Streaming
+
+```python
+streamed = await Runner.run_streamed(agent, "Tell me something surprising")
+async for ev in streamed.events:
+    if ev["type"] == "agent.turn.output_text.delta":
+        print(ev["delta"], end="")
+result = await streamed.completed
+print(result.final_output)
+```
+
+Frames use the `agent.*` envelope; `agent.turn.completed` (or
+`agent.turn.failed`) is the **only** terminal event — there is no
+`data: [DONE]` sentinel.
+
+## Sessions
+
+```python
+session = Session.create(agent)
+await Runner.run(agent, "hello", session=session)
+await Runner.run(agent, "and then?", session=session)
+```
+
+## Configuration
+
+| Option | Environment variable | Default |
+| --- | --- | --- |
+| `base_url` | `ARIA_AGENT_BASE_URL` | `http://localhost:3000` |
+| `api_key` | `ARIA_AGENT_API_KEY` | _(none)_ |
+| `beta_header` | – | `agents=v1` (`OpenAI-Beta`) |
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```

ariacompute_agent-0.17.0/ariacompute_agent/__init__.py

@@ -0,0 +1,75 @@
+"""``ariacompute-agent`` — the Aria agent SDK.
+
+The API mirrors the OpenAI Agents SDK (``openai-agents``) so the official
+quickstart transfers unchanged:
+
+```python
+import asyncio
+
+from ariacompute_agent import Agent, Runner
+
+
+async def main() -> None:
+    agent = Agent(
+        name="History tutor",
+        instructions="Answer history questions clearly and concisely.",
+        model="gpt-4o-mini",
+    )
+    result = await Runner.run(agent, "When did the Roman Empire fall?")
+    print(result.final_output)
+
+
+asyncio.run(main())
+```
+"""
+
+from .agent import Agent
+from .memory import (
+    CloudMemoryStore,
+    CompositeMemoryStore,
+    LocalMemoryStore,
+    MemoryBackend,
+)
+from .runner import Runner
+from .session import Session
+from .tool import function_tool, tool_from_function
+from .transport import (
+    DEFAULT_BETA_HEADER,
+    AgentTransportError,
+    get_json,
+    post_json,
+    resolve_client,
+)
+from .types import (
+    ClientOptions,
+    HistoryInput,
+    HistoryItem,
+    RunResult,
+    StreamedRunResult,
+    ToolSpec,
+)
+
+__all__ = [
+    "Agent",
+    "Runner",
+    "Session",
+    "MemoryBackend",
+    "LocalMemoryStore",
+    "CloudMemoryStore",
+    "CompositeMemoryStore",
+    "function_tool",
+    "tool_from_function",
+    "ClientOptions",
+    "HistoryItem",
+    "HistoryInput",
+    "RunResult",
+    "StreamedRunResult",
+    "ToolSpec",
+    "AgentTransportError",
+    "resolve_client",
+    "post_json",
+    "get_json",
+    "DEFAULT_BETA_HEADER",
+]
+
+__version__ = "0.1.0"

ariacompute_agent-0.17.0/ariacompute_agent/agent.py

@@ -0,0 +1,83 @@
+"""``Agent`` — mirrors ``Agent(...)`` from the OpenAI Agents SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Sequence, Union
+
+from .memory import MemoryBackend
+from .tool import tool_from_function
+from .types import ClientOptions, ToolSpec
+
+
+class Agent:
+    """A reusable agent definition.
+
+    ```python
+    agent = Agent(
+        name="History tutor",
+        instructions="Answer history questions clearly and concisely.",
+        model="gpt-4o-mini",
+    )
+    ```
+    """
+
+    def __init__(
+        self,
+        name: str,
+        instructions: Optional[str] = None,
+        model: Optional[str] = None,
+        tools: Optional[Sequence[Any]] = None,
+        handoffs: Optional[Sequence["Agent"]] = None,
+        handoff_description: Optional[str] = None,
+        id: Optional[str] = None,
+        client: Optional[ClientOptions] = None,
+        memory_backend: Union[str, MemoryBackend, None] = None,
+        memo_db: Optional[str] = None,
+    ) -> None:
+        if not name or not name.strip():
+            raise ValueError("Agent requires a `name`")
+        self.name = name
+        self.instructions = instructions
+        self.model = model
+        self.tools = [self._coerce_tool(t) for t in (tools or [])]
+        self.handoffs = list(handoffs or [])
+        self.handoff_description = handoff_description
+        self.id = id
+        self.client = client or ClientOptions()
+        self.memory_backend = (
+            MemoryBackend.parse(memory_backend) if memory_backend is not None
+            else MemoryBackend.CLOUD
+        )
+        self.memo_db = memo_db
+
+    @staticmethod
+    def _coerce_tool(t: Any) -> ToolSpec:
+        if isinstance(t, ToolSpec):
+            return t
+        if callable(t):
+            return tool_from_function(t)
+        raise TypeError(f"unsupported tool: {t!r}")
+
+    def clone(self, **overrides: Any) -> "Agent":
+        """Return a copy with overridden fields (used by handoffs)."""
+        params: dict[str, Any] = dict(
+            name=self.name,
+            instructions=self.instructions,
+            model=self.model,
+            tools=self.tools,
+            handoffs=self.handoffs,
+            handoff_description=self.handoff_description,
+            id=self.id,
+            client=self.client,
+            memory_backend=self.memory_backend,
+            memo_db=self.memo_db,
+        )
+        params.update(overrides)
+        return Agent(**params)
+
+    def tool_schemas(self) -> list[dict[str, Any]]:
+        """JSON-schema tool declarations forwarded to the cloud."""
+        return [t.schema() for t in self.tools]
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"Agent(name={self.name!r}, model={self.model!r})"

ariacompute_agent-0.17.0/ariacompute_agent/memory.py

@@ -0,0 +1,216 @@
+"""Memory backends for :mod:`ariacompute_agent`.
+
+* ``cloud`` — the agent-cloud session memory REST endpoints
+  (``/v1/agents/sessions/{id}/memory``).
+* ``local`` — **aria memo**: the same SQLite ``memories`` database the
+  ``aria-memo`` product/CLI uses, written directly through the stdlib
+  :mod:`sqlite3` module (no external binary required). ``aria-memo list --json``
+  can read the very same file.
+* ``both`` — writes to local **and** cloud; reads merged (cloud wins, local is
+  the fallback).
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from enum import Enum
+from pathlib import Path
+from typing import Optional, Protocol
+
+from .transport import get_json, post_json, resolve_client
+from .types import ClientOptions
+
+
+class MemoryBackend(str, Enum):
+    """Where a memory context lives."""
+
+    CLOUD = "cloud"
+    LOCAL = "local"
+    BOTH = "both"
+
+    @classmethod
+    def parse(cls, value: Optional[object]) -> "MemoryBackend":
+        if value is None:
+            return cls.CLOUD
+        if isinstance(value, cls):
+            return value
+        raw = str(getattr(value, "value", value)).strip().lower()
+        for member in cls:
+            if member.value == raw:
+                return member
+        raise ValueError(f"unknown memory backend: {value}")
+
+
+class MemoryStore(Protocol):
+    """Key/value view of a memory backend."""
+
+    backend: MemoryBackend
+
+    def put(self, key: str, value: str) -> None:  # pragma: no cover - protocol
+        ...
+
+    def get(self, key: str) -> Optional[str]:  # pragma: no cover - protocol
+        ...
+
+
+# --- aria memo (local) -------------------------------------------------------
+
+#: aria memo's ``memories`` schema — kept byte-identical so its CLI can open the file.
+ARIA_MEMO_SCHEMA = """
+CREATE TABLE IF NOT EXISTS memories (
+    id TEXT PRIMARY KEY,
+    memo_type TEXT NOT NULL,
+    content TEXT NOT NULL,
+    embedding BLOB,
+    metadata TEXT NOT NULL,
+    importance REAL NOT NULL,
+    version INTEGER NOT NULL,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    deleted INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(memo_type);
+CREATE INDEX IF NOT EXISTS idx_memories_updated_at ON memories(updated_at);
+CREATE INDEX IF NOT EXISTS idx_memories_deleted ON memories(deleted);
+"""
+
+MEMO_TYPE_LONG_TERM = "long_term:semantic"
+
+
+def _now_sec() -> int:
+    import time
+
+    return int(time.time())
+
+
+class LocalMemoryStore:
+    """``local`` backend: aria memo (SQLite, same format as ``aria-memo``)."""
+
+    backend = MemoryBackend.LOCAL
+
+    def __init__(self, db_path: Optional[str] = None) -> None:
+        path = db_path or __import__("os").environ.get("ARIA_MEMO_DB") or "memo.db"
+        self.db_path = str(path)
+        parent = Path(self.db_path).parent
+        if str(parent) and not parent.exists():
+            parent.mkdir(parents=True, exist_ok=True)
+        self._ensure_schema()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path)
+        conn.execute("PRAGMA journal_mode=WAL")
+        return conn
+
+    def _ensure_schema(self) -> None:
+        with self._connect() as conn:
+            conn.executescript(ARIA_MEMO_SCHEMA)
+
+    def put(self, key: str, value: str) -> None:
+        """Write ``key`` as a long-term aria memo (``metadata.key`` holds the key)."""
+        now = _now_sec()
+        metadata = json.dumps({"key": key})
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT INTO memories "
+                "(id, memo_type, content, embedding, metadata, importance, version, "
+                " created_at, updated_at, deleted) "
+                "VALUES (?, ?, ?, ?, ?, ?, 1, ?, ?, 0) "
+                "ON CONFLICT(id) DO UPDATE SET "
+                "  content = excluded.content, metadata = excluded.metadata, "
+                "  updated_at = excluded.updated_at, deleted = 0",
+                (f"key:{key}", MEMO_TYPE_LONG_TERM, value, b"", metadata, 0.8, now, now),
+            )
+
+    def get(self, key: str) -> Optional[str]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT content, metadata FROM memories WHERE deleted = 0",
+            ).fetchall()
+        for content, metadata in rows:
+            try:
+                parsed = json.loads(metadata or "{}")
+            except json.JSONDecodeError:
+                parsed = {}
+            if parsed.get("key") == key:
+                return content
+        return None
+
+
+# --- cloud -------------------------------------------------------------------
+
+
+class CloudMemoryStore:
+    """``cloud`` backend: the agent-cloud session memory REST endpoints."""
+
+    backend = MemoryBackend.CLOUD
+
+    def __init__(self, session_id: str, client: Optional[ClientOptions] = None) -> None:
+        self.session_id = session_id
+        self.client = client or ClientOptions()
+
+    def _base(self) -> str:
+        return f"/v1/agents/sessions/{self.session_id}/memory"
+
+    def put(self, key: str, value: str) -> None:
+        resolved = resolve_client(self.client)
+        post_json(resolved, self._base(), {"key": key, "value": value, "kind": "long_term"})
+
+    def get(self, key: str) -> Optional[str]:
+        resolved = resolve_client(self.client)
+        res = get_json(resolved, f"{self._base()}/{key}")
+        return res.get("value")
+
+
+# --- both --------------------------------------------------------------------
+
+
+class CompositeMemoryStore:
+    """``both`` backend: writes to local **and** cloud, reads merged."""
+
+    backend = MemoryBackend.BOTH
+
+    def __init__(self, local: MemoryStore, cloud: MemoryStore) -> None:
+        self.local = local
+        self.cloud = cloud
+
+    def put(self, key: str, value: str) -> None:
+        errors = []
+        for store in (self.local, self.cloud):
+            try:
+                store.put(key, value)
+            except Exception as e:  # noqa: BLE001 - one side may be offline
+                errors.append(str(e))
+        if len(errors) == 2:
+            raise RuntimeError("memory write failed on every backend: " + "; ".join(errors))
+
+    def get(self, key: str) -> Optional[str]:
+        errors = []
+        for store in (self.cloud, self.local):
+            try:
+                value = store.get(key)
+            except Exception as e:  # noqa: BLE001 - fall through to the other side
+                errors.append(str(e))
+                continue
+            if value is not None:
+                return value
+        if len(errors) == 2:
+            raise RuntimeError("memory read failed on every backend: " + "; ".join(errors))
+        return None
+
+
+def build_store(
+    backend: MemoryBackend,
+    session_id: str,
+    client: Optional[ClientOptions] = None,
+    memo_db: Optional[str] = None,
+) -> MemoryStore:
+    """Build the store for ``backend`` (local is created lazily but validated)."""
+    if backend is MemoryBackend.LOCAL:
+        return LocalMemoryStore(memo_db)
+    if backend is MemoryBackend.CLOUD:
+        return CloudMemoryStore(session_id, client)
+    return CompositeMemoryStore(
+        LocalMemoryStore(memo_db),
+        CloudMemoryStore(session_id, client),
+    )

ariacompute_agent-0.17.0/ariacompute_agent/runner.py

@@ -0,0 +1,153 @@
+"""``Runner`` — mirrors ``Runner.run`` / ``Runner.run_streamed`` from the Agents SDK.
+
+Both drive one turn against the cloud's beta Agents API:
+``POST /v1/agents/sessions/{id}/events`` (blocking) or
+``POST /v1/agents/sessions/{id}/events/stream`` (SSE).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, AsyncIterator, Optional, Union
+
+from .session import Session
+from .transport import async_stream_json, post_json, resolve_client
+from .types import ClientOptions, HistoryInput, HistoryItem, RunResult, StreamedRunResult
+
+
+def _to_text(value: HistoryInput) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, HistoryItem):
+        return value.content
+    if isinstance(value, dict):  # {"role": ..., "content": ...}
+        return str(value.get("content", ""))
+    parts: list[str] = []
+    for item in value or []:
+        if isinstance(item, str):
+            parts.append(item)
+        elif isinstance(item, HistoryItem):
+            parts.append(item.content)
+        elif isinstance(item, dict):
+            parts.append(str(item.get("content", "")))
+    return "\n".join(parts)
+
+
+def _ensure_session(agent: Any, client: ClientOptions, session: Any) -> Session:
+    if isinstance(session, Session):
+        return session
+    if isinstance(session, str) and session:
+        return Session(session, client)
+    return Session.create(agent, client)
+
+
+class Runner:
+    """Runs agents against the aria-agent-cloud service."""
+
+    @staticmethod
+    async def run(
+        agent: Any,
+        input: HistoryInput,
+        *,
+        session: Optional[Union[Session, str]] = None,
+        client: Optional[ClientOptions] = None,
+    ) -> RunResult:
+        """Run one turn to completion and return the result.
+
+        ```python
+        result = await Runner.run(agent, "When did the Roman Empire fall?")
+        print(result.final_output)
+        ```
+        """
+        merged = client or agent.client
+        resolved = resolve_client(merged)
+        sess = _ensure_session(agent, merged, session)
+        text = _to_text(input)
+
+        turn = await asyncio.to_thread(
+            post_json,
+            resolved,
+            f"/v1/agents/sessions/{sess.id}/events",
+            {"input": text},
+        )
+        output = turn.get("output") or ""
+        sess.record(input, output)
+        return RunResult(
+            final_output=output,
+            history=list(sess.history),
+            last_agent=agent,
+            session_id=sess.id,
+            turn_id=turn.get("id"),
+        )
+
+    @staticmethod
+    async def run_streamed(
+        agent: Any,
+        input: HistoryInput,
+        *,
+        session: Optional[Union[Session, str]] = None,
+        client: Optional[ClientOptions] = None,
+    ) -> StreamedRunResult:
+        """Run one turn, streaming events (``agent.turn.*`` frames).
+
+        ```python
+        streamed = await Runner.run_streamed(agent, "Tell me something surprising")
+        async for ev in streamed.events:
+            if ev["type"] == "agent.turn.output_text.delta":
+                print(ev["delta"], end="")
+        result = await streamed.completed
+        print(result.final_output)
+        ```
+        """
+        merged = client or agent.client
+        resolved = resolve_client(merged)
+        sess = _ensure_session(agent, merged, session)
+        text = _to_text(input)
+
+        state: dict[str, Any] = {"text": "", "turn_id": None, "error": None}
+        buffered: list[dict[str, Any]] = []
+        drained = asyncio.Event()
+
+        def _note(frame: dict[str, Any]) -> None:
+            state["turn_id"] = frame.get("turn_id") or state["turn_id"]
+            kind = frame.get("type")
+            if kind == "agent.turn.output_text.delta":
+                state["text"] += str(frame.get("delta") or "")
+            elif kind in ("agent.turn.output_text.done", "agent.turn.completed"):
+                out = frame.get("text") or (frame.get("turn") or {}).get("output")
+                if isinstance(out, str) and out:
+                    state["text"] = out
+            elif kind == "agent.turn.failed":
+                state["error"] = (frame.get("error") or {}).get("message") or "run failed"
+
+        async def _drain() -> None:
+            async for frame in async_stream_json(
+                resolved,
+                f"/v1/agents/sessions/{sess.id}/events/stream",
+                {"input": text},
+            ):
+                buffered.append(frame)
+                _note(frame)
+            drained.set()
+
+        drain_task = asyncio.ensure_future(_drain())
+
+        async def events() -> AsyncIterator[dict[str, Any]]:
+            await asyncio.shield(drain_task)
+            for frame in buffered:
+                yield frame
+
+        async def completed() -> RunResult:
+            await asyncio.shield(drain_task)
+            if state["error"]:
+                raise RuntimeError(state["error"])
+            sess.record(input, state["text"])
+            return RunResult(
+                final_output=state["text"],
+                history=list(sess.history),
+                last_agent=agent,
+                session_id=sess.id,
+                turn_id=state["turn_id"],
+            )
+
+        return StreamedRunResult(events=events(), completed=completed())