spinekit 0.2.0__py3-none-any.whl

spine_a2a/__init__.py

@@ -0,0 +1,17 @@
+"""A2A (agent-to-agent) adapter for Spine.
+
+```python
+from spine_core import Agent
+from spine_a2a import A2AAgent
+
+async with A2AAgent("https://remote.example.com/a2a", name="researcher") as remote:
+    agent = Agent("anthropic:claude-sonnet-4-6", tools=[remote.as_tool()])
+    print((await agent.run("ask the researcher about otters")).answer)
+```
+"""
+
+from __future__ import annotations
+
+from spine_a2a.client import A2AAgent
+
+__all__ = ["A2AAgent"]

spine_a2a/client.py

@@ -0,0 +1,101 @@
+"""A2A (agent-to-agent) client — call a remote agent and mount it as a tool.
+
+Spine consumes the open A2A protocol rather than a proprietary handoff format.
+A remote agent is reached over JSON-RPC (``message/send``); ``as_tool`` wraps it
+so a local agent can delegate to it like any other tool.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from spine_core import Tool, raw_tool
+
+_INPUT_SCHEMA = {
+    "type": "object",
+    "properties": {"input": {"type": "string", "description": "Message for the remote agent."}},
+    "required": ["input"],
+}
+
+
+def _extract_text(data: dict[str, Any]) -> str:
+    """Pull text out of an A2A response, tolerant of Message/Task shapes."""
+    if "error" in data and data["error"]:
+        return f"A2A error: {data['error'].get('message', data['error'])}"
+    result = data.get("result", data)
+
+    def parts_text(parts: Any) -> str:
+        out = [p.get("text", "") for p in (parts or []) if isinstance(p, dict)]
+        return "\n".join(t for t in out if t)
+
+    # direct message
+    if isinstance(result, dict):
+        text = parts_text(result.get("parts"))
+        if text:
+            return text
+        # task with artifacts
+        for artifact in result.get("artifacts") or []:
+            text = parts_text(artifact.get("parts"))
+            if text:
+                return text
+        # task status message
+        status = result.get("status") or {}
+        text = parts_text((status.get("message") or {}).get("parts"))
+        if text:
+            return text
+    return ""
+
+
+class A2AAgent:
+    """A handle to a remote A2A agent reached over JSON-RPC."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        client: httpx.AsyncClient | None = None,
+        name: str | None = None,
+        description: str | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self.url = url
+        self.name = name or "remote_agent"
+        self.description = description or "Delegate a task to a remote A2A agent."
+        self._client = client
+        self._owns_client = client is None
+        self._timeout = timeout
+
+    def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self._timeout)
+        return self._client
+
+    async def send(self, text: str) -> str:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "message/send",
+            "params": {"message": {"role": "user", "parts": [{"kind": "text", "text": text}]}},
+        }
+        response = await self._ensure_client().post(self.url, json=payload)
+        response.raise_for_status()
+        return _extract_text(response.json())
+
+    def as_tool(self, *, name: str | None = None, description: str | None = None) -> Tool:
+        async def call(input: str) -> str:
+            return await self.send(input)
+
+        return raw_tool(name or self.name, description or self.description, _INPUT_SCHEMA, call)
+
+    async def aclose(self) -> None:
+        if self._client is not None and self._owns_client:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> A2AAgent:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

spine_backends/__init__.py

@@ -0,0 +1,27 @@
+"""Spine storage backends.
+
+Importing the package registers the ``sqlite`` checkpoint backend by name, so
+``spine.toml`` ``checkpoint = "sqlite"`` resolves.
+"""
+
+from __future__ import annotations
+
+from spine_backends.embeddings import HashEmbedder, OpenAIEmbedder
+from spine_backends.memory import BufferMemory, InMemoryVectorMemory
+from spine_backends.migrations import register_migration
+from spine_backends.pgvector import PgVectorMemory
+from spine_backends.postgres import PostgresCheckpoint
+from spine_backends.redis import RedisCheckpoint
+from spine_backends.sqlite import SQLiteCheckpoint
+
+__all__ = [
+    "BufferMemory",
+    "HashEmbedder",
+    "InMemoryVectorMemory",
+    "OpenAIEmbedder",
+    "PgVectorMemory",
+    "PostgresCheckpoint",
+    "RedisCheckpoint",
+    "SQLiteCheckpoint",
+    "register_migration",
+]

