areev 0.0.0__py3-none-any.whl

areev/__init__.py

@@ -0,0 +1,49 @@
+"""Areev Python SDK — client library for the Areev knowledge database."""
+
+from areev.client import Areev, AsyncAreev
+from areev.types import (
+    AddOptions,
+    AddRequest,
+    AddResponse,
+    AreevConfig,
+    AreevError,
+    GetResponse,
+    GrainType,
+    HealthResponse,
+    RecallRequest,
+    RecallResponse,
+    RememberRequest,
+    RememberResponse,
+    SearchHit,
+    StatsResponse,
+    SupersedeRequest,
+    SupersedeResponse,
+)
+from areev.http import HttpClient
+
+__all__ = [
+    # High-level clients (recommended)
+    "Areev",
+    "AsyncAreev",
+    # Low-level async client
+    "HttpClient",
+    # Types
+    "AddOptions",
+    "AddRequest",
+    "AddResponse",
+    "AreevConfig",
+    "AreevError",
+    "GetResponse",
+    "GrainType",
+    "HealthResponse",
+    "RecallRequest",
+    "RecallResponse",
+    "RememberRequest",
+    "RememberResponse",
+    "SearchHit",
+    "StatsResponse",
+    "SupersedeRequest",
+    "SupersedeResponse",
+]
+
+__version__ = "0.1.0"

areev/client.py

