anamdb 1.0.0__py3-none-any.whl

anamdb/__init__.py

@@ -0,0 +1,31 @@
+"""AnamDB Python SDK — async client for the AnamDB neurosymbolic database engine."""
+
+from anamdb.client import AnamClient
+from anamdb.exceptions import (
+    AnamDBError,
+    ConnectionError,
+    QueryError,
+    ProtocolError,
+)
+from anamdb.models import (
+    QueryResult,
+    ServerHealth,
+    TableResponse,
+    RuleResponse,
+    ModelResponse,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AnamClient",
+    "AnamDBError",
+    "ConnectionError",
+    "QueryError",
+    "ProtocolError",
+    "QueryResult",
+    "ServerHealth",
+    "TableResponse",
+    "RuleResponse",
+    "ModelResponse",
+]

anamdb/client.py

@@ -0,0 +1,264 @@
+"""Async client for connecting to a running AnamDB server.
+
+Uses the JSON-over-TCP wire protocol defined in the AnamDB server module.
+Each command is a single JSON line; each response is a single JSON line back.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+from anamdb.exceptions import (
+    AnamDBError,
+    ConnectionError,
+    ProtocolError,
+    QueryError,
+)
+from anamdb.models import (
+    ModelResponse,
+    QueryResult,
+    RuleResponse,
+    ServerHealth,
+    TableResponse,
+)
+
+logger = logging.getLogger("anamdb")
+
+
+class AnamClient:
+    """Async client for the AnamDB neurosymbolic database engine.
+
+    Connects to a running AnamDB server over TCP and communicates using
+    the JSON-over-TCP wire protocol.
+
+    Use as an async context manager::
+
+        async with AnamClient("127.0.0.1:8080") as client:
+            result = await client.query("SELECT * FROM txns LIMIT 10")
+
+    Or manage the connection manually::
+
+        client = AnamClient("127.0.0.1:8080")
+        await client.connect()
+        result = await client.query("SELECT * FROM txns LIMIT 10")
+        await client.close()
+    """
+
+    def __init__(
+        self,
+        addr: str = "127.0.0.1:8080",
+        *,
+        connect_timeout: float = 5.0,
+        max_retries: int = 3,
+    ) -> None:
+        self._addr = addr
+        self._connect_timeout = connect_timeout
+        self._max_retries = max_retries
+
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+
+    # ── Connection lifecycle ──────────────────────────────────────────
+
+    async def connect(self) -> None:
+        """Establish the TCP connection to the AnamDB server."""
+        if self._writer is not None:
+            return  # Already connected.
+
+        host, _, port_str = self._addr.rpartition(":")
+        if not host:
+            host = "127.0.0.1"
+        port = int(port_str) if port_str else 8080
+
+        try:
+            self._reader, self._writer = await asyncio.wait_for(
+                asyncio.open_connection(host, port),
+                timeout=self._connect_timeout,
+            )
+            logger.info("Connected to AnamDB at %s", self._addr)
+        except asyncio.TimeoutError as exc:
+            raise ConnectionError(
+                f"Connection to {self._addr} timed out after {self._connect_timeout}s"
+            ) from exc
+        except OSError as exc:
+            raise ConnectionError(
+                f"Failed to connect to {self._addr}: {exc}"
+            ) from exc
+
+    async def close(self) -> None:
+        """Close the TCP connection."""
+        if self._writer is not None:
+            self._writer.close()
+            try:
+                await self._writer.wait_closed()
+            except Exception:
+                pass  # Best effort.
+            self._writer = None
+            self._reader = None
+            logger.info("Disconnected from AnamDB")
+
+    async def __aenter__(self) -> "AnamClient":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    # ── Wire protocol ────────────────────────────────────────────────
+
+    async def _send_command(self, cmd: dict) -> dict:
+        """Send a JSON command and receive the JSON response."""
+        if self._reader is None or self._writer is None:
+            raise ConnectionError("Not connected — call connect() first")
+
+        payload = json.dumps(cmd, separators=(",", ":")) + "\n"
+        self._writer.write(payload.encode())
+        await self._writer.drain()
+
+        line = await self._reader.readline()
+        if not line:
+            raise ConnectionError("Server closed the connection")
+
+        try:
+            return json.loads(line.decode())
+        except json.JSONDecodeError as exc:
+            raise ProtocolError(f"Invalid JSON response: {exc}") from exc
+
+    async def _send_with_retry(self, cmd: dict) -> dict:
+        """Send a command with automatic retry on transient failures."""
+        last_exc: Exception | None = None
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                return await self._send_command(cmd)
+            except ConnectionError as exc:
+                last_exc = exc
+                logger.warning(
+                    "Attempt %d/%d failed: %s",
+                    attempt,
+                    self._max_retries,
+                    exc,
+                )
+                # Try to reconnect.
+                await self.close()
+                try:
+                    await self.connect()
+                except ConnectionError:
+                    pass
+        raise last_exc or ConnectionError("All retry attempts failed")
+
+    # ── Public API ───────────────────────────────────────────────────
+
+    async def query(self, sql: str) -> QueryResult:
+        """Execute a SQL query on the AnamDB server.
+
+        Args:
+            sql: The SQL query string.
+
+        Returns:
+            A :class:`QueryResult` with row count, reasoning tree, and anomalies.
+
+        Raises:
+            QueryError: If the server reports a query execution error.
+        """
+        resp = await self._send_with_retry({"method": "query", "sql": sql})
+
+        if not resp.get("ok", False):
+            raise QueryError(
+                resp.get("error", "unknown server error"),
+                sql=sql,
+            )
+
+        return QueryResult(
+            row_count=resp.get("ipc_bytes", 0),
+            reasoning_tree=resp.get("reasoning_tree") or None,
+            anomalies=resp.get("anomalies", []),
+            raw_response=resp,
+        )
+
+    async def register_table(self, name: str, lance_path: str) -> TableResponse:
+        """Register a Lance dataset as a queryable table.
+
+        Args:
+            name: Logical table name.
+            lance_path: Filesystem path to the Lance dataset.
+        """
+        resp = await self._send_with_retry(
+            {"method": "register_table", "name": name, "lance_path": lance_path}
+        )
+        return TableResponse(
+            success=resp.get("ok", False),
+            message=resp.get("message", ""),
+        )
+
+    async def register_rule(self, name: str, datalog: str) -> RuleResponse:
+        """Register a Datalog rule as a query filter.
+
+        Args:
+            name: Rule name.
+            datalog: Datalog expression (e.g. ``"fraud_prob > 0.90 AND amount > 10000"``).
+        """
+        resp = await self._send_with_retry(
+            {"method": "register_rule", "name": name, "datalog": datalog}
+        )
+        return RuleResponse(
+            success=resp.get("ok", False),
+            message=resp.get("message", ""),
+        )
+
+    async def load_model(
+        self,
+        name: str,
+        version: str,
+        model_path: str,
+        function_id: str,
+        *,
+        num_features: int = 3,
+        avg_latency_ms: float = 1.0,
+        accuracy: float = 0.95,
+    ) -> ModelResponse:
+        """Load an ONNX model into the AnamDB model registry.
+
+        Args:
+            name: Model name (becomes the SQL function name).
+            version: Model version string.
+            model_path: Path to the ONNX model file.
+            function_id: SQL function identifier.
+            num_features: Number of input features.
+            avg_latency_ms: Expected average latency in milliseconds.
+            accuracy: Expected model accuracy (0.0–1.0).
+        """
+        resp = await self._send_with_retry(
+            {
+                "method": "load_model",
+                "name": name,
+                "version": version,
+                "model_path": model_path,
+                "function_id": function_id,
+                "num_features": num_features,
+                "avg_latency_ms": avg_latency_ms,
+                "accuracy": accuracy,
+            }
+        )
+        return ModelResponse(
+            success=resp.get("ok", False),
+            model_id=resp.get("model_id", ""),
+            message=resp.get("message", ""),
+        )
+
+    async def health(self) -> ServerHealth:
+        """Check the health of the AnamDB server.
+
+        Returns:
+            A :class:`ServerHealth` with server status and resource counts.
+        """
+        resp = await self._send_with_retry({"method": "health"})
+        return ServerHealth(
+            status=resp.get("status", "UNKNOWN"),
+            version=resp.get("version", "?"),
+            table_count=resp.get("tables", 0),
+            model_count=resp.get("models", 0),
+            rule_count=resp.get("rules", 0),
+        )

anamdb/exceptions.py

@@ -0,0 +1,25 @@
+"""Exception hierarchy for the AnamDB Python SDK."""
+
+
+class AnamDBError(Exception):
+    """Base exception for all AnamDB client errors."""
+
+
+class ConnectionError(AnamDBError):
+    """Raised when the client cannot connect to the AnamDB server."""
+
+
+class QueryError(AnamDBError):
+    """Raised when a SQL query fails on the server."""
+
+    def __init__(self, message: str, sql: str | None = None):
+        self.sql = sql
+        super().__init__(message)
+
+
+class ProtocolError(AnamDBError):
+    """Raised when the server sends an invalid or unexpected response."""
+
+
+class TimeoutError(AnamDBError):
+    """Raised when an operation exceeds the configured timeout."""

anamdb/models.py

@@ -0,0 +1,67 @@
+"""Data models for AnamDB responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class QueryResult:
+    """Result of a SQL query execution."""
+
+    row_count: int
+    """Number of rows returned (from server-reported ipc_bytes, or 0)."""
+
+    reasoning_tree: str | None = None
+    """Provenance reasoning trace (if provenance mode is enabled)."""
+
+    anomalies: list[str] = field(default_factory=list)
+    """Semantic anomaly descriptions detected during execution."""
+
+    raw_response: dict = field(default_factory=dict, repr=False)
+    """Full JSON response from the server."""
+
+
+@dataclass(frozen=True, slots=True)
+class ServerHealth:
+    """Server health status."""
+
+    status: str
+    """``'SERVING'`` or ``'NOT_SERVING'``."""
+
+    version: str
+    """AnamDB server version string."""
+
+    table_count: int = 0
+    """Number of registered tables."""
+
+    model_count: int = 0
+    """Number of loaded ONNX models."""
+
+    rule_count: int = 0
+    """Number of active Datalog rules."""
+
+
+@dataclass(frozen=True, slots=True)
+class TableResponse:
+    """Response from a table registration request."""
+
+    success: bool
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class RuleResponse:
+    """Response from a Datalog rule registration request."""
+
+    success: bool
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class ModelResponse:
+    """Response from a model loading request."""
+
+    success: bool
+    model_id: str
+    message: str

