relio 0.1.0__py3-none-any.whl

relio/__init__.py

@@ -0,0 +1,24 @@
+from .ai import RelioAI
+from .memory import Memory
+from .record import MemoryRecord, MemoryType, Relation, Scope
+from .interchange import (
+    export_records,
+    import_records,
+    import_record_objects,
+    from_mem0,
+)
+from .mcp_server import build_mcp_server
+
+__all__ = [
+    "RelioAI",
+    "Memory",
+    "MemoryRecord",
+    "MemoryType",
+    "Relation",
+    "Scope",
+    "export_records",
+    "import_records",
+    "import_record_objects",
+    "from_mem0",
+    "build_mcp_server",
+]

relio/agents.py

@@ -0,0 +1,72 @@
+# relio/agents.py
+from __future__ import annotations
+
+from typing import Any, Iterator, Optional
+
+from .record import MemoryRecord, Scope
+
+
+class Agent:
+    """A bounded agent context: its own memory namespace, tool slice, config,
+    and session. Private by default — it sees only its own space and the tools
+    it was granted.
+    """
+
+    def __init__(
+        self,
+        ai: Any,
+        name: str,
+        *,
+        space: Optional[Scope] = None,
+        tools: Optional[list[str]] = None,
+        system: str = "",
+        model: Optional[str] = None,
+        recall_limit: int = 5,
+    ) -> None:
+        self.ai = ai
+        self.name = name
+        self.space = space or Scope(agent=name)  # its own memory namespace
+        self._allowed: Optional[set[str]] = set(tools) if tools is not None else None
+        self.system = system
+        self.model = model
+        self.recall_limit = recall_limit
+
+    # --- memory namespace (isolated) ----------------------------------------
+
+    def remember(self, content: str, **kwargs: Any) -> MemoryRecord:
+        return self.ai.remember(content, scope=self.space, **kwargs)
+
+    def recall(self, query: str, limit: Optional[int] = None) -> list[MemoryRecord]:
+        return self.ai.recall(query, scope=self.space, limit=limit or self.recall_limit)
+
+    def history(self, limit: int = 20) -> list[MemoryRecord]:
+        return self.ai.memory.history(self.space, limit=limit)
+
+    # --- tool slice (granted subset of the exposure map) --------------------
+
+    def tools(self) -> list[str]:
+        names = self.ai.tools.names()
+        return names if self._allowed is None else [n for n in names if n in self._allowed]
+
+    def call_tool(self, name: str, **kwargs: Any) -> Any:
+        if self._allowed is not None and name not in self._allowed:
+            raise PermissionError(f"agent {self.name!r} may not call tool {name!r}")
+        return self.ai.call_tool(name, **kwargs)
+
+    # --- reasoning (scoped to this agent) -----------------------------------
+
+    def chat(self, message: str, **kwargs: Any) -> Iterator[str]:
+        if self.ai.provider is None:
+            raise RuntimeError("agent chat needs an LLM provider")
+        from .server.agent import run_chat
+
+        prefix = (self.system + "\n\n") if self.system else ""
+        return run_chat(
+            self.ai.memory,
+            self.ai.provider,
+            message,
+            self.space,
+            limit=self.recall_limit,
+            system_prefix=prefix,
+            **kwargs,
+        )

relio/ai.py