@@ -0,0 +1,219 @@
+"""High-level Areev client with minimal boilerplate."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from areev.types import (
+    AddResponse,
+    AreevError,
+    GetResponse,
+    GrainType,
+    HealthResponse,
+    RecallResponse,
+    RememberResponse,
+    StatsResponse,
+    SupersedeResponse,
+)
+
+_DEFAULT_URL = "https://app.areev.ai"
+_DEFAULT_MEMORY = "default"
+
+
+def _resolve(
+    api_key: str | None,
+    url: str | None,
+    memory_id: str | None,
+) -> tuple[str | None, str, str]:
+    return (
+        api_key or os.environ.get("AREEV_API_KEY"),
+        (url or os.environ.get("AREEV_URL", _DEFAULT_URL)).rstrip("/"),
+        memory_id or os.environ.get("AREEV_MEMORY_ID", _DEFAULT_MEMORY),
+    )
+
+
+def _check(resp: httpx.Response) -> Any:
+    if resp.status_code >= 400:
+        raise AreevError(resp.status_code, resp.text)
+    if resp.status_code == 204 or not resp.content:
+        return None
+    return resp.json()
+
+
+def _compact(d: dict) -> dict:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+class Areev:
+    """Synchronous Areev client.
+
+    Reads ``AREEV_API_KEY``, ``AREEV_URL``, and ``AREEV_MEMORY_ID`` from the
+    environment when no explicit values are provided.
+
+    Usage::
+
+        from areev import Areev
+
+        areev = Areev()
+        areev.remember("John likes coffee")
+        results = areev.recall("what does John like?")
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        url: str | None = None,
+        memory_id: str | None = None,
+    ) -> None:
+        key, self._url, self._memory_id = _resolve(api_key, url, memory_id)
+        headers: dict[str, str] = {}
+        if key:
+            headers["X-API-Key"] = key
+        self._http = httpx.Client(headers=headers)
+
+    def _path(self, endpoint: str) -> str:
+        return f"{self._url}/api/memories/{self._memory_id}/{endpoint}"
+
+    # -- Primary methods -----------------------------------------------
+
+    def remember(self, text: str, *, sync: bool = True, **kwargs: Any) -> RememberResponse:
+        """Store a natural-language memory. Returns extraction details."""
+        body = _compact({"text": text, "sync": sync, **kwargs})
+        return RememberResponse(**_check(self._http.post(self._path("remember"), json=body)))
+
+    def recall(self, query: str, *, limit: int = 10, **kwargs: Any) -> RecallResponse:
+        """Search memories. Returns matching grains."""
+        params = _compact({"query": query, "limit": limit, **kwargs})
+        return RecallResponse(**_check(self._http.get(self._path("recall"), params=params)))
+
+    def forget(self, hash: str) -> None:
+        """Delete a memory by hash."""
+        _check(self._http.delete(self._path(f"grains/{hash}")))
+
+    # -- Low-level methods ---------------------------------------------
+
+    def add(self, grain_type: str | GrainType, /, **fields: Any) -> str:
+        """Add a typed grain. Returns the grain hash."""
+        grain = grain_type.value if isinstance(grain_type, GrainType) else grain_type
+        body = _compact({"grain_type": grain, **fields})
+        return AddResponse(**_check(self._http.post(self._path("add"), json=body))).hash
+
+    def get(self, hash: str) -> GetResponse:
+        """Get a grain by hash."""
+        return GetResponse(**_check(self._http.get(self._path(f"grains/{hash}"))))
+
+    def supersede(self, old_hash: str, grain_type: str | GrainType, /, **fields: Any) -> str:
+        """Update a grain. Returns the new hash."""
+        grain = grain_type.value if isinstance(grain_type, GrainType) else grain_type
+        body = _compact({"old_hash": old_hash, "grain_type": grain, **fields})
+        return SupersedeResponse(**_check(self._http.post(self._path("supersede"), json=body))).new_hash
+
+    def health(self) -> HealthResponse:
+        """Health check."""
+        return HealthResponse(**_check(self._http.get(f"{self._url}/health")))
+
+    def stats(self) -> StatsResponse:
+        """Database statistics."""
+        return StatsResponse(**_check(self._http.get(self._path("stats"))))
+
+    def flush(self) -> None:
+        """Flush write buffer."""
+        _check(self._http.post(self._path("flush")))
+
+    # -- Lifecycle -----------------------------------------------------
+
+    def close(self) -> None:
+        """Close the HTTP connection."""
+        self._http.close()
+
+    def __enter__(self) -> Areev:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncAreev:
+    """Async Areev client.
+
+    Same API as :class:`Areev` but all methods are coroutines.
+
+    Usage::
+
+        from areev import AsyncAreev
+
+        async with AsyncAreev() as areev:
+            await areev.remember("John likes coffee")
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        url: str | None = None,
+        memory_id: str | None = None,
+    ) -> None:
+        key, self._url, self._memory_id = _resolve(api_key, url, memory_id)
+        headers: dict[str, str] = {}
+        if key:
+            headers["X-API-Key"] = key
+        self._http = httpx.AsyncClient(headers=headers)
+
+    def _path(self, endpoint: str) -> str:
+        return f"{self._url}/api/memories/{self._memory_id}/{endpoint}"
+
+    async def remember(self, text: str, *, sync: bool = True, **kwargs: Any) -> RememberResponse:
+        """Store a natural-language memory. Returns extraction details."""
+        body = _compact({"text": text, "sync": sync, **kwargs})
+        return RememberResponse(**_check(await self._http.post(self._path("remember"), json=body)))
+
+    async def recall(self, query: str, *, limit: int = 10, **kwargs: Any) -> RecallResponse:
+        """Search memories. Returns matching grains."""
+        params = _compact({"query": query, "limit": limit, **kwargs})
+        return RecallResponse(**_check(await self._http.get(self._path("recall"), params=params)))
+
+    async def forget(self, hash: str) -> None:
+        """Delete a memory by hash."""
+        _check(await self._http.delete(self._path(f"grains/{hash}")))
+
+    async def add(self, grain_type: str | GrainType, /, **fields: Any) -> str:
+        """Add a typed grain. Returns the grain hash."""
+        grain = grain_type.value if isinstance(grain_type, GrainType) else grain_type
+        body = _compact({"grain_type": grain, **fields})
+        return AddResponse(**_check(await self._http.post(self._path("add"), json=body))).hash
+
+    async def get(self, hash: str) -> GetResponse:
+        """Get a grain by hash."""
+        return GetResponse(**_check(await self._http.get(self._path(f"grains/{hash}"))))
+
+    async def supersede(self, old_hash: str, grain_type: str | GrainType, /, **fields: Any) -> str:
+        """Update a grain. Returns the new hash."""
+        grain = grain_type.value if isinstance(grain_type, GrainType) else grain_type
+        body = _compact({"old_hash": old_hash, "grain_type": grain, **fields})
+        return SupersedeResponse(**_check(await self._http.post(self._path("supersede"), json=body))).new_hash
+
+    async def health(self) -> HealthResponse:
+        """Health check."""
+        return HealthResponse(**_check(await self._http.get(f"{self._url}/health")))
+
+    async def stats(self) -> StatsResponse:
+        """Database statistics."""
+        return StatsResponse(**_check(await self._http.get(self._path("stats"))))
+
+    async def flush(self) -> None:
+        """Flush write buffer."""
+        _check(await self._http.post(self._path("flush")))
+
+    async def close(self) -> None:
+        """Close the HTTP connection."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncAreev:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