anamdb-1.0.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: anamdb
+Version: 1.0.0
+Summary: Python client for AnamDB — the AI-native neurosymbolic database engine.
+Project-URL: Homepage, https://jorge-nexsys.github.io/anam
+Project-URL: Repository, https://github.com/jorge-nexsys/anam
+Project-URL: Documentation, https://jorge-nexsys.github.io/anam
+Project-URL: Issues, https://github.com/jorge-nexsys/anam/issues
+Author: Jorge Martinez
+License-Expression: Apache-2.0
+Keywords: ai,arrow,database,datalog,neurosymbolic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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 :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: arrow
+Requires-Dist: pyarrow>=14.0; extra == 'arrow'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AnamDB Python SDK
+
+Python client for [AnamDB](https://github.com/jorge-nexsys/anam) — the AI-native neurosymbolic database engine.
+
+## Installation
+
+```bash
+pip install anamdb
+```
+
+For Arrow IPC support (decode query results into PyArrow tables):
+
+```bash
+pip install anamdb[arrow]
+```
+
+## Quick Start
+
+```python
+import asyncio
+from anamdb import AnamClient
+
+async def main():
+    # Connect to a running AnamDB server
+    async with AnamClient("127.0.0.1:8080") as client:
+        # Check server health
+        health = await client.health()
+        print(f"Server: {health.status} (v{health.version})")
+
+        # Register a table
+        await client.register_table("txns", "/data/transactions.lance")
+
+        # Register a Datalog rule
+        await client.register_rule("high_risk", "fraud_prob > 0.90 AND amount > 10000")
+
+        # Run a SQL query
+        result = await client.query(
+            "SELECT region, COUNT(1) AS count "
+            "FROM txns WHERE fraud_prob > 0.90 "
+            "GROUP BY region ORDER BY count DESC"
+        )
+
+        print(f"Rows: {result.row_count}")
+        if result.reasoning_tree:
+            print(f"Reasoning: {result.reasoning_tree}")
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### `AnamClient(addr, *, connect_timeout=5.0, max_retries=3)`
+
+Async context manager for connecting to an AnamDB server.
+
+**Methods:**
+
+| Method | Description |
+|:---|:---|
+| `query(sql)` | Execute a SQL query, returns `QueryResult` |
+| `register_table(name, lance_path)` | Register a Lance dataset as a table |
+| `register_rule(name, datalog)` | Register a Datalog rule |
+| `load_model(name, version, path, ...)` | Load an ONNX model |
+| `health()` | Server health check |
+
+### `QueryResult`
+
+| Field | Type | Description |
+|:---|:---|:---|
+| `row_count` | `int` | Number of rows returned |
+| `reasoning_tree` | `str \| None` | Provenance reasoning trace |
+| `anomalies` | `list[str]` | Semantic anomaly descriptions |
+| `raw_response` | `dict` | Full JSON response from server |
+
+### `ServerHealth`
+
+| Field | Type | Description |
+|:---|:---|:---|
+| `status` | `str` | `"SERVING"` or `"NOT_SERVING"` |
+| `version` | `str` | AnamDB server version |
+| `table_count` | `int` | Number of registered tables |
+| `model_count` | `int` | Number of loaded models |
+| `rule_count` | `int` | Number of Datalog rules |
+
+## License
+
+Apache License 2.0

anamdb-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+anamdb/__init__.py,sha256=4WI3wPGjQZNA_y-EKDqnYo4vQNHCSFgaQjbwmFSzYqA,591
+anamdb/client.py,sha256=t93O9vSJBJ_GCXzifTz8U9399iHlAq1AYeY_1dii30I,8895
+anamdb/exceptions.py,sha256=oC093XHIYyzWg6BpzPyorQGMhy_ve0jiSiPIwwITmyo,668
+anamdb/models.py,sha256=dagiwJ383jvXmp3z1c30cwkIIdt6wdD1ZwmlAIahlGI,1531
+anamdb-1.0.0.dist-info/METADATA,sha256=T1eT2mQAeFiT6rlieJV1P3tC41kL1Jgd4NhLsGD2l4w,3639
+anamdb-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+anamdb-1.0.0.dist-info/RECORD,,

anamdb-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any