@@ -0,0 +1,190 @@
+# relio/ai.py
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Iterator, Optional, Union
+
+from .exposure import ExposureMap
+from .memory import Memory
+from .record import MemoryRecord, MemoryType, Relation, Scope
+
+
+class RelioAI:
+    """The called-in AI component: one seam composing the AI-system components
+    (memory/RAG, embeddings, graph, structured query, reasoning, MCP interop).
+
+    The LLM is optional — construct it with no provider for a pure
+    memory/retrieval/data component, and add a provider when you need `chat`.
+    """
+
+    def __init__(
+        self,
+        memory: Optional[Memory] = None,
+        provider: Optional[object] = None,
+        *,
+        path: str = "relio.db",
+        embedder: Optional[object] = None,
+        database_url: Optional[str] = None,
+    ) -> None:
+        self.memory = memory or Memory(
+            path=path, embedder=embedder, database_url=database_url
+        )
+        self.provider = provider
+        self.tools = ExposureMap()  # the governed surface the AI may call
+
+    # --- knowledge & retrieval ----------------------------------------------
+
+    def remember(
+        self,
+        content: str,
+        type: MemoryType = MemoryType.SEMANTIC,
+        scope: Optional[Scope] = None,
+        **kwargs: Any,
+    ) -> MemoryRecord:
+        return self.memory.add(content, type=type, scope=scope, **kwargs)
+
+    def recall(
+        self, query: str, scope: Optional[Scope] = None, limit: int = 5
+    ) -> list[MemoryRecord]:
+        return self.memory.recall(query, scope=scope, limit=limit)
+
+    def recall_text(self, query: str, **kwargs: Any) -> str:
+        return self.memory.recall_text(query, **kwargs)
+
+    def embed(self, texts: Union[str, list[str]]) -> Union[list[float], list[list[float]]]:
+        if isinstance(texts, str):
+            return self.memory.embedder.embed(texts)
+        return self.memory.embedder.embed_batch(list(texts))
+
+    # --- graph ---------------------------------------------------------------
+
+    def add_node(self, content: str, **kwargs: Any) -> MemoryRecord:
+        return self.memory.add_node(content, **kwargs)
+
+    def add_edge(self, source_id: str, predicate: str, target_id: str) -> MemoryRecord:
+        return self.memory.add_edge(source_id, predicate, target_id)
+
+    def neighbors(self, node_id: str, predicate: Optional[str] = None) -> list[MemoryRecord]:
+        return self.memory.neighbors(node_id, predicate=predicate)
+
+    def in_neighbors(self, node_id: str, predicate: Optional[str] = None) -> list[MemoryRecord]:
+        return self.memory.in_neighbors(node_id, predicate=predicate)
+
+    def traverse(self, start_id: str, depth: int = 1, predicate: Optional[str] = None) -> list[MemoryRecord]:
+        return self.memory.traverse(start_id, depth=depth, predicate=predicate)
+
+    # --- structured query ----------------------------------------------------
+
+    def query(
+        self,
+        type: Optional[MemoryType] = None,
+        scope: Optional[Scope] = None,
+        where: Optional[dict[str, str]] = None,
+        limit: int = 100,
+    ) -> list[MemoryRecord]:
+        return self.memory.query(type=type, scope=scope, where=where, limit=limit)
+
+    def transaction(self):
+        return self.memory.transaction()
+
+    # --- reasoning -----------------------------------------------------------
+
+    @property
+    def has_llm(self) -> bool:
+        return self.provider is not None
+
+    def chat(
+        self, message: str, scope: Optional[Scope] = None, **kwargs: Any
+    ) -> Iterator[str]:
+        if self.provider is None:
+            raise RuntimeError(
+                "RelioAI.chat needs an LLM provider; construct RelioAI(provider=...)"
+            )
+        from .server.agent import run_chat
+
+        return run_chat(self.memory, self.provider, message, scope or Scope(), **kwargs)
+
+    # --- structured / multimodal extraction (D6) ----------------------------
+
+    def _require_provider(self, what: str) -> None:
+        if self.provider is None:
+            raise RuntimeError(f"RelioAI.{what} needs an LLM provider")
+
+    def extract(self, text: str, schema: Optional[dict] = None) -> dict:
+        """Extract structured data from text into `schema`."""
+        self._require_provider("extract")
+        return self.provider.extract(text, schema=schema)
+
+    def extract_file(
+        self,
+        file: Union[str, Path, bytes, bytearray],
+        schema: Optional[dict] = None,
+        media_type: str = "application/pdf",
+    ) -> dict:
+        """Extract structured data from a file (PDF/image) into `schema` — the
+        path for "read this drawing/scan and give me a bill"."""
+        self._require_provider("extract_file")
+        data = bytes(file) if isinstance(file, (bytes, bytearray)) else Path(file).read_bytes()
+        return self.provider.extract("", schema=schema, image_bytes=data, media_type=media_type)
+
+    # --- tools / exposure map (D3) ------------------------------------------
+
+    def tool(self, fn=None, *, name: Optional[str] = None, description: Optional[str] = None):
+        """Register an app operation the AI may call (decorator)."""
+        return self.tools.tool(fn, name=name, description=description)
+
+    def expose(self, obj: Any, fields: list[str]) -> dict[str, Any]:
+        """Field allowlist: project `obj` to only `fields` for AI consumption."""
+        return ExposureMap.project(obj, fields)
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        return [
+            {"name": s.name, "description": s.description, "parameters": s.parameters}
+            for s in self.tools.list()
+        ]
+
+    def call_tool(self, name: str, **kwargs: Any) -> Any:
+        return self.tools.call(name, **kwargs)
+
+    # --- agents (D4) ---------------------------------------------------------
+
+    def agent(
+        self,
+        name: str,
+        *,
+        space: Optional[Scope] = None,
+        tools: Optional[list[str]] = None,
+        system: str = "",
+        model: Optional[str] = None,
+        recall_limit: int = 5,
+    ):
+        """Construct a bounded agent: its own memory namespace + tool slice +
+        config + session. Private by default."""
+        from .agents import Agent
+
+        return Agent(
+            self,
+            name,
+            space=space,
+            tools=tools,
+            system=system,
+            model=model,
+            recall_limit=recall_limit,
+        )
+
+    # --- interop -------------------------------------------------------------
+
+    def mcp_server(self, include_tools: bool = True):
+        """The FastMCP server exposing this memory (add/recall) and — when
+        `include_tools` — the exposure-map tools, to external agents."""
+        from .mcp_server import build_mcp_server
+
+        server, tools = build_mcp_server(self.memory)
+        if include_tools:
+            for spec in self.tools.list():
+                server.tool()(spec.fn)
+                tools[spec.name] = spec.fn
+        return server, tools
+
+    def close(self) -> None:
+        self.memory.close()