spine_backends/embeddings.py

@@ -0,0 +1,68 @@
+"""Embedders — pluggable text->vector backends implementing core ``Embedder``.
+
+``HashEmbedder`` is dependency-free and offline (a good default and test double);
+``OpenAIEmbedder`` calls a real embedding model. Any object with
+``async def embed(text) -> list[float]`` works, so users can bring their own
+(sentence-transformers, Cohere, local models, …).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from typing import Any
+
+_WORD = re.compile(r"\w+")
+
+
+def _features(text: str) -> list[str]:
+    text = text.lower()
+    words = _WORD.findall(text)
+    trigrams = [text[i : i + 3] for i in range(max(0, len(text) - 2))]
+    return words + trigrams
+
+
+class HashEmbedder:
+    """Deterministic, offline hashed bag-of-features embedding (L2-normalized).
+
+    Good for tests and small/offline deployments; not as expressive as a learned
+    model. Swap for ``OpenAIEmbedder`` (or your own) in production.
+    """
+
+    def __init__(self, dim: int = 256) -> None:
+        self.dim = dim
+
+    async def embed(self, text: str) -> list[float]:
+        vec = [0.0] * self.dim
+        for feature in _features(text):
+            digest = hashlib.md5(feature.encode()).hexdigest()  # noqa: S324 - non-crypto
+            vec[int(digest, 16) % self.dim] += 1.0
+        norm = math.sqrt(sum(v * v for v in vec))
+        return [v / norm for v in vec] if norm else vec
+
+
+class OpenAIEmbedder:
+    """Embeds via the OpenAI embeddings API (lazy client; injectable for tests)."""
+
+    def __init__(
+        self,
+        model: str = "text-embedding-3-small",
+        *,
+        client: Any = None,
+        api_key: str | None = None,
+    ) -> None:
+        self.model = model
+        self._client = client
+        self._api_key = api_key
+
+    def _ensure_client(self) -> Any:
+        if self._client is None:
+            import openai
+
+            self._client = openai.AsyncOpenAI(api_key=self._api_key)
+        return self._client
+
+    async def embed(self, text: str) -> list[float]:
+        response = await self._ensure_client().embeddings.create(model=self.model, input=text)
+        return list(response.data[0].embedding)

spine_backends/memory.py

@@ -0,0 +1,99 @@
+"""In-process memory backends — semantic vector recall and simple recency buffer.
+
+Both implement the core ``Memory`` protocol. ``InMemoryVectorMemory`` takes any
+``Embedder`` (default :class:`HashEmbedder`), so users choose how text is
+embedded. ``BufferMemory`` is non-semantic recency recall for the simple case.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from spine_backends.embeddings import HashEmbedder
+from spine_core.memory import Embedder, MemoryHit, MemoryRecord
+from spine_core.registry import register_memory
+
+
+def _cosine(a: list[float], b: list[float]) -> float:
+    return sum(x * y for x, y in zip(a, b, strict=True))  # inputs are L2-normalized
+
+
+class InMemoryVectorMemory:
+    """Process-local vector memory; recall by embedding cosine similarity."""
+
+    def __init__(self, *, embedder: Embedder | None = None, dim: int = 256) -> None:
+        self.embedder: Embedder = embedder or HashEmbedder(dim)
+        self.dim = dim
+        self._records: list[tuple[MemoryRecord, list[float]]] = []
+
+    async def save(
+        self,
+        content: str,
+        *,
+        session_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> MemoryRecord:
+        record = MemoryRecord(
+            id=uuid.uuid4().hex, content=content, session_id=session_id, metadata=metadata or {}
+        )
+        self._records.append((record, await self.embedder.embed(content)))
+        return record
+
+    async def search(
+        self, query: str, *, k: int = 5, session_id: str | None = None
+    ) -> list[MemoryHit]:
+        qv = await self.embedder.embed(query)
+        hits = [
+            MemoryHit(record=record, score=_cosine(qv, vec))
+            for record, vec in self._records
+            if session_id is None or record.session_id == session_id
+        ]
+        hits.sort(key=lambda h: h.score, reverse=True)
+        return hits[:k]
+
+    async def load(self, session_id: str, *, limit: int = 20) -> list[MemoryRecord]:
+        records = [r for r, _ in self._records if r.session_id == session_id]
+        return records[-limit:]
+
+
+class BufferMemory:
+    """Non-semantic recency memory: ``search`` returns the most recent records.
+
+    Cheap and predictable when similarity is not needed (e.g. a rolling notes
+    buffer). ``search`` ignores the query text.
+    """
+
+    def __init__(self) -> None:
+        self._records: list[MemoryRecord] = []
+
+    async def save(
+        self,
+        content: str,
+        *,
+        session_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> MemoryRecord:
+        record = MemoryRecord(
+            id=uuid.uuid4().hex, content=content, session_id=session_id, metadata=metadata or {}
+        )
+        self._records.append(record)
+        return record
+
+    async def search(
+        self, query: str, *, k: int = 5, session_id: str | None = None
+    ) -> list[MemoryHit]:
+        pool = [r for r in self._records if session_id is None or r.session_id == session_id]
+        return [MemoryHit(record=r, score=1.0) for r in reversed(pool[-k:])]
+
+    async def load(self, session_id: str, *, limit: int = 20) -> list[MemoryRecord]:
+        records = [r for r in self._records if r.session_id == session_id]
+        return records[-limit:]
+
+
+def register() -> None:
+    register_memory("vector", lambda **cfg: InMemoryVectorMemory(**cfg))
+    register_memory("buffer", lambda **_: BufferMemory())
+
+
+register()

spine_backends/migrations.py

@@ -0,0 +1,39 @@
+"""State schema migration registry.
+
+A checkpoint written by old code (``version=1``) may be resumed by new code
+(``version=2``). Backends call :func:`migrate` on the raw dict before validating,
+walking registered upgrade functions one version at a time.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from spine_core.state import STATE_VERSION
+
+Migration = Callable[[dict[str, Any]], dict[str, Any]]
+_MIGRATIONS: dict[int, Migration] = {}
+
+
+def register_migration(from_version: int, fn: Migration) -> None:
+    """Register an upgrade from ``from_version`` to ``from_version + 1``."""
+    _MIGRATIONS[from_version] = fn
+
+
+def migrate(raw: dict[str, Any]) -> dict[str, Any]:
+    """Upgrade a raw state dict to the current ``STATE_VERSION``."""
+    version = int(raw.get("version", 1))
+    while version < STATE_VERSION:
+        fn = _MIGRATIONS.get(version)
+        if fn is None:
+            raise ValueError(
+                f"cannot resume: no migration from state version {version} "
+                f"(current is {STATE_VERSION})"
+            )
+        raw = fn(raw)
+        new_version = int(raw.get("version", version + 1))
+        if new_version <= version:  # guard against a migration that doesn't advance
+            raise ValueError(f"migration from version {version} did not advance the version")
+        version = new_version
+    return raw

spine_backends/pgvector.py

@@ -0,0 +1,140 @@
+"""pgvector memory backend — semantic recall backed by Postgres + pgvector.
+
+Scales the vector memory beyond one process. ``asyncpg`` is imported lazily;
+the ``pgvector`` extension must be installed in the database. Integration is
+exercised when ``SPINE_TEST_PG_DSN`` is set.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+from spine_backends.embeddings import HashEmbedder
+from spine_core.memory import Embedder, MemoryHit, MemoryRecord
+from spine_core.registry import register_memory
+
+
+class PgVectorMemory:
+    """``Memory`` over Postgres + pgvector with cosine-distance recall."""
+
+    def __init__(
+        self,
+        dsn: str,
+        *,
+        embedder: Embedder | None = None,
+        dim: int = 256,
+        table: str = "spine_memory",
+        pool: Any = None,
+    ) -> None:
+        self.dsn = dsn
+        self.embedder: Embedder = embedder or HashEmbedder(dim)
+        self.dim = dim
+        self.table = table
+        self._pool = pool
+
+    async def _ensure_pool(self) -> Any:
+        if self._pool is None:
+            import asyncpg
+
+            self._pool = await asyncpg.create_pool(self.dsn)
+        async with self._pool.acquire() as conn:
+            await conn.execute("CREATE EXTENSION IF NOT EXISTS vector")
+            await conn.execute(
+                f"""
+                CREATE TABLE IF NOT EXISTS {self.table} (
+                    id         TEXT PRIMARY KEY,
+                    session_id TEXT,
+                    content    TEXT NOT NULL,
+                    metadata   JSONB NOT NULL DEFAULT '{{}}',
+                    embedding  vector({self.dim}) NOT NULL,
+                    ts         TIMESTAMPTZ NOT NULL DEFAULT now()
+                )
+                """
+            )
+        return self._pool
+
+    @staticmethod
+    def _vec_literal(vec: list[float]) -> str:
+        return "[" + ",".join(repr(x) for x in vec) + "]"
+
+    async def save(
+        self,
+        content: str,
+        *,
+        session_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> MemoryRecord:
+        pool = await self._ensure_pool()
+        record = MemoryRecord(
+            id=uuid.uuid4().hex, content=content, session_id=session_id, metadata=metadata or {}
+        )
+        embedding = self._vec_literal(await self.embedder.embed(content))
+        async with pool.acquire() as conn:
+            await conn.execute(
+                f"INSERT INTO {self.table} (id, session_id, content, metadata, embedding) "
+                f"VALUES ($1, $2, $3, $4::jsonb, $5::vector)",
+                record.id,
+                session_id,
+                content,
+                json.dumps(record.metadata),
+                embedding,
+            )
+        return record
+
+    async def search(
+        self, query: str, *, k: int = 5, session_id: str | None = None
+    ) -> list[MemoryHit]:
+        pool = await self._ensure_pool()
+        embedding = self._vec_literal(await self.embedder.embed(query))
+        where = "WHERE session_id = $2" if session_id is not None else ""
+        args: list[Any] = [embedding] + ([session_id] if session_id is not None else [])
+        async with pool.acquire() as conn:
+            rows = await conn.fetch(
+                f"SELECT id, session_id, content, metadata, "
+                f"1 - (embedding <=> $1::vector) AS score "
+                f"FROM {self.table} {where} ORDER BY embedding <=> $1::vector LIMIT {int(k)}",
+                *args,
+            )
+        return [
+            MemoryHit(
+                record=MemoryRecord(
+                    id=row["id"],
+                    session_id=row["session_id"],
+                    content=row["content"],
+                    metadata=json.loads(row["metadata"])
+                    if isinstance(row["metadata"], str)
+                    else row["metadata"],
+                ),
+                score=float(row["score"]),
+            )
+            for row in rows
+        ]
+
+    async def load(self, session_id: str, *, limit: int = 20) -> list[MemoryRecord]:
+        pool = await self._ensure_pool()
+        async with pool.acquire() as conn:
+            rows = await conn.fetch(
+                f"SELECT id, session_id, content, metadata FROM {self.table} "
+                f"WHERE session_id = $1 ORDER BY ts DESC LIMIT {int(limit)}",
+                session_id,
+            )
+        return [
+            MemoryRecord(
+                id=row["id"],
+                session_id=row["session_id"],
+                content=row["content"],
+                metadata=json.loads(row["metadata"])
+                if isinstance(row["metadata"], str)
+                else row["metadata"],
+            )
+            for row in rows
+        ]
+
+
+def register() -> None:
+    register_memory("pgvector", lambda dsn="", **cfg: PgVectorMemory(dsn, **cfg))
+
+
+register()

spine_backends/postgres.py

@@ -0,0 +1,85 @@
+"""Postgres checkpoint backend — durable state with optimistic locking.
+
+Uses ``asyncpg`` (imported lazily; inject a ``pool`` for tests). Integration is
+exercised against a real database when ``SPINE_TEST_PG_DSN`` is set; the module
+itself imports nothing heavy at top level.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from spine_backends.migrations import migrate
+from spine_core.registry import register_checkpoint
+from spine_core.state import State
+
+
+class PostgresCheckpoint:
+    """Durable :class:`~spine_core.checkpoint.CheckpointStore` over Postgres."""
+
+    def __init__(self, dsn: str, *, pool: Any = None, table: str = "spine_checkpoints") -> None:
+        self.dsn = dsn
+        self.table = table
+        self._pool = pool
+
+    async def _ensure_pool(self) -> Any:
+        if self._pool is None:
+            import asyncpg
+
+            self._pool = await asyncpg.create_pool(self.dsn)
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                f"""
+                CREATE TABLE IF NOT EXISTS {self.table} (
+                    session_id TEXT PRIMARY KEY,
+                    version    INTEGER NOT NULL,
+                    revision   BIGINT  NOT NULL DEFAULT 1,
+                    data       JSONB   NOT NULL,
+                    updated    TIMESTAMPTZ NOT NULL DEFAULT now()
+                )
+                """
+            )
+        return self._pool
+
+    async def put(self, state: State) -> None:
+        pool = await self._ensure_pool()
+        async with pool.acquire() as conn:
+            await conn.execute(
+                f"""
+                INSERT INTO {self.table} (session_id, version, revision, data)
+                VALUES ($1, $2, 1, $3::jsonb)
+                ON CONFLICT (session_id) DO UPDATE SET
+                    version  = EXCLUDED.version,
+                    revision = {self.table}.revision + 1,
+                    data     = EXCLUDED.data,
+                    updated  = now()
+                """,
+                state.session_id,
+                state.version,
+                state.model_dump_json(),
+            )
+
+    async def get(self, session_id: str) -> State | None:
+        pool = await self._ensure_pool()
+        async with pool.acquire() as conn:
+            row = await conn.fetchrow(
+                f"SELECT data FROM {self.table} WHERE session_id = $1", session_id
+            )
+        if row is None:
+            return None
+        data: Any = row["data"]
+        raw = json.loads(data) if isinstance(data, str) else data
+        return State.model_validate(migrate(raw))
+
+    async def delete(self, session_id: str) -> None:
+        pool = await self._ensure_pool()
+        async with pool.acquire() as conn:
+            await conn.execute(f"DELETE FROM {self.table} WHERE session_id = $1", session_id)
+
+
+def register() -> None:
+    register_checkpoint("postgres", lambda dsn="", **_: PostgresCheckpoint(dsn))
+
+
+register()

spine_backends/redis.py

@@ -0,0 +1,58 @@
+"""Redis checkpoint backend — durable state for distributed workers.
+
+The ``redis`` client is imported lazily and may be injected (tests use a fake),
+so importing this module never requires the dependency or a server.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from spine_backends.migrations import migrate
+from spine_core.registry import register_checkpoint
+from spine_core.state import State
+
+
+class RedisCheckpoint:
+    """Durable :class:`~spine_core.checkpoint.CheckpointStore` over Redis."""
+
+    def __init__(
+        self,
+        url: str = "redis://localhost:6379",
+        *,
+        client: Any = None,
+        prefix: str = "spine:checkpoint:",
+    ) -> None:
+        self.url = url
+        self.prefix = prefix
+        self._client = client
+
+    def _ensure_client(self) -> Any:
+        if self._client is None:
+            import redis.asyncio as redis
+
+            self._client = redis.from_url(self.url, decode_responses=True)
+        return self._client
+
+    def _key(self, session_id: str) -> str:
+        return f"{self.prefix}{session_id}"
+
+    async def put(self, state: State) -> None:
+        await self._ensure_client().set(self._key(state.session_id), state.model_dump_json())
+
+    async def get(self, session_id: str) -> State | None:
+        raw = await self._ensure_client().get(self._key(session_id))
+        if raw is None:
+            return None
+        return State.model_validate(migrate(json.loads(raw)))
+
+    async def delete(self, session_id: str) -> None:
+        await self._ensure_client().delete(self._key(session_id))
+
+
+def register() -> None:
+    register_checkpoint("redis", lambda url="redis://localhost:6379", **_: RedisCheckpoint(url))
+
+
+register()