memoryintelligence 0.1.0__py3-none-any.whl

memoryintelligence/_simple.py

@@ -0,0 +1,301 @@
+"""The flat client: eight verbs, on the canonical public endpoints.
+
+    from memoryintelligence import MemoryIntelligence
+
+    mi = MemoryIntelligence.from_env()                 # reads MI_API_KEY
+    note = mi.capture("Sarah proposed provenance hashing for the deck.")
+
+    for hit in mi.ask("what did sarah suggest?"):
+        print(f"{hit.score:.2f}  {hit.summary}")
+
+    if mi.verify(note.id):                              # every memory has a receipt
+        print("intact")
+
+This is the surface most people want: capture, ask, get, list, verify, explain,
+forget, batch, upload. It maps one-to-one onto the canonical `/v1/*` endpoints
+(the ones the public OpenAPI and operationIds describe) and hides the wire
+format so results come back as small typed objects, not envelopes.
+
+It is built on the same transport and error family as `MemoryClient`, so it
+shares connection pooling, retries, and `except MIError` behavior. `MemoryClient`
+(the `mi.umo.*` namespace, multi-tenant `user_ulid`, edge and crypto features)
+stays available for advanced and regulated use.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable
+
+from ._auth import (
+    resolve_api_key,
+    resolve_base_url,
+    validate_key_environment,
+    validate_key_format,
+)
+from ._errors import MIError
+from ._http import SyncTransport
+
+__all__ = ["MemoryIntelligence", "MI", "Memory", "Match", "Proof", "Explanation", "Receipt"]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Result types. Small, typed, readable. Each keeps a `.raw` escape hatch and
+# supports item access, so you are never boxed in by our field choices:
+# `note.id` when it is clean, `note["quality_score"]` when you need something we
+# did not surface.
+# ─────────────────────────────────────────────────────────────────────────────
+
+class _Record:
+    raw: dict
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.raw.get(key, default)
+
+
+@dataclass(frozen=True)
+class Memory(_Record):
+    """A stored memory (a Unified Memory Object). `id` is what you pass back to
+    verify, explain, and forget."""
+    id: str
+    quality_score: float | None = None
+    summary: str | None = None
+    channel: str | None = None
+    created_at: str | None = None
+    raw: dict = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def _wrap(cls, d: dict) -> "Memory":
+        return cls(
+            id=d.get("umo_id") or d.get("id"),
+            quality_score=d.get("quality_score"),
+            summary=d.get("summary"),
+            channel=d.get("channel"),
+            created_at=d.get("created_at"),
+            raw=d,
+        )
+
+    @property
+    def entities(self) -> list[dict]:
+        return self.raw.get("entities", [])
+
+
+@dataclass(frozen=True)
+class Match(_Record):
+    """One search result: a `memory` plus its relevance `score` (0 to 1)."""
+    score: float
+    memory: Memory
+    raw: dict = field(default_factory=dict, repr=False)
+
+    @property
+    def id(self) -> str:
+        return self.memory.id
+
+    @property
+    def summary(self) -> str | None:
+        return self.memory.summary
+
+    @property
+    def entities(self) -> list[dict]:
+        return self.memory.entities
+
+
+@dataclass(frozen=True)
+class Proof(_Record):
+    """The receipt for a memory. Truthy when intact: `if mi.verify(id): ...`"""
+    valid: bool
+    hash_chain_valid: bool | None = None
+    mode: str | None = None            # cryptographic | legacy | incomplete
+    tampered: bool | None = None
+    raw: dict = field(default_factory=dict, repr=False)
+
+    def __bool__(self) -> bool:
+        return bool(self.valid)
+
+    @classmethod
+    def _wrap(cls, d: dict) -> "Proof":
+        audit = d.get("audit_proof") or {}
+        return cls(
+            valid=bool(d.get("valid")),
+            hash_chain_valid=d.get("hash_chain_valid"),
+            mode=audit.get("verification_mode"),
+            tampered=audit.get("chain_tampered"),
+            raw=d,
+        )
+
+
+@dataclass(frozen=True)
+class Explanation(_Record):
+    """What the pipeline extracted from a memory and why it matched."""
+    id: str
+    raw: dict = field(default_factory=dict, repr=False)
+
+
+@dataclass(frozen=True)
+class Receipt(_Record):
+    """Confirmation that a memory was deleted, with its deletion record.
+    Truthy when the delete took effect."""
+    id: str
+    deleted: bool
+    raw: dict = field(default_factory=dict, repr=False)
+
+    def __bool__(self) -> bool:
+        return bool(self.deleted)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# The client.
+# ─────────────────────────────────────────────────────────────────────────────
+
+class MemoryIntelligence:
+    """A connection to Memory Intelligence.
+
+        mi = MemoryIntelligence("mi_sk_...")
+        mi = MemoryIntelligence.from_env()      # reads MI_API_KEY
+
+    Reuse one instance across your app. It is a thin, synchronous wrapper over a
+    pooled connection, cheap to hold and safe to share within a thread. Close it
+    when you are done, or use it as a context manager.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ):
+        self._api_key = resolve_api_key(api_key)
+        self._base_url = resolve_base_url(base_url)
+        validate_key_format(self._api_key)
+        validate_key_environment(self._api_key, self._base_url)
+        self._transport = SyncTransport(
+            api_key=self._api_key,
+            base_url=self._base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> "MemoryIntelligence":
+        """Build a client from MI_API_KEY (and optional MI_BASE_URL)."""
+        return cls(None, **kwargs)
+
+    # ── the eight verbs ──────────────────────────────────────────────────────
+
+    def capture(self, content: str, *, source: str | None = None, **metadata: Any) -> Memory:
+        """Turn raw content into a structured, verifiable memory.
+
+            note = mi.capture("Deploy is Friday at 3pm.", source="standup")
+
+        Keep `note.id`: it is how you verify, explain, and forget this later.
+        """
+        body: dict[str, Any] = {"content": content}
+        if source:
+            body["source"] = source
+        if metadata:
+            body["metadata"] = metadata
+        return Memory._wrap(self._data(self._transport.request("POST", "/v1/process", json=body)))
+
+    def ask(self, query: str, *, limit: int = 5, **filters: Any) -> list[Match]:
+        """Find memories by meaning, not keywords.
+
+            for hit in mi.ask("what did we decide about pricing?", limit=3):
+                print(hit.score, hit.summary)
+
+        Filters (source, topics, entities, date_from, date_to) pass through.
+        Returns matches already sorted by relevance.
+        """
+        body = {"query": query, "limit": limit, **filters}
+        payload = self._transport.request("POST", "/v1/memories/query", json=body)
+        container = payload.get("data", payload)          # tolerate either envelope
+        return [
+            Match(score=r.get("score"), memory=Memory._wrap(r.get("umo", {})), raw=r)
+            for r in container.get("results", [])
+        ]
+
+    def get(self, id: str) -> Memory:
+        """Retrieve one memory by id."""
+        return Memory._wrap(self._data(self._transport.request("GET", f"/v1/memories/{id}")))
+
+    def list(self, *, limit: int | None = None) -> list[Memory]:
+        """List the memories this key can see, newest first."""
+        params = {"limit": limit} if limit is not None else None
+        payload = self._transport.request("GET", "/v1/memories", params=params)
+        container = payload.get("data", payload)
+        rows = container.get("memories") or container.get("results") or container
+        return [Memory._wrap(r) for r in rows] if isinstance(rows, list) else []
+
+    def verify(self, id: str) -> Proof:
+        """Prove a memory is real and unaltered. The result is truthy when
+        intact, so `assert mi.verify(id)` reads naturally."""
+        return Proof._wrap(self._data(self._transport.request("GET", f"/v1/memories/{id}/proof")))
+
+    def explain(self, id: str) -> Explanation:
+        """See what the pipeline extracted from a memory and why it matched."""
+        d = self._data(self._transport.request("GET", f"/v1/memories/{id}/explain"))
+        return Explanation(id=id, raw=d)
+
+    def forget(self, id: str) -> Receipt:
+        """Delete a memory and get a deletion receipt. Soft delete with a grace
+        window: recoverable until the window closes."""
+        d = self._data(self._transport.request("DELETE", f"/v1/memories/{id}"))
+        return Receipt(id=id, deleted=d.get("deleted", True), raw=d)
+
+    def batch(self, items: Iterable[str | dict]) -> list[Memory]:
+        """Capture many memories in one round trip.
+
+            mi.batch(["first note", "second note"])
+            mi.batch([{"content": "with a source", "source": "import"}])
+        """
+        payload = [
+            {"content": it} if isinstance(it, str) else dict(it)
+            for it in items
+        ]
+        result = self._transport.request("POST", "/v1/batch", json={"items": payload})
+        container = result.get("data", result)
+        rows = container.get("results") or container.get("items") or []
+        return [Memory._wrap(r.get("umo", r)) for r in rows]
+
+    def upload(self, path: str | Path) -> Memory:
+        """Capture a media file (audio, video, image, PDF). MI extracts the
+        content and structures it the same way capture() does."""
+        p = Path(path)
+        with p.open("rb") as fh:
+            result = self._transport.request("POST", "/v1/upload", files={"file": (p.name, fh)})
+        return Memory._wrap(self._data(result))
+
+    def health(self) -> bool:
+        """True when the API is reachable and serving."""
+        try:
+            self._transport.request("GET", "/health")
+            return True
+        except MIError:
+            return False
+
+    # ── internals ────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _data(payload: dict) -> dict:
+        """Unwrap the {status, data} envelope so the caller always gets the
+        useful object, never the wrapper. Bare bodies pass through."""
+        if isinstance(payload, dict) and isinstance(payload.get("data"), dict):
+            return payload["data"]
+        return payload
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "MemoryIntelligence":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+# A terse alias for those who want it: `from memoryintelligence import MI`.
+MI = MemoryIntelligence

memoryintelligence/_version.py

@@ -0,0 +1,3 @@
+"""Memory Intelligence SDK version."""
+
+__version__ = "0.1.0"

memoryintelligence/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561
+# This package provides type hints

memoryintelligence-0.1.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: memoryintelligence
+Version: 0.1.0
+Summary: Official Python SDK for Memory Intelligence. Structured, verifiable memory for AI.
+Author-email: Memory Intelligence Team <sdk@memoryintelligence.io>
+License: MIT
+Project-URL: Homepage, https://memoryintelligence.io
+Project-URL: Documentation, https://docs.memoryintelligence.io
+Project-URL: Repository, https://github.com/somewhere11/memoryintelligence-python-sdk
+Project-URL: Changelog, https://github.com/somewhere11/memoryintelligence-python-sdk/blob/main/CHANGELOG.md
+Keywords: ai,llm,memory,rag,embeddings,privacy,compliance,hipaa,gdpr,provenance,umo
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-ulid>=2.0.0
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0.0; extra == "dotenv"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# Memory Intelligence API
+
+**Memory without meaning is just storage.**
+
+This API turns raw content (text, conversations, images) into structured meaning. Searchable, explainable, provenance-tracked. No black box. No hallucinations.
+
+**For Python backends:** FastAPI, Django, Flask, Lambda, Cloud Functions.
+
+---
+
+## Installation
+
+```bash
+pip install memoryintelligence
+```
+
+**Get your API key:** [memoryintelligence.io/beta](https://memoryintelligence.io/beta)
+
+---
+
+## Quick Start
+
+```python
+from memoryintelligence import MemoryIntelligence
+
+mi = MemoryIntelligence.from_env()          # reads MI_API_KEY
+
+# Turn content into a structured, verifiable memory
+note = mi.capture(
+    "Discussed pricing with ACME. They prefer quarterly billing.",
+    source="sales_call",
+)
+
+# Ask by meaning, not keywords
+for hit in mi.ask("what did ACME say about billing?"):
+    print(f"{hit.score:.2f}  {hit.summary}")
+
+# Every memory has a receipt
+if mi.verify(note.id):
+    print("intact")
+```
+
+> **Upgrading from `MemoryClient`?** The flat `MemoryIntelligence` client above is
+> the recommended surface. The older `MemoryClient` (the `mi.umo.*` namespace, with
+> multi-tenant `user_ulid`) still works for advanced use, and `EdgeClient` still
+> serves regulated on-premise deployments, but `MemoryClient` is deprecated and will
+> be removed in a future major. See [Core Operations](#core-operations) for the full
+> eight-verb surface.
+
+---
+
+## What It Does
+
+- **Processes** → Extracts entities, topics, relationships, sentiment
+- **Searches** → Returns ranked results with explainability
+- **Matches** → Compares memories for relevance/similarity
+- **Explains** → Shows *why* results matched (semantic, temporal, graph)
+- **Deletes** → GDPR-compliant data removal with audit trail
+
+**No vector database setup. No chunking strategies. No embedding models to manage.**
+
+---
+
+## Security: API Keys Are Server-Only
+
+Your API key grants full account access. Keep it server-side.
+
+**✅ Backend (environment variable):**
+```python
+mi = MemoryIntelligence.from_env()   # reads MI_API_KEY
+```
+
+**❌ Never hardcoded:**
+```python
+# Don't - visible in logs/code
+mi = MemoryIntelligence(api_key='mi_sk_live_...')
+```
+
+**For web apps:** Use your API key in the backend, build your own endpoints with your auth, let your frontend call those.
+
+---
+
+## What Makes This Different
+
+| Others | Memory Intelligence |
+|--------|---------------------|
+| Store text, embed, hope | Extract meaning first |
+| "Here are similar chunks" | "Here's why this matched" |
+| No audit trail | Cryptographic provenance |
+| Your data = their model training | We never train on your data |
+
+**Setting the standard for memory.**
+
+---
+
+## Core Operations
+
+Eight verbs, mapped one-to-one onto the public API:
+
+```python
+note    = mi.capture(content, source="notes")   # POST   /v1/process
+hits    = mi.ask(query, limit=5)                 # POST   /v1/memories/query
+note    = mi.get(umo_id)                          # GET    /v1/memories/{id}
+notes   = mi.list(limit=20)                       # GET    /v1/memories
+proof   = mi.verify(umo_id)                        # GET    /v1/memories/{id}/proof
+why     = mi.explain(umo_id)                        # GET    /v1/memories/{id}/explain
+receipt = mi.forget(umo_id)                        # DELETE /v1/memories/{id}
+notes   = mi.batch(["note one", "note two"])       # POST   /v1/batch
+note    = mi.upload("meeting.mp3")                 # POST   /v1/upload
+```
+
+Results come back as small typed objects (`Memory`, `Match`, `Proof`, `Receipt`),
+each with a `.raw` escape hatch and item access, so `note.id` when it is clean and
+`note["quality_score"]` when you need a field we did not surface.
+
+---
+
+## Async Support
+
+An async twin of the flat client (`AsyncMemoryIntelligence`) is on the roadmap.
+Until then, the async surface is the older `AsyncMemoryClient` (the `mi.umo.*`
+namespace, deprecated alongside `MemoryClient`):
+
+```python
+from memoryintelligence import AsyncMemoryClient
+
+async with AsyncMemoryClient.from_env() as mi:
+    results = await mi.umo.search(query, user_ulid="01ABC...")
+```
+
+---
+
+## Error Handling
+
+```python
+from memoryintelligence import (
+    MIError, AuthenticationError, NotFoundError, RateLimitError, ValidationError,
+)
+
+try:
+    hits = mi.ask(query)
+except AuthenticationError:
+    ...                       # API key invalid or expired
+except NotFoundError:
+    ...                       # no memory with that id
+except RateLimitError:
+    ...                       # the client already retried with backoff
+except ValidationError as e:
+    ...                       # request shape was wrong
+except MIError as e:
+    print(e.status, e)        # any API error carries its status
+```
+
+---
+
+## Typed Everywhere
+
+Full Pydantic models. Type hints on every method. No `dict` soup.
+
+```python
+from memoryintelligence import Memory, Match, Proof
+```
+
+---
+
+## Examples & Docs
+
+- **[Getting Started Guide](https://github.com/memoryintelligence/memoryintelligence-python-sdk/tree/main/docs/GETTING-STARTED.md)** — Full walkthrough
+- **[FastAPI Integration](https://github.com/memoryintelligence/memoryintelligence-python-sdk/tree/main/examples/fastapi_app.py)** — Complete example
+- **[Advanced Usage](https://github.com/memoryintelligence/memoryintelligence-python-sdk/tree/main/docs/ADVANCED.md)** — Batch processing, retry logic, custom configs
+
+---
+
+## Support
+
+- **Docs:** [memoryintelligence.io/docs](https://memoryintelligence.io/docs)
+- **Issues:** [github.com/memoryintelligence/memoryintelligence-python-sdk/issues](https://github.com/memoryintelligence/memoryintelligence-python-sdk/issues)
+- **Beta:** [memoryintelligence.io/beta](https://memoryintelligence.io/beta)
+
+---
+
+**Memory Intelligence™** — Setting the standard for memory.
+
+Built by [somewhere](https://somewheremedia.com)

memoryintelligence-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+memoryintelligence/__init__.py,sha256=wUVGDGp02yRrbb7U5BeZhaucW0hwCjc1Q_NHtrmeBfI,1579
+memoryintelligence/_auth.py,sha256=zvgI2Fo5WjxiAckP9lRIYYitqzJhOAPL6wspo881Nuo,8664
+memoryintelligence/_errors.py,sha256=-GxVqZkc7FdU8s_GKfB7mc8kmCOVPHTEIPTpKpqcxMM,6168
+memoryintelligence/_http.py,sha256=RhPTV024dRL1J_PxsvcJE0iA__N_EGhXmxohrjQFr8M,14462
+memoryintelligence/_simple.py,sha256=GAX-qYJH3TtFVcqbqC_bdP8vIrGGL9e549zRF3J42uo,11815
+memoryintelligence/_version.py,sha256=q5Y7I3-OKUvbx6WVmu60NV9BiRldLC0gNt5dRvt93x4,62
+memoryintelligence/py.typed,sha256=tipAbxnkxwswNZuJUzl8r0GLJZ8YN4aU5SieSXdwxkM,61
+memoryintelligence-0.1.0.dist-info/licenses/LICENSE,sha256=2mzz0DJdCoNdgUXVcDxIr1o1LMnNdkJEIQj7HSNnsrw,1537
+memoryintelligence-0.1.0.dist-info/METADATA,sha256=VEe92bBuGQT3AzJGC58nJNxGLwDSsrSUoBQj-rovvNs,7460
+memoryintelligence-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+memoryintelligence-0.1.0.dist-info/top_level.txt,sha256=jQxLND_7L23jp0FCpvuTv-Pf9qw64yMBkUsovU1WGpk,19
+memoryintelligence-0.1.0.dist-info/RECORD,,

memoryintelligence-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

memoryintelligence-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,31 @@
+MIT License with Attribution Requirement
+
+Copyright (c) 2026 Memory Intelligence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+2. Applications using this SDK MUST display "Powered by Memory Intelligence" 
+   attribution in their user interface or documentation.
+
+3. This SDK may only be used to interact with official Memory Intelligence API 
+   services. No reverse engineering of the API or unauthorized replication of 
+   the service is permitted.
+
+4. API access credentials (API keys) are non-transferable and may not be 
+   resold or sublicensed.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memoryintelligence-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+memoryintelligence