relio/backends/base.py

@@ -0,0 +1,56 @@
+# relio/backends/base.py
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import ContextManager, Optional
+
+from ..record import MemoryRecord, MemoryType, Scope
+
+
+class StorageBackend(ABC):
+    """Persistence contract. Callers (Memory, RecallEngine) depend only on this."""
+
+    @abstractmethod
+    def add(self, record: MemoryRecord, embedding: list[float] | None) -> None:
+        """Insert or replace a record; store its embedding if provided."""
+
+    @abstractmethod
+    def get(self, record_id: str) -> MemoryRecord | None:
+        ...
+
+    @abstractmethod
+    def delete(self, record_id: str) -> bool:
+        """Return True if a row was removed."""
+
+    @abstractmethod
+    def search(self, embedding: list[float], k: int) -> list[tuple[MemoryRecord, float]]:
+        """Return up to k nearest records as (record, distance), ascending distance."""
+
+    @abstractmethod
+    def all(self) -> list[MemoryRecord]:
+        """Return every record in insertion order (oldest first).
+
+        History relies on this ordering; backends must preserve it.
+        """
+
+    @abstractmethod
+    def query(
+        self,
+        *,
+        type: Optional[MemoryType] = None,
+        scope: Optional[Scope] = None,
+        metadata: Optional[dict[str, str]] = None,
+        limit: int = 100,
+    ) -> list[MemoryRecord]:
+        """Structured (non-semantic) filter by exact type / scope / metadata
+        equality, returned in insertion order. Unlike search(), this includes
+        records with no embedding."""
+
+    @abstractmethod
+    def transaction(self) -> "ContextManager[None]":
+        """Context manager grouping writes into one atomic unit: all commit on
+        clean exit, all roll back if the block raises."""
+
+    @abstractmethod
+    def close(self) -> None:
+        ...

