loremem 0.1.0__py3-none-any.whl

loremem/__init__.py

@@ -0,0 +1,33 @@
+"""
+loremem — The Python SDK for Lore Organizational Memory.
+
+Quick start:
+    from loremem import LoreClient
+
+    client = LoreClient(
+        api_key="sk-lore-xxxx",
+        workspace_id="ws_yourworkspace",
+    )
+
+    # Before your LLM call
+    ctx = client.get_context(query="Draft MSA for Acme Corp", tool="contract-agent")
+    system_prompt = ctx.formatted_injection + base_system_prompt
+
+    # After a human corrects the AI output
+    client.report_correction(
+        ai_output_id="output_001",
+        summary="Changed jurisdiction from UK to US",
+        tool="contract-agent",
+    )
+"""
+
+from loremem.client import AsyncLoreClient, LoreClient
+from loremem.models import ContextResponse, ReportResult
+
+__version__ = "0.1.0"
+__all__ = [
+    "LoreClient",
+    "AsyncLoreClient",
+    "ContextResponse",
+    "ReportResult",
+]

loremem/_http.py

@@ -0,0 +1,227 @@
+"""
+loremem HTTP transport layer.
+
+Handles:
+  - Bearer auth header injection
+  - Retry with exponential backoff (3 attempts)
+  - Timeout enforcement (5s context, 10s writes)
+  - Error classification into loremem exceptions
+  - Async variant (AsyncTransport) for async callers
+
+httpx is used for both sync and async. It is the only required dependency.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from loremem.exceptions import (
+    AuthError,
+    LoreMemError,
+    NetworkError,
+    RateLimitError,
+    ServerError,
+)
+
+logger = logging.getLogger("loremem")
+
+_MAX_RETRIES = 3
+_BACKOFF_BASE = 0.5   # seconds — 0.5, 1.0, 2.0
+_CONTEXT_TIMEOUT = 5.0   # seconds — context must be fast
+_WRITE_TIMEOUT = 10.0    # seconds — reporting calls are less time-sensitive
+
+
+def _classify(response: httpx.Response) -> None:
+    """Raise the appropriate exception for a non-2xx response."""
+    status = response.status_code
+    try:
+        detail = response.json().get("detail", response.text)
+    except Exception:
+        detail = response.text or str(status)
+
+    if status == 401:
+        raise AuthError(f"Authentication failed: {detail}")
+    if status == 403:
+        raise AuthError(f"Forbidden — workspace mismatch: {detail}")
+    if status == 429:
+        raise RateLimitError(f"Rate limit exceeded: {detail}")
+    if status >= 500:
+        raise ServerError(f"Lore API error {status}: {detail}")
+    raise LoreMemError(f"Unexpected response {status}: {detail}")
+
+
+def _should_retry(exc: Exception) -> bool:
+    """Only retry on network errors and 5xx; not on 4xx."""
+    return isinstance(exc, (NetworkError, ServerError, httpx.TransportError))
+
+
+# ── Sync transport ────────────────────────────────────────────────────────────
+
+
+class Transport:
+    """Synchronous HTTP transport with retry + backoff."""
+
+    def __init__(self, base_url: str, api_key: str) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "loremem-python/0.1.0",
+        }
+
+    def post(
+        self,
+        path: str,
+        payload: dict[str, Any],
+        timeout: float = _WRITE_TIMEOUT,
+    ) -> dict[str, Any]:
+        """POST with retry. Returns parsed JSON body."""
+        url = f"{self._base_url}{path}"
+        last_exc: Exception = LoreMemError("Unknown error")
+
+        for attempt in range(_MAX_RETRIES):
+            try:
+                response = httpx.post(
+                    url,
+                    json=payload,
+                    headers=self._headers,
+                    timeout=timeout,
+                )
+                if response.is_success:
+                    return response.json()
+                _classify(response)
+
+            except (AuthError, RateLimitError, LoreMemError):
+                raise   # non-retryable
+            except httpx.TimeoutException as exc:
+                last_exc = NetworkError(f"Request timed out: {exc}")
+            except httpx.TransportError as exc:
+                last_exc = NetworkError(f"Network error: {exc}")
+            except ServerError as exc:
+                last_exc = exc
+
+            if attempt < _MAX_RETRIES - 1:
+                time.sleep(_BACKOFF_BASE * (2 ** attempt))
+
+        raise last_exc
+
+    def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        timeout: float = _WRITE_TIMEOUT,
+    ) -> dict[str, Any]:
+        """GET with retry. Returns parsed JSON body."""
+        url = f"{self._base_url}{path}"
+        last_exc: Exception = LoreMemError("Unknown error")
+
+        for attempt in range(_MAX_RETRIES):
+            try:
+                response = httpx.get(
+                    url,
+                    params=params,
+                    headers=self._headers,
+                    timeout=timeout,
+                )
+                if response.is_success:
+                    return response.json()
+                _classify(response)
+
+            except (AuthError, RateLimitError, LoreMemError):
+                raise
+            except httpx.TimeoutException as exc:
+                last_exc = NetworkError(f"Request timed out: {exc}")
+            except httpx.TransportError as exc:
+                last_exc = NetworkError(f"Network error: {exc}")
+            except ServerError as exc:
+                last_exc = exc
+
+            if attempt < _MAX_RETRIES - 1:
+                time.sleep(_BACKOFF_BASE * (2 ** attempt))
+
+        raise last_exc
+
+
+# ── Async transport ───────────────────────────────────────────────────────────
+
+
+class AsyncTransport:
+    """Async HTTP transport with retry + backoff. Use with async AI agent frameworks."""
+
+    def __init__(self, base_url: str, api_key: str) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "loremem-python/0.1.0",
+        }
+
+    async def post(
+        self,
+        path: str,
+        payload: dict[str, Any],
+        timeout: float = _WRITE_TIMEOUT,
+    ) -> dict[str, Any]:
+        import asyncio
+
+        url = f"{self._base_url}{path}"
+        last_exc: Exception = LoreMemError("Unknown error")
+
+        async with httpx.AsyncClient(headers=self._headers, timeout=timeout) as client:
+            for attempt in range(_MAX_RETRIES):
+                try:
+                    response = await client.post(url, json=payload)
+                    if response.is_success:
+                        return response.json()
+                    _classify(response)
+
+                except (AuthError, RateLimitError, LoreMemError):
+                    raise
+                except httpx.TimeoutException as exc:
+                    last_exc = NetworkError(f"Request timed out: {exc}")
+                except httpx.TransportError as exc:
+                    last_exc = NetworkError(f"Network error: {exc}")
+                except ServerError as exc:
+                    last_exc = exc
+
+                if attempt < _MAX_RETRIES - 1:
+                    await asyncio.sleep(_BACKOFF_BASE * (2 ** attempt))
+
+        raise last_exc
+
+    async def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        timeout: float = _WRITE_TIMEOUT,
+    ) -> dict[str, Any]:
+        import asyncio
+
+        url = f"{self._base_url}{path}"
+        last_exc: Exception = LoreMemError("Unknown error")
+
+        async with httpx.AsyncClient(headers=self._headers, timeout=timeout) as client:
+            for attempt in range(_MAX_RETRIES):
+                try:
+                    response = await client.get(url, params=params)
+                    if response.is_success:
+                        return response.json()
+                    _classify(response)
+
+                except (AuthError, RateLimitError, LoreMemError):
+                    raise
+                except httpx.TimeoutException as exc:
+                    last_exc = NetworkError(f"Request timed out: {exc}")
+                except httpx.TransportError as exc:
+                    last_exc = NetworkError(f"Network error: {exc}")
+                except ServerError as exc:
+                    last_exc = exc
+
+                if attempt < _MAX_RETRIES - 1:
+                    await asyncio.sleep(_BACKOFF_BASE * (2 ** attempt))
+
+        raise last_exc

loremem/client.py

@@ -0,0 +1,442 @@
+"""
+LoreClient — sync and async clients for the Lore context injection API.
+
+Sync usage (most AI agents):
+    from loremem import LoreClient
+
+    client = LoreClient(
+        api_key="sk-lore-xxxx",
+        workspace_id="ws_yourworkspace",
+    )
+
+    # Before every LLM call
+    context = client.get_context(
+        query="Draft an MSA for Acme Corp",
+        tool="contract-drafting-agent",
+    )
+    # context.formatted_injection → prepend to system prompt
+
+Async usage (async agent frameworks — LangChain, CrewAI, etc.):
+    from loremem import AsyncLoreClient
+
+    client = AsyncLoreClient(api_key="sk-lore-xxxx", workspace_id="ws_acme")
+    context = await client.get_context(query="...", tool="...")
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from loremem._http import AsyncTransport, Transport, _CONTEXT_TIMEOUT
+from loremem.exceptions import LoreMemError
+from loremem.models import ContextResponse, ReportResult
+
+logger = logging.getLogger("loremem")
+
+_DEFAULT_BASE_URL = "https://lore-m0st.onrender.com"
+
+
+# ── Sync client ───────────────────────────────────────────────────────────────
+
+
+class LoreClient:
+    """
+    Synchronous Lore client.
+
+    Parameters
+    ----------
+    api_key:
+        Your Lore API key (starts with ``sk-lore-``). Get one from
+        ``POST /v1/auth/api-keys`` or the Lore dashboard.
+    workspace_id:
+        The workspace this client operates within.
+    base_url:
+        Override the API base URL (default: production Render service).
+        Set to ``http://localhost:8000`` during local development.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        workspace_id: str,
+        base_url: str = _DEFAULT_BASE_URL,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must not be empty.")
+        if not workspace_id:
+            raise ValueError("workspace_id must not be empty.")
+
+        self._workspace_id = workspace_id
+        self._http = Transport(base_url=base_url, api_key=api_key)
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def get_context(
+        self,
+        query: str,
+        tool: str,
+        hints: dict[str, Any] | None = None,
+        entities: list[str] | None = None,
+        max_rules: int = 10,
+        max_tokens: int = 2000,
+    ) -> ContextResponse:
+        """
+        Retrieve relevant organizational context for an AI task.
+
+        Call this **before** your LLM call and prepend
+        ``response.formatted_injection`` to your system prompt.
+
+        This method **never raises**. On any error it returns an empty
+        ``ContextResponse`` and logs a warning so your agent continues normally.
+
+        Parameters
+        ----------
+        query:
+            Natural language description of the task the agent is about to perform.
+            E.g. ``"Draft an MSA for Acme Corp"``.
+        tool:
+            Identifier for the AI tool making the request. Use a consistent slug
+            per agent — e.g. ``"contract-drafting-agent"``. Rules are scoped to tool.
+        hints:
+            Optional dict of additional context tags passed to the graph query.
+            E.g. ``{"jurisdiction": "US", "customer_tier": "enterprise"}``.
+        entities:
+            Optional list of entity names to fetch specific profiles for.
+            E.g. ``["Acme Corp"]``.
+        max_rules:
+            Maximum number of rules to include in the injection block.
+        max_tokens:
+            Approximate token budget for the formatted injection string.
+
+        Returns
+        -------
+        ContextResponse
+            Always returns a valid object. ``formatted_injection`` is an empty
+            string when no context was found or on error.
+
+        Example
+        -------
+        ::
+
+            ctx = client.get_context(
+                query="Draft an MSA for Acme Corp",
+                tool="contract-agent",
+                hints={"jurisdiction": "US"},
+                entities=["Acme Corp"],
+            )
+            system_prompt = ctx.formatted_injection + "\\n\\n" + base_system_prompt
+        """
+        try:
+            payload: dict[str, Any] = {
+                "tool": tool,
+                "task": query,
+                "context_tags": hints or {},
+                "entities": entities or [],
+                "max_rules": max_rules,
+                "max_tokens": max_tokens,
+            }
+            data = self._http.post(
+                f"/v1/context?workspace_id={self._workspace_id}",
+                payload=payload,
+                timeout=_CONTEXT_TIMEOUT,
+            )
+            return ContextResponse(
+                context_id=data.get("context_id", ""),
+                formatted_injection=data.get("formatted_injection", ""),
+                rules=data.get("rules", []),
+                entities=data.get("entities", []),
+                decisions=data.get("decisions", []),
+                cached=data.get("cached", False),
+            )
+        except LoreMemError as exc:
+            logger.warning("loremem.get_context failed — returning empty context: %s", exc)
+            return ContextResponse.empty()
+        except Exception as exc:
+            logger.warning("loremem.get_context unexpected error — returning empty context: %s", exc)
+            return ContextResponse.empty()
+
+    def report_correction(
+        self,
+        ai_output_id: str,
+        summary: str,
+        tool: str,
+        context_tags: dict[str, Any] | None = None,
+        actor_id: str | None = None,
+    ) -> ReportResult:
+        """
+        Report a human correction of an AI output.
+
+        Call this whenever a human edits, overrides, or rejects an AI-generated
+        output. Lore learns from these corrections over time.
+
+        This method **never raises**. Errors are logged as warnings.
+
+        Parameters
+        ----------
+        ai_output_id:
+            ID you assigned to the AI output that was corrected. Used for
+            deduplication and linking back to the original output.
+        summary:
+            Human-readable description of what changed.
+            E.g. ``"Changed jurisdiction clause from UK to US standard"``.
+        tool:
+            The tool that generated the original output. Same slug as in
+            ``get_context()``.
+        context_tags:
+            Optional additional metadata about the correction context.
+            E.g. ``{"customer": "Acme Corp", "document_type": "MSA"}``.
+        actor_id:
+            ID of the human who made the correction (email or user ID).
+            Helps pattern mining distinguish corrections by different people.
+
+        Returns
+        -------
+        ReportResult
+            Always returns. ``accepted=True`` means the event was queued.
+
+        Example
+        -------
+        ::
+
+            client.report_correction(
+                ai_output_id="draft_acme_msa_v1",
+                summary="Changed indemnity clause to US_STANDARD template",
+                tool="contract-agent",
+                context_tags={"customer": "Acme Corp"},
+                actor_id="james@company.com",
+            )
+        """
+        try:
+            payload: dict[str, Any] = {
+                "workspace_id": self._workspace_id,
+                "tool": tool,
+                "event_type": "correction",
+                "ai_output_id": ai_output_id,
+                "actor_id": actor_id or "sdk_reporter",
+                "context_tags": context_tags or {},
+                "delta": [
+                    {
+                        "field": "output",
+                        "change_type": "correction",
+                        "change_summary": summary,
+                    }
+                ],
+                "confidence_signal": 0.9,
+            }
+            data = self._http.post(
+                f"/v1/events?workspace_id={self._workspace_id}",
+                payload=payload,
+            )
+            return ReportResult(
+                accepted=True,
+                event_id=data.get("event_id", ""),
+            )
+        except LoreMemError as exc:
+            logger.warning("loremem.report_correction failed (event dropped): %s", exc)
+            return ReportResult(accepted=False)
+        except Exception as exc:
+            logger.warning("loremem.report_correction unexpected error (event dropped): %s", exc)
+            return ReportResult(accepted=False)
+
+    def report_output(
+        self,
+        output_id: str,
+        tool: str,
+        summary: str = "",
+        context_tags: dict[str, Any] | None = None,
+        actor_id: str | None = None,
+    ) -> ReportResult:
+        """
+        Report an AI output that was approved without modification (positive signal).
+
+        Use this when a human reviews an AI output and accepts it without changes.
+        This reinforces the rules that contributed to the good output.
+
+        This method **never raises**.
+
+        Parameters
+        ----------
+        output_id:
+            Unique ID for this AI output — the same ID you'd pass to
+            ``report_correction()`` if the output were later corrected.
+        tool:
+            The tool that generated this output.
+        summary:
+            Optional description of what was generated. E.g. ``"MSA draft approved"``.
+        context_tags:
+            Optional metadata about the output context.
+        actor_id:
+            ID of the human who approved the output.
+
+        Returns
+        -------
+        ReportResult
+        """
+        try:
+            payload: dict[str, Any] = {
+                "workspace_id": self._workspace_id,
+                "tool": tool,
+                "event_type": "approval",
+                "ai_output_id": output_id,
+                "actor_id": actor_id or "sdk_reporter",
+                "context_tags": context_tags or {},
+                "delta": [
+                    {
+                        "field": "output",
+                        "change_type": "approval",
+                        "change_summary": summary or "Output approved without modification",
+                    }
+                ],
+                "confidence_signal": 1.0,
+            }
+            data = self._http.post(
+                f"/v1/events?workspace_id={self._workspace_id}",
+                payload=payload,
+            )
+            return ReportResult(
+                accepted=True,
+                event_id=data.get("event_id", ""),
+            )
+        except LoreMemError as exc:
+            logger.warning("loremem.report_output failed (event dropped): %s", exc)
+            return ReportResult(accepted=False)
+        except Exception as exc:
+            logger.warning("loremem.report_output unexpected error (event dropped): %s", exc)
+            return ReportResult(accepted=False)
+
+
+# ── Async client ──────────────────────────────────────────────────────────────
+
+
+class AsyncLoreClient:
+    """
+    Async variant of LoreClient. Same interface, all methods are coroutines.
+
+    Use with async agent frameworks (LangChain, CrewAI, FastAPI-based agents, etc.).
+
+    ::
+
+        client = AsyncLoreClient(api_key="sk-lore-xxx", workspace_id="ws_acme")
+        ctx = await client.get_context(query="...", tool="...")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        workspace_id: str,
+        base_url: str = _DEFAULT_BASE_URL,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must not be empty.")
+        if not workspace_id:
+            raise ValueError("workspace_id must not be empty.")
+
+        self._workspace_id = workspace_id
+        self._http = AsyncTransport(base_url=base_url, api_key=api_key)
+
+    async def get_context(
+        self,
+        query: str,
+        tool: str,
+        hints: dict[str, Any] | None = None,
+        entities: list[str] | None = None,
+        max_rules: int = 10,
+        max_tokens: int = 2000,
+    ) -> ContextResponse:
+        """Async version of LoreClient.get_context(). Never raises."""
+        try:
+            payload: dict[str, Any] = {
+                "tool": tool,
+                "task": query,
+                "context_tags": hints or {},
+                "entities": entities or [],
+                "max_rules": max_rules,
+                "max_tokens": max_tokens,
+            }
+            data = await self._http.post(
+                f"/v1/context?workspace_id={self._workspace_id}",
+                payload=payload,
+                timeout=_CONTEXT_TIMEOUT,
+            )
+            return ContextResponse(
+                context_id=data.get("context_id", ""),
+                formatted_injection=data.get("formatted_injection", ""),
+                rules=data.get("rules", []),
+                entities=data.get("entities", []),
+                decisions=data.get("decisions", []),
+                cached=data.get("cached", False),
+            )
+        except Exception as exc:
+            logger.warning("loremem.get_context failed — returning empty context: %s", exc)
+            return ContextResponse.empty()
+
+    async def report_correction(
+        self,
+        ai_output_id: str,
+        summary: str,
+        tool: str,
+        context_tags: dict[str, Any] | None = None,
+        actor_id: str | None = None,
+    ) -> ReportResult:
+        """Async version of LoreClient.report_correction(). Never raises."""
+        try:
+            payload: dict[str, Any] = {
+                "workspace_id": self._workspace_id,
+                "tool": tool,
+                "event_type": "correction",
+                "ai_output_id": ai_output_id,
+                "actor_id": actor_id or "sdk_reporter",
+                "context_tags": context_tags or {},
+                "delta": [
+                    {
+                        "field": "output",
+                        "change_type": "correction",
+                        "change_summary": summary,
+                    }
+                ],
+                "confidence_signal": 0.9,
+            }
+            data = await self._http.post(
+                f"/v1/events?workspace_id={self._workspace_id}",
+                payload=payload,
+            )
+            return ReportResult(accepted=True, event_id=data.get("event_id", ""))
+        except Exception as exc:
+            logger.warning("loremem.report_correction failed (event dropped): %s", exc)
+            return ReportResult(accepted=False)
+
+    async def report_output(
+        self,
+        output_id: str,
+        tool: str,
+        summary: str = "",
+        context_tags: dict[str, Any] | None = None,
+        actor_id: str | None = None,
+    ) -> ReportResult:
+        """Async version of LoreClient.report_output(). Never raises."""
+        try:
+            payload: dict[str, Any] = {
+                "workspace_id": self._workspace_id,
+                "tool": tool,
+                "event_type": "approval",
+                "ai_output_id": output_id,
+                "actor_id": actor_id or "sdk_reporter",
+                "context_tags": context_tags or {},
+                "delta": [
+                    {
+                        "field": "output",
+                        "change_type": "approval",
+                        "change_summary": summary or "Output approved without modification",
+                    }
+                ],
+                "confidence_signal": 1.0,
+            }
+            data = await self._http.post(
+                f"/v1/events?workspace_id={self._workspace_id}",
+                payload=payload,
+            )
+            return ReportResult(accepted=True, event_id=data.get("event_id", ""))
+        except Exception as exc:
+            logger.warning("loremem.report_output failed (event dropped): %s", exc)
+            return ReportResult(accepted=False)