areev/generated/__init__.py

@@ -0,0 +1 @@
+"""Auto-generated code from Areev specs. Do not edit manually."""

areev/grpc.py

@@ -0,0 +1,14 @@
+"""gRPC transport for the Areev SDK (requires 'grpc' extra)."""
+
+from __future__ import annotations
+
+try:
+    import grpc
+    from areev.generated import areev_pb2, areev_pb2_grpc
+except ImportError as e:
+    raise ImportError(
+        "gRPC transport requires the 'grpc' extra: pip install areev[grpc]"
+    ) from e
+
+# gRPC client implementation will be generated from proto stubs.
+# This module wraps the generated stubs with the same interface as HttpClient.

areev/http.py

@@ -0,0 +1,121 @@
+"""HTTP transport for the Areev SDK using httpx."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from areev.types import (
+    AddRequest,
+    AddResponse,
+    AreevConfig,
+    AreevError,
+    GetResponse,
+    HealthResponse,
+    RecallRequest,
+    RecallResponse,
+    RememberRequest,
+    RememberResponse,
+    StatsResponse,
+    SupersedeRequest,
+    SupersedeResponse,
+)
+
+
+class HttpClient:
+    """Async HTTP client for Areev.
+
+    Usage::
+
+        client = HttpClient(AreevConfig(url="http://localhost:4009", memory_id="default"))
+        resp = await client.add(AddRequest(grain_type="belief", fields={"subject": "john"}))
+    """
+
+    def __init__(self, config: AreevConfig) -> None:
+        self._base = config.url.rstrip("/")
+        self._memory_id = config.memory_id
+        headers: dict[str, str] = {}
+        if config.api_key:
+            headers["X-API-Key"] = config.api_key
+        self._client = httpx.AsyncClient(headers=headers)
+
+    def _url(self, path: str) -> str:
+        return f"{self._base}/api/memories/{self._memory_id}/{path}"
+
+    async def _handle(self, resp: httpx.Response) -> Any:
+        if resp.status_code >= 400:
+            raise AreevError(resp.status_code, resp.text)
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    async def add(self, req: AddRequest) -> AddResponse:
+        """Add a grain to memory."""
+        resp = await self._client.post(
+            self._url("add"),
+            json=req.model_dump(exclude_none=True),
+        )
+        return AddResponse(**(await self._handle(resp)))
+
+    async def remember(self, req: RememberRequest) -> RememberResponse:
+        """Ingest natural language text as memory.
+
+        Accepts free-form text, stores it as an Observation grain, and
+        extracts structured Belief grains (sync or async depending on
+        ``req.sync``).
+        """
+        resp = await self._client.post(
+            self._url("remember"),
+            json=req.model_dump(exclude_none=True),
+        )
+        return RememberResponse(**(await self._handle(resp)))
+
+    async def recall(self, req: RecallRequest) -> RecallResponse:
+        """Query (recall) grains from memory."""
+        params = req.model_dump(exclude_none=True)
+        resp = await self._client.get(self._url("recall"), params=params)
+        return RecallResponse(**(await self._handle(resp)))
+
+    async def get(self, hash: str) -> GetResponse:
+        """Get a grain by its hash."""
+        resp = await self._client.get(self._url(f"grains/{hash}"))
+        return GetResponse(**(await self._handle(resp)))
+
+    async def forget(self, hash: str) -> None:
+        """Forget (delete) a grain."""
+        resp = await self._client.delete(self._url(f"grains/{hash}"))
+        await self._handle(resp)
+
+    async def supersede(self, req: SupersedeRequest) -> SupersedeResponse:
+        """Supersede (update) a grain."""
+        resp = await self._client.post(
+            self._url("supersede"),
+            json=req.model_dump(exclude_none=True),
+        )
+        return SupersedeResponse(**(await self._handle(resp)))
+
+    async def health(self) -> HealthResponse:
+        """Get health status."""
+        resp = await self._client.get(f"{self._base}/health")
+        return HealthResponse(**(await self._handle(resp)))
+
+    async def stats(self) -> StatsResponse:
+        """Get database statistics."""
+        resp = await self._client.get(self._url("stats"))
+        return StatsResponse(**(await self._handle(resp)))
+
+    async def flush(self) -> None:
+        """Flush write buffer."""
+        resp = await self._client.post(self._url("flush"))
+        await self._handle(resp)
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> HttpClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

areev/types.py

@@ -0,0 +1,173 @@
+"""Core types for the Areev SDK."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class GrainType(str, Enum):
+    """Grain types supported by Areev."""
+
+    BELIEF = "belief"
+    EVENT = "event"
+    STATE = "state"
+    WORKFLOW = "workflow"
+    ACTION = "action"
+    OBSERVATION = "observation"
+    GOAL = "goal"
+    REASONING = "reasoning"
+    CONSENSUS = "consensus"
+    CONSENT = "consent"
+
+
+class AddOptions(BaseModel):
+    """Options for the add operation (import intelligence)."""
+
+    extract_event_date: bool | None = None
+    auto_relate: bool | None = None
+    extract_memories: bool | None = None
+    sync: bool | None = None
+
+
+class AddRequest(BaseModel):
+    """Request to add a grain."""
+
+    grain_type: GrainType
+    fields: dict[str, Any]
+    options: AddOptions | None = None
+
+
+class AddResponse(BaseModel):
+    """Response from adding a grain."""
+
+    hash: str
+
+
+class RecallRequest(BaseModel):
+    """Request to recall (query) grains."""
+
+    query: str | None = None
+    subject: str | None = None
+    relation: str | None = None
+    object: str | None = None
+    namespace: str | None = None
+    user_id: str | None = None
+    grain_type: str | None = None
+    limit: int | None = None
+    temporal_expr: str | None = None
+    tags: list[str] | None = None
+    deduplicate: bool | None = None
+    rerank: bool | None = None
+    query_expansion: bool | None = None
+    explanation: bool | None = None
+    min_score: float | None = None
+    diversity: float | None = None
+    recency_weight: float | None = None
+    entity: str | None = None
+    multi_hop: int | None = None
+
+    model_config = {"extra": "allow"}
+
+
+class SearchHit(BaseModel):
+    """A single search result."""
+
+    hash: str
+    grain_type: str
+    score: float
+    fields: dict[str, Any]
+    source_namespace: str | None = None
+    explanation: str | None = None
+    relative_time: str | None = None
+
+
+class RecallResponse(BaseModel):
+    """Response from a recall query."""
+
+    count: int
+    results: list[SearchHit]
+
+
+class SupersedeRequest(BaseModel):
+    """Request to supersede a grain."""
+
+    old_hash: str
+    grain_type: GrainType
+    fields: dict[str, Any]
+
+
+class SupersedeResponse(BaseModel):
+    """Response from superseding a grain."""
+
+    new_hash: str
+
+
+class RememberRequest(BaseModel):
+    """Request to ingest natural language text as memory."""
+
+    text: str
+    sync: bool = False
+    keep_source: bool = False
+    namespace: str | None = None
+    user_id: str | None = None
+    tags: list[str] | None = None
+    source_type: str | None = None
+    confidence: float | None = None
+    extract_event_date: bool | None = None
+    auto_relate: bool | None = None
+    created_at: int | None = None
+
+
+class RememberResponse(BaseModel):
+    """Response from the remember endpoint."""
+
+    source_hash: str
+    mode: str
+    extracted_count: int
+    source_forgotten: bool
+    extracted_hashes: list[str] | None = None
+    marker_status: str | None = None
+    warnings: list[str] | None = None
+
+
+class GetResponse(BaseModel):
+    """Grain detail response."""
+
+    hash: str
+    grain_type: str
+    fields: dict[str, Any]
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+
+    status: str
+    version: str
+
+
+class StatsResponse(BaseModel):
+    """Database statistics."""
+
+    total_grains: int
+    disk_space_bytes: int
+    store_size: str
+    type_counts: dict[str, int] = Field(default_factory=dict)
+
+
+class AreevConfig(BaseModel):
+    """Client configuration."""
+
+    url: str
+    memory_id: str
+    api_key: str | None = None
+
+
+class AreevError(Exception):
+    """Error raised by the Areev client."""
+
+    def __init__(self, status: int, message: str) -> None:
+        self.status = status
+        super().__init__(f"Areev API error ({status}): {message}")