relio/backends/postgres.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import re
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Iterator, Optional
+
+from ..record import MemoryRecord, MemoryType, Scope
+from .base import StorageBackend
+
+_KEY = re.compile(r"^\w+$")  # guard interpolated json paths against injection
+
+
+def _vector_literal(embedding: list[float]) -> str:
+    """pgvector text form: [a,b,c]."""
+    return "[" + ",".join(str(float(x)) for x in embedding) + "]"
+
+
+def _to_record(doc) -> MemoryRecord:
+    # psycopg returns JSONB as a parsed dict; tolerate text too.
+    if isinstance(doc, (dict, list)):
+        return MemoryRecord.model_validate(doc)
+    return MemoryRecord.model_validate_json(doc)
+
+
+class PostgresBackend(StorageBackend):
+    """Postgres + pgvector backend — behaviour-identical to SQLiteBackend.
+
+    The scale path for high write-concurrency or many millions of vectors. A
+    connection **pool** lets independent requests run concurrently (no global
+    lock). Within `transaction()`, one connection is bound to the current
+    context so nested writes share it and commit atomically.
+    """
+
+    def __init__(self, dsn: str, dim: int = 384, pool_size: int = 10) -> None:
+        from psycopg_pool import ConnectionPool  # lazy: only when Postgres is used
+
+        self.dim = dim
+        # Holds the transaction's connection for the current context (else None).
+        self._active: ContextVar[Optional[object]] = ContextVar(
+            "relio_pg_active", default=None
+        )
+        self._pool = ConnectionPool(
+            dsn, min_size=1, max_size=pool_size, kwargs={"autocommit": True}, open=True
+        )
+        self._init_schema()
+
+    @contextmanager
+    def _conn(self) -> Iterator[object]:
+        """Yield the transaction-bound connection if inside one, else a pooled one."""
+        active = self._active.get()
+        if active is not None:
+            yield active
+        else:
+            with self._pool.connection() as conn:
+                yield conn
+
+    def _init_schema(self) -> None:
+        with self._conn() as conn, conn.cursor() as cur:
+            cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
+            cur.execute(
+                f"""
+                CREATE TABLE IF NOT EXISTS records (
+                    rid        BIGSERIAL PRIMARY KEY,
+                    id         TEXT UNIQUE NOT NULL,
+                    doc        JSONB NOT NULL,
+                    expires_at DOUBLE PRECISION,
+                    embedding  vector({self.dim})
+                )
+                """
+            )
+            # GIN index makes structured query() (Feature J) indexed on jsonb.
+            cur.execute("CREATE INDEX IF NOT EXISTS idx_doc_gin ON records USING GIN (doc)")
+
+    @staticmethod
+    def _expires_at(record: MemoryRecord) -> float | None:
+        if record.ttl is None:
+            return None
+        return record.created_at.timestamp() + record.ttl
+
+    def add(self, record: MemoryRecord, embedding: list[float] | None) -> None:
+        doc = record.model_dump_json()
+        vec = _vector_literal(embedding) if embedding is not None else None
+        with self._conn() as conn, conn.cursor() as cur:
+            cur.execute(
+                """
+                INSERT INTO records (id, doc, expires_at, embedding)
+                VALUES (%s, %s::jsonb, %s, %s::vector)
+                ON CONFLICT (id) DO UPDATE
+                SET doc = EXCLUDED.doc,
+                    expires_at = EXCLUDED.expires_at,
+                    embedding = EXCLUDED.embedding
+                """,
+                (record.id, doc, self._expires_at(record), vec),
+            )
+
+    def get(self, record_id: str) -> MemoryRecord | None:
+        with self._conn() as conn, conn.cursor() as cur:
+            cur.execute("SELECT doc FROM records WHERE id = %s", (record_id,))
+            row = cur.fetchone()
+        if row is None:
+            return None
+        return _to_record(row[0])
+
+    def delete(self, record_id: str) -> bool:
+        with self._conn() as conn, conn.cursor() as cur:
+            cur.execute("DELETE FROM records WHERE id = %s", (record_id,))
+            return cur.rowcount > 0
+
+    def all(self) -> list[MemoryRecord]:
+        with self._conn() as conn, conn.cursor() as cur:
+            cur.execute("SELECT doc FROM records ORDER BY rid")
+            rows = cur.fetchall()
+        return [_to_record(r[0]) for r in rows]
+
+    def search(self, embedding: list[float], k: int) -> list[tuple[MemoryRecord, float]]:
+        vec = _vector_literal(embedding)
+        with self._conn() as conn, conn.cursor() as cur:
+            cur.execute(
+                """
+                SELECT doc, embedding <-> %s::vector AS distance
+                FROM records
+                WHERE embedding IS NOT NULL
+                ORDER BY distance
+                LIMIT %s
+                """,
+                (vec, k),
+            )
+            rows = cur.fetchall()
+        return [(_to_record(r[0]), float(r[1])) for r in rows]
+
+    def query(
+        self,
+        *,
+        type: Optional[MemoryType] = None,
+        scope: Optional[Scope] = None,
+        metadata: Optional[dict[str, str]] = None,
+        limit: int = 100,
+    ) -> list[MemoryRecord]:
+        clauses: list[str] = []
+        params: list[object] = []
+        if type is not None:
+            clauses.append("doc->>'type' = %s")
+            params.append(type.value)
+        if scope is not None:
+            for field in ("tenant", "user", "agent", "session"):
+                value = getattr(scope, field)
+                if value is not None:
+                    clauses.append(f"doc#>>'{{scope,{field}}}' = %s")
+                    params.append(value)
+        for key, value in (metadata or {}).items():
+            if not _KEY.match(key):
+                raise ValueError(f"invalid metadata key: {key!r}")
+            clauses.append(f"doc#>>'{{metadata,{key}}}' = %s")
+            params.append(value)
+        where = (" WHERE " + " AND ".join(clauses)) if clauses else ""
+        params.append(limit)
+        with self._conn() as conn, conn.cursor() as cur:
+            cur.execute(f"SELECT doc FROM records{where} ORDER BY rid LIMIT %s", params)
+            rows = cur.fetchall()
+        return [_to_record(r[0]) for r in rows]
+
+    @contextmanager
+    def transaction(self) -> Iterator[None]:
+        # Borrow one connection, bind it for this context so nested add()/delete()
+        # reuse it, and wrap the block in a single BEGIN/COMMIT.
+        with self._pool.connection() as conn:
+            token = self._active.set(conn)
+            try:
+                with conn.transaction():
+                    yield
+            finally:
+                self._active.reset(token)
+
+    def close(self) -> None:
+        self._pool.close()