tinyhumansai 0.1.0__tar.gz

tinyhumansai-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: tinyhumansai
+Version: 0.1.0
+Summary: Python SDK for TinyHumans API - ingest and delete memory
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# tinyhuman
+
+Python SDK for the [TinyHumans API](https://tinyhumans.ai).
+
+## Requirements
+
+- Python ≥ 3.9
+- `httpx >= 0.25`
+
+## Install
+
+```bash
+pip install tinyhuman
+```
+
+## Quick start (synchronous)
+
+```python
+from tinyhumansai import (
+    TinyHumanMemoryClient,
+    TinyHumanConfig,
+    IngestMemoryRequest,
+    ReadMemoryRequest,
+    DeleteMemoryRequest,
+    MemoryItem,
+)
+
+client = TinyHumanMemoryClient(TinyHumanConfig(token="your-api-key"))
+
+# Ingest (upsert) memory
+result = client.ingest_memory(
+    IngestMemoryRequest(
+        items=[
+            MemoryItem(
+                key="user-preference-theme",
+                content="User prefers dark mode",
+                namespace="preferences",
+                metadata={"source": "onboarding"},
+            )
+        ]
+    )
+)
+print(result)  # IngestMemoryResponse(ingested=1, updated=0, errors=0)
+
+# Read memory
+items = client.read_memory(ReadMemoryRequest(namespace="preferences"))
+print(items.count, items.items)
+
+# Delete by key
+client.delete_memory(DeleteMemoryRequest(key="user-preference-theme", namespace="preferences"))
+
+# Delete all user memory
+client.delete_memory(DeleteMemoryRequest(delete_all=True))
+```
+
+The client implements the context-manager protocol for deterministic cleanup:
+
+```python
+with TinyHumanMemoryClient(TinyHumanConfig(token="your-api-key")) as client:
+    result = client.read_memory()
+```
+
+## Async usage
+
+Use `AsyncTinyHumanMemoryClient` inside `async` code to avoid blocking the
+event loop (e.g. FastAPI, LangGraph async pipelines):
+
+```python
+import asyncio
+from tinyhumansai import AsyncTinyHumanMemoryClient, TinyHumanConfig, ReadMemoryRequest
+
+async def main():
+    async with AsyncTinyHumanMemoryClient(TinyHumanConfig(token="your-api-key")) as client:
+        result = await client.read_memory()
+        print(result.items)
+
+asyncio.run(main())
+```
+
+## API reference
+
+### `TinyHumanMemoryClient(config)` / `AsyncTinyHumanMemoryClient(config)`
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `config.token` | `str` | ✓ | JWT or API key |
+| `config.base_url` | `str` | | Override API URL. If not set, uses `ALPHAHUMAN_BASE_URL` from env (e.g. `.env`) or default `https://staging-api.alphahuman.xyz` |
+
+### `client.ingest_memory(request)`
+
+Upserts memory items. Items are deduplicated by `(namespace, key)`.
+
+Returns `IngestMemoryResponse(ingested, updated, errors)`.
+
+### `client.read_memory(request?)`
+
+Read memory items, optionally filtered by `key`, `keys`, or `namespace`.
+
+Returns `ReadMemoryResponse(items, count)`.
+
+### `client.delete_memory(request)`
+
+Delete memory by `key`, `keys`, or `delete_all=True`, optionally scoped by `namespace`.
+
+Returns `DeleteMemoryResponse(deleted)`.
+
+## Error handling
+
+```python
+from tinyhumansai import TinyHumanError
+
+try:
+    client.read_memory()
+except TinyHumanError as e:
+    print(e.status, str(e))
+```
+
+`TinyHumanError` carries `.status` (HTTP status code) and `.body` (parsed
+response or raw text for non-JSON responses such as gateway errors).

tinyhumansai-0.1.0/README.md

@@ -0,0 +1,119 @@
+# tinyhuman
+
+Python SDK for the [TinyHumans API](https://tinyhumans.ai).
+
+## Requirements
+
+- Python ≥ 3.9
+- `httpx >= 0.25`
+
+## Install
+
+```bash
+pip install tinyhuman
+```
+
+## Quick start (synchronous)
+
+```python
+from tinyhumansai import (
+    TinyHumanMemoryClient,
+    TinyHumanConfig,
+    IngestMemoryRequest,
+    ReadMemoryRequest,
+    DeleteMemoryRequest,
+    MemoryItem,
+)
+
+client = TinyHumanMemoryClient(TinyHumanConfig(token="your-api-key"))
+
+# Ingest (upsert) memory
+result = client.ingest_memory(
+    IngestMemoryRequest(
+        items=[
+            MemoryItem(
+                key="user-preference-theme",
+                content="User prefers dark mode",
+                namespace="preferences",
+                metadata={"source": "onboarding"},
+            )
+        ]
+    )
+)
+print(result)  # IngestMemoryResponse(ingested=1, updated=0, errors=0)
+
+# Read memory
+items = client.read_memory(ReadMemoryRequest(namespace="preferences"))
+print(items.count, items.items)
+
+# Delete by key
+client.delete_memory(DeleteMemoryRequest(key="user-preference-theme", namespace="preferences"))
+
+# Delete all user memory
+client.delete_memory(DeleteMemoryRequest(delete_all=True))
+```
+
+The client implements the context-manager protocol for deterministic cleanup:
+
+```python
+with TinyHumanMemoryClient(TinyHumanConfig(token="your-api-key")) as client:
+    result = client.read_memory()
+```
+
+## Async usage
+
+Use `AsyncTinyHumanMemoryClient` inside `async` code to avoid blocking the
+event loop (e.g. FastAPI, LangGraph async pipelines):
+
+```python
+import asyncio
+from tinyhumansai import AsyncTinyHumanMemoryClient, TinyHumanConfig, ReadMemoryRequest
+
+async def main():
+    async with AsyncTinyHumanMemoryClient(TinyHumanConfig(token="your-api-key")) as client:
+        result = await client.read_memory()
+        print(result.items)
+
+asyncio.run(main())
+```
+
+## API reference
+
+### `TinyHumanMemoryClient(config)` / `AsyncTinyHumanMemoryClient(config)`
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `config.token` | `str` | ✓ | JWT or API key |
+| `config.base_url` | `str` | | Override API URL. If not set, uses `ALPHAHUMAN_BASE_URL` from env (e.g. `.env`) or default `https://staging-api.alphahuman.xyz` |
+
+### `client.ingest_memory(request)`
+
+Upserts memory items. Items are deduplicated by `(namespace, key)`.
+
+Returns `IngestMemoryResponse(ingested, updated, errors)`.
+
+### `client.read_memory(request?)`
+
+Read memory items, optionally filtered by `key`, `keys`, or `namespace`.
+
+Returns `ReadMemoryResponse(items, count)`.
+
+### `client.delete_memory(request)`
+
+Delete memory by `key`, `keys`, or `delete_all=True`, optionally scoped by `namespace`.
+
+Returns `DeleteMemoryResponse(deleted)`.
+
+## Error handling
+
+```python
+from tinyhumansai import TinyHumanError
+
+try:
+    client.read_memory()
+except TinyHumanError as e:
+    print(e.status, str(e))
+```
+
+`TinyHumanError` carries `.status` (HTTP status code) and `.body` (parsed
+response or raw text for non-JSON responses such as gateway errors).

tinyhumansai-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tinyhumansai"
+version = "0.1.0"
+description = "Python SDK for TinyHumans API - ingest and delete memory"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.25"]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "mypy", "ruff"]
+
+[project.scripts]
+run-act-publish = "scripts.run_act_publish:main"
+
+[tool.setuptools.packages.find]
+include = ["tinyhumansai*", "scripts*"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+src = ["tinyhumansai", "alphahuman_memory", "scripts"]

tinyhumansai-0.1.0/scripts/__init__.py

@@ -0,0 +1 @@
+# Dev script entry points (run-act-publish, etc.)

tinyhumansai-0.1.0/scripts/run_act_publish.py

@@ -0,0 +1,49 @@
+"""Run act to test .github/workflows/publish.yml locally with secrets from .act-secrets."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def _repo_root() -> Path:
+    root = Path(__file__).resolve().parent.parent
+    if not (root / ".github" / "workflows").exists():
+        raise SystemExit("run_act_publish: must run from repo root (has .github/workflows)")
+    return root
+
+
+def main() -> None:
+    root = _repo_root()
+    secrets_file = root / ".act-secrets"
+    if not secrets_file.exists():
+        print("Missing .act-secrets. Copy act-secrets.example to .act-secrets and add PYPI_API_TOKEN.", file=sys.stderr)
+        sys.exit(1)
+
+    tag = os.environ.get("ACT_TAG", "v0.1.0")
+    event = {"ref": f"refs/tags/{tag}"}
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+        json.dump(event, f)
+        event_path = f.name
+
+    try:
+        workflow = root / ".github" / "workflows" / "publish.yml"
+        cmd = [
+            "act",
+            "push",
+            "-W", str(workflow),
+            "--secret-file", str(secrets_file),
+            "-e", event_path,
+        ]
+        sys.exit(subprocess.run(cmd, cwd=root).returncode)
+    finally:
+        os.unlink(event_path, dir_fd=None)
+
+
+if __name__ == "__main__":
+    main()

tinyhumansai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tinyhumansai-0.1.0/tinyhumansai/__init__.py

@@ -0,0 +1,36 @@
+"""TinyHumans Python SDK."""
+
+from .async_client import AsyncTinyHumanMemoryClient, AsyncAlphahumanMemoryClient
+from .client import TinyHumanMemoryClient, AlphahumanMemoryClient
+from .types import (
+    TinyHumanConfig,
+    TinyHumanError,
+    DeleteMemoryRequest,
+    DeleteMemoryResponse,
+    IngestMemoryRequest,
+    IngestMemoryResponse,
+    MemoryItem,
+    ReadMemoryItem,
+    ReadMemoryRequest,
+    ReadMemoryResponse,
+)
+
+__all__ = [
+    # Preferred TinyHuman names
+    "TinyHumanMemoryClient",
+    "AsyncTinyHumanMemoryClient",
+    "TinyHumanConfig",
+    "TinyHumanError",
+    # Backwards-compatible Alphahuman names
+    "AlphahumanMemoryClient",
+    "AsyncAlphahumanMemoryClient",
+    # Shared types
+    "DeleteMemoryRequest",
+    "DeleteMemoryResponse",
+    "IngestMemoryRequest",
+    "IngestMemoryResponse",
+    "MemoryItem",
+    "ReadMemoryItem",
+    "ReadMemoryRequest",
+    "ReadMemoryResponse",
+]

tinyhumansai-0.1.0/tinyhumansai/async_client.py

@@ -0,0 +1,197 @@
+"""Async TinyHumans memory client for Python."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+import httpx
+
+from .types import (
+    TinyHumanConfig,
+    TinyHumanError,
+    BASE_URL_ENV,
+    DEFAULT_BASE_URL,
+    DeleteMemoryRequest,
+    DeleteMemoryResponse,
+    IngestMemoryRequest,
+    IngestMemoryResponse,
+    ReadMemoryItem,
+    ReadMemoryRequest,
+    ReadMemoryResponse,
+)
+
+
+class AsyncTinyHumanMemoryClient:
+    """Async client for the TinyHumans memory API.
+
+    Prefer this in async runtimes (e.g. FastAPI, LangGraph async pipelines)
+    to avoid blocking the event loop.
+
+    Args:
+        config: Connection configuration (token required, base_url optional).
+
+    Example::
+
+        async with AsyncTinyHumanMemoryClient(TinyHumanConfig(token="...")) as client:
+            result = await client.ingest_memory(IngestMemoryRequest(items=[...]))
+    """
+
+    def __init__(self, config: TinyHumanConfig) -> None:
+        if not config.token or not config.token.strip():
+            raise ValueError("token is required")
+        base_url = config.base_url or os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL
+        self._base_url = base_url.rstrip("/")
+        self._token = config.token
+        self._http = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {self._token}"},
+            timeout=30,
+        )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client and release connections."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncAlphahumanMemoryClient":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+    async def ingest_memory(self, request: IngestMemoryRequest) -> IngestMemoryResponse:
+        """Ingest (upsert) one or more memory items asynchronously.
+
+        Args:
+            request: The ingestion request containing items to upsert.
+
+        Returns:
+            Counts of ingested, updated, and errored items.
+
+        Raises:
+            ValueError: If items list is empty.
+            TinyHumanError: On API errors.
+        """
+        if not request.items:
+            raise ValueError("items must be a non-empty list")
+
+        body = {
+            "items": [
+                {
+                    "key": item.key,
+                    "content": item.content,
+                    "namespace": item.namespace,
+                    "metadata": item.metadata,
+                }
+                for item in request.items
+            ]
+        }
+        data = await self._send("POST", "/v1/memory", body)
+        return IngestMemoryResponse(
+            ingested=data["ingested"],
+            updated=data["updated"],
+            errors=data["errors"],
+        )
+
+    async def read_memory(
+        self, request: Optional[ReadMemoryRequest] = None
+    ) -> ReadMemoryResponse:
+        """Read memory items by key, keys, or namespace asynchronously.
+
+        Returns all user memory if no filters are provided.
+
+        Args:
+            request: Optional filters for the read.
+
+        Returns:
+            List of matching memory items and count.
+
+        Raises:
+            TinyHumanError: On API errors.
+        """
+        params: list[tuple[str, str]] = []
+        if request:
+            if request.key:
+                params.append(("key", request.key))
+            if request.keys:
+                for k in request.keys:
+                    params.append(("keys[]", k))
+            if request.namespace:
+                params.append(("namespace", request.namespace))
+
+        data = await self._get("/v1/memory", params)
+        items = [
+            ReadMemoryItem(
+                key=item["key"],
+                content=item["content"],
+                namespace=item["namespace"],
+                metadata=item.get("metadata", {}),
+                created_at=item.get("createdAt", ""),
+                updated_at=item.get("updatedAt", ""),
+            )
+            for item in data["items"]
+        ]
+        return ReadMemoryResponse(items=items, count=data["count"])
+
+    async def delete_memory(self, request: DeleteMemoryRequest) -> DeleteMemoryResponse:
+        """Delete memory items by key, keys, or delete all asynchronously.
+
+        Args:
+            request: The deletion request specifying what to delete.
+
+        Returns:
+            Count of deleted items.
+
+        Raises:
+            ValueError: If no deletion target is specified.
+            TinyHumanError: On API errors.
+        """
+        has_key = isinstance(request.key, str) and len(request.key) > 0
+        has_keys = isinstance(request.keys, list) and len(request.keys) > 0
+        if not has_key and not has_keys and not request.delete_all:
+            raise ValueError('Provide "key", "keys", or set delete_all=True')
+
+        body: dict[str, Any] = {}
+        if request.key is not None:
+            body["key"] = request.key
+        if request.keys is not None:
+            body["keys"] = request.keys
+        if request.namespace is not None:
+            body["namespace"] = request.namespace
+        if request.delete_all:
+            body["deleteAll"] = True
+
+        data = await self._send("DELETE", "/v1/memory", body)
+        return DeleteMemoryResponse(deleted=data["deleted"])
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _get(self, path: str, params: list[tuple[str, str]]) -> dict[str, Any]:
+        response = await self._http.get(path, params=params)
+        return self._parse_response(response)
+
+    async def _send(
+        self, method: str, path: str, body: dict[str, Any]
+    ) -> dict[str, Any]:
+        response = await self._http.request(method, path, json=body)
+        return self._parse_response(response)
+
+    def _parse_response(self, response: httpx.Response) -> dict[str, Any]:
+        try:
+            payload = response.json()
+        except Exception:
+            raise TinyHumanError(
+                f"HTTP {response.status_code}: non-JSON response",
+                response.status_code,
+                response.text,
+            )
+        if not response.is_success:
+            message = payload.get("error", f"HTTP {response.status_code}")
+            raise TinyHumanError(message, response.status_code, payload)
+        return payload["data"]
+
+
+# Backwards-compatible alias
+AsyncAlphahumanMemoryClient = AsyncTinyHumanMemoryClient

tinyhumansai-0.1.0/tinyhumansai/client.py

@@ -0,0 +1,191 @@
+"""TinyHumans memory client for Python."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+import httpx
+
+from .types import (
+    TinyHumanConfig,
+    TinyHumanError,
+    BASE_URL_ENV,
+    DEFAULT_BASE_URL,
+    DeleteMemoryRequest,
+    DeleteMemoryResponse,
+    IngestMemoryRequest,
+    IngestMemoryResponse,
+    ReadMemoryItem,
+    ReadMemoryRequest,
+    ReadMemoryResponse,
+)
+
+
+class TinyHumanMemoryClient:
+    """Synchronous client for the TinyHumans memory API.
+
+    Args:
+        config: Connection configuration (token required, base_url optional).
+    """
+
+    def __init__(self, config: TinyHumanConfig) -> None:
+        if not config.token or not config.token.strip():
+            raise ValueError("token is required")
+        base_url = config.base_url or os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL
+        self._base_url = base_url.rstrip("/")
+        self._token = config.token
+        self._http = httpx.Client(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {self._token}"},
+            timeout=30,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release connections."""
+        self._http.close()
+
+    def __enter__(self) -> "AlphahumanMemoryClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def ingest_memory(self, request: IngestMemoryRequest) -> IngestMemoryResponse:
+        """Ingest (upsert) one or more memory items.
+
+        Items are deduped by (namespace, key). If a matching item already
+        exists its content and metadata are updated; otherwise a new item
+        is created.
+
+        Args:
+            request: The ingestion request containing items to upsert.
+
+        Returns:
+            Counts of ingested, updated, and errored items.
+
+        Raises:
+            ValueError: If items list is empty.
+            TinyHumanError: On API errors.
+        """
+        if not request.items:
+            raise ValueError("items must be a non-empty list")
+
+        body = {
+            "items": [
+                {
+                    "key": item.key,
+                    "content": item.content,
+                    "namespace": item.namespace,
+                    "metadata": item.metadata,
+                }
+                for item in request.items
+            ]
+        }
+        data = self._send("POST", "/v1/memory", body)
+        return IngestMemoryResponse(
+            ingested=data["ingested"],
+            updated=data["updated"],
+            errors=data["errors"],
+        )
+
+    def read_memory(
+        self, request: Optional[ReadMemoryRequest] = None
+    ) -> ReadMemoryResponse:
+        """Read memory items by key, keys, or namespace.
+
+        Returns all user memory if no filters are provided.
+
+        Args:
+            request: Optional filters for the read.
+
+        Returns:
+            List of matching memory items and count.
+
+        Raises:
+            TinyHumanError: On API errors.
+        """
+        params: list[tuple[str, str]] = []
+        if request:
+            if request.key:
+                params.append(("key", request.key))
+            if request.keys:
+                for k in request.keys:
+                    params.append(("keys[]", k))
+            if request.namespace:
+                params.append(("namespace", request.namespace))
+
+        data = self._get("/v1/memory", params)
+        items = [
+            ReadMemoryItem(
+                key=item["key"],
+                content=item["content"],
+                namespace=item["namespace"],
+                metadata=item.get("metadata", {}),
+                created_at=item.get("createdAt", ""),
+                updated_at=item.get("updatedAt", ""),
+            )
+            for item in data["items"]
+        ]
+        return ReadMemoryResponse(items=items, count=data["count"])
+
+    def delete_memory(self, request: DeleteMemoryRequest) -> DeleteMemoryResponse:
+        """Delete memory items by key, keys, or delete all.
+
+        Args:
+            request: The deletion request specifying what to delete.
+
+        Returns:
+            Count of deleted items.
+
+        Raises:
+            ValueError: If no deletion target is specified.
+            TinyHumanError: On API errors.
+        """
+        has_key = isinstance(request.key, str) and len(request.key) > 0
+        has_keys = isinstance(request.keys, list) and len(request.keys) > 0
+        if not has_key and not has_keys and not request.delete_all:
+            raise ValueError('Provide "key", "keys", or set delete_all=True')
+
+        body: dict[str, Any] = {}
+        if request.key is not None:
+            body["key"] = request.key
+        if request.keys is not None:
+            body["keys"] = request.keys
+        if request.namespace is not None:
+            body["namespace"] = request.namespace
+        if request.delete_all:
+            body["deleteAll"] = True
+
+        data = self._send("DELETE", "/v1/memory", body)
+        return DeleteMemoryResponse(deleted=data["deleted"])
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get(self, path: str, params: list[tuple[str, str]]) -> dict[str, Any]:
+        response = self._http.get(path, params=params)
+        return self._parse_response(response)
+
+    def _send(self, method: str, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        response = self._http.request(method, path, json=body)
+        return self._parse_response(response)
+
+    def _parse_response(self, response: httpx.Response) -> dict[str, Any]:
+        try:
+            payload = response.json()
+        except Exception:
+            raise TinyHumanError(
+                f"HTTP {response.status_code}: non-JSON response",
+                response.status_code,
+                response.text,
+            )
+        if not response.is_success:
+            message = payload.get("error", f"HTTP {response.status_code}")
+            raise TinyHumanError(message, response.status_code, payload)
+        return payload["data"]
+
+
+# Backwards-compatible alias
+AlphahumanMemoryClient = TinyHumanMemoryClient

tinyhumansai-0.1.0/tinyhumansai/types.py

@@ -0,0 +1,123 @@
+"""Type definitions for the TinyHumans Python SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+DEFAULT_BASE_URL = "https://staging-api.alphahuman.xyz"
+
+# Environment variable for base URL override (e.g. from .env)
+BASE_URL_ENV = "ALPHAHUMAN_BASE_URL"
+
+
+@dataclass
+class TinyHumanConfig:
+    """Configuration for the TinyHumans client."""
+
+    token: str
+    """Bearer token (JWT or API key) for authentication."""
+
+    base_url: Optional[str] = None
+    """Base URL of the backend. If None, uses ALPHAHUMAN_BASE_URL env var or default staging URL."""
+
+
+@dataclass
+class MemoryItem:
+    """A single memory item to ingest."""
+
+    key: str
+    """Unique key within the namespace (used for upsert / dedup)."""
+
+    content: str
+    """Memory content text."""
+
+    namespace: str = "default"
+    """Namespace to scope this item."""
+
+    metadata: dict[str, Any] = field(default_factory=dict)
+    """Arbitrary metadata."""
+
+
+@dataclass
+class IngestMemoryRequest:
+    """Request payload for memory ingestion."""
+
+    items: list[MemoryItem]
+
+
+@dataclass
+class IngestMemoryResponse:
+    """Response from memory ingestion."""
+
+    ingested: int
+    updated: int
+    errors: int
+
+
+@dataclass
+class ReadMemoryRequest:
+    """Request payload for memory read."""
+
+    key: Optional[str] = None
+    """Single key to read."""
+
+    keys: Optional[list[str]] = None
+    """Array of keys to read."""
+
+    namespace: Optional[str] = None
+    """Namespace scope."""
+
+
+@dataclass
+class ReadMemoryItem:
+    """A single memory item returned from a read."""
+
+    key: str
+    content: str
+    namespace: str
+    metadata: dict[str, Any]
+    created_at: str
+    updated_at: str
+
+
+@dataclass
+class ReadMemoryResponse:
+    """Response from memory read."""
+
+    items: list[ReadMemoryItem]
+    count: int
+
+
+@dataclass
+class DeleteMemoryRequest:
+    """Request payload for memory deletion."""
+
+    key: Optional[str] = None
+    """Single key to delete."""
+
+    keys: Optional[list[str]] = None
+    """Array of keys to delete."""
+
+    namespace: Optional[str] = None
+    """Namespace scope (default: 'default')."""
+
+    delete_all: bool = False
+    """Delete all memory for the user (optionally scoped by namespace)."""
+
+
+@dataclass
+class DeleteMemoryResponse:
+    """Response from memory deletion."""
+
+    deleted: int
+
+
+class TinyHumanError(Exception):
+    """Error raised by the TinyHumans API."""
+
+    def __init__(self, message: str, status: int, body: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body

tinyhumansai-0.1.0/tinyhumansai.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: tinyhumansai
+Version: 0.1.0
+Summary: Python SDK for TinyHumans API - ingest and delete memory
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# tinyhuman
+
+Python SDK for the [TinyHumans API](https://tinyhumans.ai).
+
+## Requirements
+
+- Python ≥ 3.9
+- `httpx >= 0.25`
+
+## Install
+
+```bash
+pip install tinyhuman
+```
+
+## Quick start (synchronous)
+
+```python
+from tinyhumansai import (
+    TinyHumanMemoryClient,
+    TinyHumanConfig,
+    IngestMemoryRequest,
+    ReadMemoryRequest,
+    DeleteMemoryRequest,
+    MemoryItem,
+)
+
+client = TinyHumanMemoryClient(TinyHumanConfig(token="your-api-key"))
+
+# Ingest (upsert) memory
+result = client.ingest_memory(
+    IngestMemoryRequest(
+        items=[
+            MemoryItem(
+                key="user-preference-theme",
+                content="User prefers dark mode",
+                namespace="preferences",
+                metadata={"source": "onboarding"},
+            )
+        ]
+    )
+)
+print(result)  # IngestMemoryResponse(ingested=1, updated=0, errors=0)
+
+# Read memory
+items = client.read_memory(ReadMemoryRequest(namespace="preferences"))
+print(items.count, items.items)
+
+# Delete by key
+client.delete_memory(DeleteMemoryRequest(key="user-preference-theme", namespace="preferences"))
+
+# Delete all user memory
+client.delete_memory(DeleteMemoryRequest(delete_all=True))
+```
+
+The client implements the context-manager protocol for deterministic cleanup:
+
+```python
+with TinyHumanMemoryClient(TinyHumanConfig(token="your-api-key")) as client:
+    result = client.read_memory()
+```
+
+## Async usage
+
+Use `AsyncTinyHumanMemoryClient` inside `async` code to avoid blocking the
+event loop (e.g. FastAPI, LangGraph async pipelines):
+
+```python
+import asyncio
+from tinyhumansai import AsyncTinyHumanMemoryClient, TinyHumanConfig, ReadMemoryRequest
+
+async def main():
+    async with AsyncTinyHumanMemoryClient(TinyHumanConfig(token="your-api-key")) as client:
+        result = await client.read_memory()
+        print(result.items)
+
+asyncio.run(main())
+```
+
+## API reference
+
+### `TinyHumanMemoryClient(config)` / `AsyncTinyHumanMemoryClient(config)`
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `config.token` | `str` | ✓ | JWT or API key |
+| `config.base_url` | `str` | | Override API URL. If not set, uses `ALPHAHUMAN_BASE_URL` from env (e.g. `.env`) or default `https://staging-api.alphahuman.xyz` |
+
+### `client.ingest_memory(request)`
+
+Upserts memory items. Items are deduplicated by `(namespace, key)`.
+
+Returns `IngestMemoryResponse(ingested, updated, errors)`.
+
+### `client.read_memory(request?)`
+
+Read memory items, optionally filtered by `key`, `keys`, or `namespace`.
+
+Returns `ReadMemoryResponse(items, count)`.
+
+### `client.delete_memory(request)`
+
+Delete memory by `key`, `keys`, or `delete_all=True`, optionally scoped by `namespace`.
+
+Returns `DeleteMemoryResponse(deleted)`.
+
+## Error handling
+
+```python
+from tinyhumansai import TinyHumanError
+
+try:
+    client.read_memory()
+except TinyHumanError as e:
+    print(e.status, str(e))
+```
+
+`TinyHumanError` carries `.status` (HTTP status code) and `.body` (parsed
+response or raw text for non-JSON responses such as gateway errors).

tinyhumansai-0.1.0/tinyhumansai.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+scripts/__init__.py
+scripts/run_act_publish.py
+tinyhumansai/__init__.py
+tinyhumansai/async_client.py
+tinyhumansai/client.py
+tinyhumansai/types.py
+tinyhumansai.egg-info/PKG-INFO
+tinyhumansai.egg-info/SOURCES.txt
+tinyhumansai.egg-info/dependency_links.txt
+tinyhumansai.egg-info/entry_points.txt
+tinyhumansai.egg-info/requires.txt
+tinyhumansai.egg-info/top_level.txt

tinyhumansai-0.1.0/tinyhumansai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tinyhumansai-0.1.0/tinyhumansai.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+run-act-publish = scripts.run_act_publish:main

tinyhumansai-0.1.0/tinyhumansai.egg-info/requires.txt

@@ -0,0 +1,7 @@
+httpx>=0.25
+
+[dev]
+pytest
+pytest-asyncio
+mypy
+ruff

tinyhumansai-0.1.0/tinyhumansai.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+scripts
+tinyhumansai