memcode-sdk 2.3.1__tar.gz

memcode_sdk-2.3.1/PKG-INFO

@@ -0,0 +1,387 @@
+Metadata-Version: 2.4
+Name: memcode-sdk
+Version: 2.3.1
+Summary: Python SDK for the Memcode long-term memory API
+Author: Memcode
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://memcode.in
+Project-URL: Repository, https://gitlab.com/xortex1/memcode-sdk
+Project-URL: Issues, https://gitlab.com/xortex1/memcode-sdk/-/issues
+Keywords: memory,long-term-memory,llm,rag,ai-agent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.24
+
+<h1 align="center">Memcode Client SDKs</h1>
+
+<p align="center">
+Official client libraries for the <strong>Memcode long-term memory API</strong>.<br>
+Available in Python, TypeScript, and Go.
+</p>
+
+All three SDKs share the same design principles:
+
+- Existing v1 clients keep three 1:1 methods: **ingest**, **retrieve**, **search**
+- Bearer-token authentication via constructor arg or `MEMCODE_API_KEY` env var
+- Typed error hierarchy so callers can handle auth, rate-limit, and server errors distinctly
+- Zero config defaults &mdash; point at `localhost:8000` with no key and it just works in dev
+
+The existing `MemcodeClient`/`Client` APIs remain v1-compatible and now expose an
+additive advanced personal v2 surface for authenticated personal callers:
+
+- Python: `ingest_v2`, `get_ingest_status_v2`, `search_v2`, `retrieve_v2`
+- TypeScript: `ingestV2`, `getIngestStatusV2`, `searchV2`, `retrieveV2`
+- Go: `IngestV2`, `GetIngestStatusV2`, `SearchV2`,
+  `SearchV2WithOptions`, `RetrieveV2`
+
+Personal v2 derives the user from the API key or JWT, so no `user_id` is needed.
+Ingestion returns a durable job receipt, retrieval includes
+attribution/connection-learning metadata, and personal v2 search uses the
+unified `/v2/memory/search` route.
+The deprecated `user_id` argument remains accepted and is sent only when supplied.
+The API may return `409` for personal v2 ingest when raw original storage is
+globally enabled; that backend safety gate remains unchanged.
+
+```python
+from memcode_sdk import MemcodeClient
+
+client = MemcodeClient(api_url="https://memory.example.com", api_key="sk-...")
+job = client.ingest_v2(
+    user_query="The launch is Friday",
+)
+status = client.get_ingest_status_v2(job.job_id)
+hits = client.search_v2(query="launch date")
+answer = client.retrieve_v2(query="When is launch?")
+```
+
+## Prerequisites
+
+A running Memcode API server:
+
+```bash
+uvicorn src.api.app:create_app --factory --host 0.0.0.0 --port 8000
+```
+
+## Python
+
+**Location:** `memcode_sdk/`
+
+### Install
+
+```bash
+pip install memcode-sdk
+```
+
+### Sync usage
+
+```python
+from memcode_sdk import MemcodeClient
+
+client = MemcodeClient(api_url="http://localhost:8000", api_key="sk-...")
+
+# Check health
+health = client.ping()
+print(health.status, health.pipelines_ready)
+
+# Ingest a conversation turn
+result = client.ingest(
+    user_query="I just got promoted to senior engineer at Google!",
+    agent_response="Congratulations on your promotion!",
+    user_id="user_42",
+)
+print(result.model, result.profile, result.temporal)
+
+# Retrieve an LLM-generated answer backed by memory
+answer = client.retrieve(query="What is my job title?", user_id="user_42")
+print(answer.answer)
+print(answer.sources)       # list of SourceRecord
+print(answer.confidence)
+
+# Raw semantic search (no LLM answer)
+hits = client.search(
+    query="work history",
+    user_id="user_42",
+    domains=["profile", "temporal"],
+    top_k=10,
+)
+for r in hits.results:
+    print(f"[{r.domain}] {r.content}  (score={r.score:.2f})")
+
+job = client.ingest_v2(
+    user_query="I now lead the platform team",
+    effort_level="high",
+)
+status = client.get_ingest_status_v2(job.job_id)
+hybrid = client.search_v2(
+    query="work history",
+    top_k=10,
+    original_top_k=5,
+)
+advanced_answer = client.retrieve_v2(
+    query="What team do I lead?",
+)
+
+client.close()
+```
+
+### Async usage
+
+```python
+from memcode_sdk import AsyncMemcodeClient
+
+async with AsyncMemcodeClient(api_url="http://localhost:8000") as client:
+    result = await client.ingest(
+        user_query="I love hiking in the Rockies.",
+        user_id="user_42",
+    )
+    answer = await client.retrieve(query="hobbies", user_id="user_42")
+    print(answer.answer)
+```
+
+### Error handling
+
+```python
+from memcode_sdk import MemcodeClient, AuthenticationError, RateLimitError, NotReadyError
+
+client = MemcodeClient(api_key="bad-key")
+
+try:
+    client.ingest(user_query="test", user_id="u1")
+except AuthenticationError as e:
+    print(f"Auth failed (HTTP {e.status_code}): {e.message}")
+except RateLimitError as e:
+    print(f"Throttled, retry after {e.retry_after}s")
+except NotReadyError:
+    print("Pipelines still loading, try again shortly")
+```
+
+### Configuration
+
+| Parameter | Env var | Default |
+|-----------|---------|---------|
+| `api_url` | `MEMCODE_API_URL` | `http://localhost:8000` |
+| `api_key` | `MEMCODE_API_KEY` | _(empty, no auth)_ |
+| `timeout` | &mdash; | `120` seconds |
+
+---
+
+## TypeScript
+
+**Location:** `memcode-ts/`
+**Package name:** `memcode-sdk`
+
+### Install
+
+```bash
+npm install memcode-sdk
+```
+
+### Usage
+
+```typescript
+import { MemcodeClient } from "memcode-sdk";
+
+const client = new MemcodeClient("http://localhost:8000", "sk-...");
+
+// Health
+const ready = await client.isReady();
+
+// Ingest
+const result = await client.ingest({
+  user_query: "I just adopted a golden retriever named Max!",
+  agent_response: "That's wonderful!",
+  user_id: "user_42",
+});
+
+// Retrieve
+const answer = await client.retrieve({
+  query: "Do I have any pets?",
+  user_id: "user_42",
+});
+console.log(answer.answer);
+
+// Search
+const hits = await client.search({
+  query: "pets",
+  user_id: "user_42",
+  domains: ["profile", "summary"],
+  top_k: 5,
+});
+hits.results.forEach((r) => console.log(`[${r.domain}] ${r.content}`));
+
+const job = await client.ingestV2({
+  user_query: "I now lead the platform team",
+  effort_level: "high",
+});
+const status = await client.getIngestStatusV2(job.job_id);
+const hybrid = await client.searchV2({
+  query: "pets",
+  top_k: 10,
+  original_top_k: 5,
+});
+const advancedAnswer = await client.retrieveV2({
+  query: "Do I have pets?",
+});
+```
+
+### Error handling
+
+```typescript
+import { MemcodeClient, AuthenticationError, RateLimitError } from "memcode-sdk";
+
+try {
+  await client.ingest({ user_query: "test", user_id: "u1" });
+} catch (e) {
+  if (e instanceof AuthenticationError) {
+    console.error(`Auth failed: ${e.message}`);
+  } else if (e instanceof RateLimitError) {
+    console.error(`Rate limited, retry after ${e.retryAfter}s`);
+  }
+}
+```
+
+---
+
+## Go
+
+**Location:** `memcode-go/`
+**Module:** `gitlab.com/xortex1/memcode-sdk/memcode-go/v2`
+
+### Install
+
+```bash
+go get gitlab.com/xortex1/memcode-sdk/memcode-go/v2
+```
+
+### Usage
+
+```go
+package main
+
+import (
+    "fmt"
+    memcode "gitlab.com/xortex1/memcode-sdk/memcode-go/v2"
+)
+
+func main() {
+    client := memcode.NewClient("http://localhost:8000", "sk-...")
+
+    // Health
+    if client.IsReady() {
+        fmt.Println("Memcode API is ready")
+    }
+
+    // Ingest
+    result, err := client.Ingest(memcode.IngestParams{
+        UserQuery:     "I'm moving to Seattle next month.",
+        AgentResponse: "Good luck with your move!",
+        UserID:        "user_42",
+    })
+    if err != nil {
+        panic(err)
+    }
+    fmt.Println("Model:", result.Model)
+
+    // Retrieve
+    answer, err := client.Retrieve(memcode.RetrieveParams{
+        Query:  "Where am I moving?",
+        UserID: "user_42",
+    })
+    if err != nil {
+        panic(err)
+    }
+    fmt.Println("Answer:", answer.Answer)
+
+    // Search
+    hits, err := client.Search(memcode.SearchParams{
+        Query:   "location",
+        UserID:  "user_42",
+        Domains: []string{"profile", "temporal"},
+        TopK:    10,
+    })
+    if err != nil {
+        panic(err)
+    }
+    for _, r := range hits.Results {
+        fmt.Printf("[%s] %s (%.2f)\n", r.Domain, r.Content, r.Score)
+    }
+
+    job, err := client.IngestV2(memcode.PersonalV2IngestParams{
+        UserQuery:   "I'm moving to Seattle next month.",
+        EffortLevel: "high",
+    }, "move-1")
+    if err != nil {
+        panic(err)
+    }
+    status, err := client.GetIngestStatusV2(job.JobID)
+
+    hybrid, err := client.SearchV2WithOptions(memcode.HybridSearchParams{
+        Query:        "location",
+        OriginalTopK: 5,
+    }, memcode.PersonalV2SearchOptions{
+        TopK: 10,
+    })
+    if err != nil {
+        panic(err)
+    }
+    advancedAnswer, err := client.RetrieveV2(memcode.RetrieveParams{
+        Query: "Where am I moving?",
+    })
+    fmt.Println("V2:", status.Status, hybrid.Total, advancedAnswer.Answer)
+}
+```
+
+### Error handling
+
+```go
+result, err := client.Ingest(params)
+if err != nil {
+    switch e := err.(type) {
+    case *memcode.AuthenticationError:
+        fmt.Println("Bad API key:", e.Message)
+    case *memcode.RateLimitError:
+        fmt.Printf("Throttled, retry after %ds\n", e.RetryAfter)
+    case *memcode.NotReadyError:
+        fmt.Println("Pipelines loading, retry shortly")
+    default:
+        fmt.Println("Error:", err)
+    }
+}
+```
+
+---
+
+## API Reference
+
+All three SDKs expose backwards-compatible v1 methods plus advanced personal v2 methods:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| **ingest** | `POST /v1/memory/ingest` | Store a conversation turn. Memcode classifies the input and extracts profile facts, temporal events, and summaries automatically. |
+| **retrieve** | `POST /v1/memory/retrieve` | Answer a question using stored memories. Returns an LLM-generated answer with source citations and a confidence score. |
+| **search** | `POST /v1/memory/search` | Raw semantic search across memory domains (`profile`, `temporal`, `summary`). Returns matching records without an LLM answer. |
+| **personal v2 ingest** | `POST /v2/memory/ingest` | Start a durable normal-user ingest job. |
+| **personal v2 status** | `GET /v2/memory/ingest/{job_id}/status` | Poll durable ingest progress. |
+| **personal v2 search** | `POST /v2/memory/search` | Search extracted memories and original chunks for the user derived from the credential. |
+| **personal v2 retrieve** | `POST /v2/memory/retrieve` | Advanced attributed retrieval with connection-learning metadata. |
+| **ping** | `GET /health` | Health/readiness check. Never raises on a valid HTTP response. |
+
+## Error Types
+
+| Error | HTTP status | When |
+|-------|-------------|------|
+| `AuthenticationError` | 401 / 403 | Missing or invalid API key |
+| `RateLimitError` | 429 | Per-key rate limit exceeded |
+| `ValidationError` | 422 | Request body failed validation |
+| `NotReadyError` | 503 | Pipelines still initializing |
+| `ServerError` | 5xx | Server-side failure |
+| `ConnectionError` | &mdash; | Network timeout, DNS failure, connection refused |