areev-0.0.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: areev
+Version: 0.0.0
+Summary: Python SDK for the Areev knowledge database — HTTP, gRPC, and MCP transports
+Project-URL: Repository, https://github.com/AreevAI/areev-sdk-python
+Project-URL: Documentation, https://areev.ai/docs
+License-Expression: BUSL-1.1
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.26; extra == 'dev'
+Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: grpc
+Requires-Dist: grpcio>=1.60; extra == 'grpc'
+Requires-Dist: protobuf>=5.0; extra == 'grpc'
+Description-Content-Type: text/markdown
+
+# Areev Python SDK
+
+Python client library for the [Areev](https://areev.ai) knowledge database.
+
+## Installation
+
+```bash
+pip install areev
+```
+
+For gRPC transport:
+```bash
+pip install areev[grpc]
+```
+
+## Quick Start
+
+```python
+from areev import Areev
+
+areev = Areev()  # reads AREEV_API_KEY, AREEV_URL from env
+areev.remember("John likes coffee")
+
+results = areev.recall("what does John like?")
+for hit in results.results:
+    print(f"  {hit.grain_type}: {hit.fields}")
+```
+
+### Configuration
+
+The client reads from environment variables by default:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AREEV_API_KEY` | — | API key (sent as `X-API-Key` header) |
+| `AREEV_URL` | `https://app.areev.ai` | Server endpoint |
+| `AREEV_MEMORY_ID` | `default` | Memory database ID |
+
+Or pass them explicitly:
+
+```python
+areev = Areev(api_key="ar_...", url="https://dub.areev.ai", memory_id="my-memory")
+```
+
+### Async
+
+```python
+from areev import AsyncAreev
+
+async with AsyncAreev() as areev:
+    await areev.remember("John likes coffee")
+    results = await areev.recall("what does John like?")
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `remember(text)` | Store natural-language memory (LLM extracts structure) |
+| `recall(query)` | Search memories |
+| `forget(hash)` | Delete a memory by hash |
+| `add(grain_type, **fields)` | Add a typed grain (low-level) |
+| `get(hash)` | Get a grain by hash |
+| `supersede(old_hash, grain_type, **fields)` | Update a grain |
+| `health()` | Health check |
+| `stats()` | Database statistics |
+| `flush()` | Flush write buffer |
+
+### Low-Level Client
+
+For advanced use cases (custom request objects, full async control):
+
+```python
+from areev import HttpClient, AreevConfig, AddRequest, GrainType
+
+config = AreevConfig(url="http://localhost:4009", memory_id="default", api_key="your-key")
+async with HttpClient(config) as client:
+    resp = await client.add(AddRequest(
+        grain_type=GrainType.BELIEF,
+        fields={"subject": "john", "relation": "likes", "object": "coffee"},
+    ))
+```
+
+## Transports
+
+| Transport | Extra | Status |
+|-----------|-------|--------|
+| HTTP/REST | _(default)_ | Available |
+| gRPC | `areev[grpc]` | Available |
+| MCP | — | Planned |
+
+## Code Generation
+
+Generate gRPC stubs and Pydantic models from the Areev spec:
+
+```bash
+pip install areev[dev]
+./scripts/generate.sh
+```
+
+## License
+
+BUSL-1.1

areev-0.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+areev/__init__.py,sha256=1IuGtBdXYmz3tCsynmRAGDfPBDWhA51sHVWpUfp9C2M,971
+areev/client.py,sha256=AtValmqMsAAyp4yGhAqxIZAqiTnQCVCVDIaoWpSUtYQ,7768
+areev/grpc.py,sha256=8xhqniba-njixAgPy0N14YbGNSxqUlOsPePSrRIFcJ8,462
+areev/http.py,sha256=p1aMbHKtVKorufGkOWiWwh3XL0UV6Qw1U14Vem9Qyes,3976
+areev/types.py,sha256=iE-d7cYrTxK17uh37whGhUwE7J9DY5zX1-mlRwUDpsg,3862
+areev/generated/__init__.py,sha256=nvnu8PEosfcYv7xT2VzI_xlgqeRc1rnXAoIdK6zLQxQ,66
+areev-0.0.0.dist-info/METADATA,sha256=3RJYJ_hWCRCGFZJXHK8Gib9okmabKJnR1l-fAAPD6A4,3184
+areev-0.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+areev-0.0.0.dist-info/licenses/LICENSE,sha256=pAmHakG0ptbZ0By03_Nxza9WpIpfOOYxJnC_rTB2i7E,250
+areev-0.0.0.dist-info/RECORD,,

areev-0.0.0.dist-info/WHEEL

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

areev-0.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Business Source License 1.1
+
+Licensor: MindGryd Technologies Private Limited
+Licensed Work: Areev Python SDK
+
+The Licensed Work is provided under the terms of the Business Source License 1.1.
+See https://mariadb.com/bsl11/ for the full license text.