loremem/exceptions.py

@@ -0,0 +1,30 @@
+"""
+loremem exceptions.
+
+These are INTERNAL — never surfaced to SDK callers.
+All public methods catch every exception, log a warning, and return a safe default.
+"""
+
+
+class LoreMemError(Exception):
+    """Base exception for all loremem SDK errors."""
+
+
+class AuthError(LoreMemError):
+    """API key rejected or workspace not found."""
+
+
+class NetworkError(LoreMemError):
+    """Could not reach the Lore API."""
+
+
+class TimeoutError(LoreMemError):
+    """Request timed out."""
+
+
+class RateLimitError(LoreMemError):
+    """Workspace rate limit exceeded."""
+
+
+class ServerError(LoreMemError):
+    """Lore API returned a 5xx response."""

loremem/models.py

@@ -0,0 +1,68 @@
+"""
+loremem data models.
+
+Lightweight dataclasses — no Pydantic dependency in the SDK.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ContextResponse:
+    """
+    Returned by LoreClient.get_context().
+
+    In practice you mostly use `formatted_injection` — prepend it to your LLM
+    system prompt. The other fields are available for logging / debugging.
+    """
+
+    context_id: str
+    """Unique ID for this context response — include in your audit trail."""
+
+    formatted_injection: str
+    """
+    Ready-to-use string to prepend to your LLM system prompt.
+    Empty string when no relevant context exists or if the request failed.
+    """
+
+    rules: list[dict[str, Any]] = field(default_factory=list)
+    """Active rules that matched this request."""
+
+    entities: list[dict[str, Any]] = field(default_factory=list)
+    """Entity profiles that matched this request."""
+
+    decisions: list[dict[str, Any]] = field(default_factory=list)
+    """Decision records that matched this request."""
+
+    cached: bool = False
+    """True if this response was served from cache (no graph query was run)."""
+
+    @classmethod
+    def empty(cls) -> "ContextResponse":
+        """Safe empty response — returned on any error."""
+        return cls(
+            context_id="",
+            formatted_injection="",
+            rules=[],
+            entities=[],
+            decisions=[],
+            cached=False,
+        )
+
+    def __bool__(self) -> bool:
+        """True if the response contains any usable context."""
+        return bool(self.formatted_injection)
+
+
+@dataclass
+class ReportResult:
+    """Returned by report_correction / report_output. Always succeeds (errors swallowed)."""
+
+    accepted: bool
+    """True if the API accepted the report."""
+
+    event_id: str = ""
+    """Event ID assigned by Lore, if accepted."""

loremem-0.1.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: loremem
+Version: 0.1.0
+Summary: Lore SDK — inject organizational memory into any AI agent
+Project-URL: Homepage, https://github.com/mr-shakib/lore
+Project-URL: Documentation, https://github.com/mr-shakib/lore/tree/main/sdk/python
+Project-URL: Repository, https://github.com/mr-shakib/lore
+Project-URL: Issues, https://github.com/mr-shakib/lore/issues
+License: MIT
+Keywords: agents,ai,context,llm,lore,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# loremem — Python SDK for Lore
+
+> Inject your company's organizational memory into any AI agent in 3 lines of code.
+
+**Lore** captures every human correction of an AI output, structures it into a company knowledge graph, and feeds it back to your AI agents so they stop making the same mistakes twice.
+
+`loremem` is the Python SDK for accessing Lore's Context Injection API.
+
+---
+
+## Installation
+
+```bash
+# From PyPI (when published)
+pip install loremem
+
+# From GitHub (MVP — no PyPI publish required)
+pip install git+https://github.com/mr-shakib/lore#subdirectory=sdk/python
+```
+
+---
+
+## Quickstart (3 minutes)
+
+```python
+from loremem import LoreClient
+
+client = LoreClient(
+    api_key="sk-lore-xxxx",          # from POST /v1/auth/api-keys
+    workspace_id="ws_yourworkspace",  # your Lore workspace ID
+)
+
+# ── Step 1: Get context before your LLM call ──────────────────────────────────
+
+ctx = client.get_context(
+    query="Draft an MSA for Acme Corp",
+    tool="contract-drafting-agent",
+    hints={"jurisdiction": "US", "customer_tier": "enterprise"},
+    entities=["Acme Corp"],
+)
+
+# Prepend to your system prompt
+system_prompt = ctx.formatted_injection + "\n\n" + YOUR_BASE_SYSTEM_PROMPT
+response = openai_client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "system", "content": system_prompt}, ...],
+)
+
+# ── Step 2: Report corrections so Lore learns ─────────────────────────────────
+
+# When a human edits the AI output:
+client.report_correction(
+    ai_output_id="draft_acme_msa_v1",
+    summary="Changed indemnity clause from UK to US_STANDARD template",
+    tool="contract-drafting-agent",
+    context_tags={"customer": "Acme Corp", "document_type": "MSA"},
+    actor_id="james@company.com",
+)
+
+# When a human approves the AI output without changes (positive signal):
+client.report_output(
+    output_id="draft_acme_msa_v2",
+    tool="contract-drafting-agent",
+    summary="MSA draft approved — no changes needed",
+    actor_id="james@company.com",
+)
+```
+
+After a few corrections, Lore automatically proposes rules like:
+> *"US clients require the US_STANDARD indemnity template"*
+
+Confirm the rule once → it's injected into every future AI call automatically.
+
+---
+
+## Async usage
+
+For async agent frameworks (LangChain, CrewAI, FastAPI-based agents):
+
+```python
+from loremem import AsyncLoreClient
+
+client = AsyncLoreClient(api_key="sk-lore-xxxx", workspace_id="ws_acme")
+
+ctx = await client.get_context(
+    query="Route this support ticket",
+    tool="support-triage-agent",
+)
+
+await client.report_correction(
+    ai_output_id="ticket_001",
+    summary="Re-routed from Tier 1 to Enterprise team",
+    tool="support-triage-agent",
+)
+```
+
+---
+
+## Never-throw guarantee
+
+Every method in `LoreClient` and `AsyncLoreClient` is designed to **never raise exceptions**. If Lore is unavailable, misconfigured, or rate-limited:
+
+- `get_context()` returns an empty `ContextResponse` (`.formatted_injection == ""`)
+- `report_correction()` and `report_output()` return `ReportResult(accepted=False)`
+- A `WARNING` is logged via Python's standard `logging` module
+
+**Lore's unavailability will never cause your AI agent to break.**
+
+```python
+import logging
+logging.getLogger("loremem").setLevel(logging.WARNING)  # optional: see SDK warnings
+```
+
+---
+
+## API reference
+
+### `LoreClient(api_key, workspace_id, base_url?)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `api_key` | `str` | Lore API key (`sk-lore-...`) |
+| `workspace_id` | `str` | Your workspace ID |
+| `base_url` | `str` | Default: production Lore API. Set to `http://localhost:8000` for local dev |
+
+### `get_context(query, tool, hints?, entities?, max_rules?, max_tokens?)`
+
+Returns a `ContextResponse`:
+
+| Field | Type | Description |
+|---|---|---|
+| `formatted_injection` | `str` | Ready-to-use string — prepend to system prompt |
+| `context_id` | `str` | Unique ID for this context response |
+| `rules` | `list[dict]` | Active rules that matched |
+| `entities` | `list[dict]` | Entity profiles that matched |
+| `decisions` | `list[dict]` | Decision records that matched |
+| `cached` | `bool` | True if served from 15-min cache |
+
+### `report_correction(ai_output_id, summary, tool, context_tags?, actor_id?)`
+
+Call when a human edits or overrides an AI output.
+
+### `report_output(output_id, tool, summary?, context_tags?, actor_id?)`
+
+Call when a human approves an AI output unchanged (positive signal).
+
+---
+
+## Getting an API key
+
+```bash
+# Create a key (requires Clerk JWT from the dashboard, or bootstrap via Supabase directly)
+curl -X POST https://lore-m0st.onrender.com/v1/auth/api-keys \
+  -H "Authorization: Bearer <clerk_jwt>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Production SDK key"}'
+```
+
+---
+
+## Local development
+
+```python
+client = LoreClient(
+    api_key="sk-lore-xxxx",
+    workspace_id="ws_test",
+    base_url="http://localhost:8000",  # local FastAPI server
+)
+```
+
+---
+
+## License
+
+MIT

loremem-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+loremem/__init__.py,sha256=ieBpPGsoEQTz4FmRpNIWU2Kh7iGcu00xLT5KHuiBV94,866
+loremem/_http.py,sha256=79P1hsUw7OT9_c-HR_oez4ifiLHbR09Y5UfinolZuFs,7952
+loremem/client.py,sha256=EacsYArYaY2d_LJwhuXA3pxZiAzKJte6zwThDIKirHs,16537
+loremem/exceptions.py,sha256=FPtco-CbeCpMaNveWOH55yjpo2p5VZqlpvfO6V7B6Yc,666
+loremem/models.py,sha256=JPVzYn-alj6Gg7KV_vGn1vYrBTBog3WeiWxHtwmKY-M,1976
+loremem-0.1.0.dist-info/METADATA,sha256=7zk8P2OAa5rVoju0ONAZKNKqxFbmOLjVrKug10N7vm4,6234
+loremem-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+loremem-0.1.0.dist-info/RECORD,,

loremem-0.1.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