lore-sdk 0.1.0__tar.gz

lore_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src/ tests/
+      - name: Test
+        run: pytest
+
+  typescript:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20]
+    defaults:
+      run:
+        working-directory: ts
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Install dependencies
+        run: npm ci
+      - name: Build
+        run: npm run build
+      - name: Test
+        run: npm test

lore_sdk-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+node_modules/
+*.pyc
+.ruff_cache/
+ts/dist/
+ts/node_modules/
+.env

lore_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amit Paz
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

lore_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: lore-sdk
+Version: 0.1.0
+Summary: Cross-agent memory library
+Project-URL: Homepage, https://github.com/amitpaz1/lore
+Project-URL: Repository, https://github.com/amitpaz1/lore
+Project-URL: Issues, https://github.com/amitpaz1/lore/issues
+Author-email: Amit Paz <amit.paz@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,lessons,lore,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: onnxruntime>=1.14.0
+Requires-Dist: python-ulid>=2.0.0
+Requires-Dist: tokenizers>=0.13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<![CDATA[# Lore
+
+[![PyPI](https://img.shields.io/pypi/v/lore-sdk)](https://pypi.org/project/lore-sdk/)
+[![npm](https://img.shields.io/npm/v/lore-sdk)](https://www.npmjs.com/package/lore-sdk)
+[![Tests](https://img.shields.io/github/actions/workflow/status/amitpaz/lore/ci.yml?label=tests)](https://github.com/amitpaz/lore/actions)
+[![License](https://img.shields.io/github/license/amitpaz/lore)](LICENSE)
+
+**Cross-agent memory.** Agents publish what they learn, other agents query it. PII redacted automatically.
+
+## Why Lore?
+
+Your agents keep making the same mistakes. Agent A discovers Stripe rate-limits at 100 req/min. Agent B hits the same wall tomorrow. No learning transfer.
+
+Lore fixes this. It's a tiny library — no server, no infra — that gives agents a shared memory of operational lessons. Publish a lesson in one line, query it in another. Sensitive data is redacted before storage automatically.
+
+**What Lore is:** A local-first SDK for storing and retrieving structured lessons across agent runs. SQLite-backed, embedding-powered semantic search, automatic PII redaction.
+
+**What Lore is not:** A conversation memory store (see Mem0/Zep), a vector database, or a RAG framework.
+
+## Quickstart
+
+```python
+from lore import Lore
+
+lore = Lore()  # zero config — local SQLite, built-in embeddings
+
+lore.publish(
+    problem="Stripe API returns 429 after 100 req/min",
+    resolution="Exponential backoff starting at 1s, cap at 32s",
+    tags=["stripe", "rate-limit"],
+    confidence=0.9,
+)
+
+lessons = lore.query("stripe rate limiting")
+prompt = lore.as_prompt(lessons)  # ready for system prompt injection
+```
+
+```typescript
+import { Lore } from 'lore-sdk';
+
+const lore = new Lore({ embeddingFn: yourEmbedFn });
+
+await lore.publish({
+  problem: 'Stripe API returns 429 after 100 req/min',
+  resolution: 'Exponential backoff starting at 1s, cap at 32s',
+  tags: ['stripe', 'rate-limit'],
+  confidence: 0.9,
+});
+
+const lessons = await lore.query('stripe rate limiting');
+const prompt = lore.asPrompt(lessons);
+```
+
+## Install
+
+**Python** (3.9+):
+```bash
+pip install lore-sdk
+```
+
+**TypeScript** (Node 18+):
+```bash
+npm install lore-sdk
+```
+
+## Python API Reference
+
+### `Lore(project?, db_path?, store?, embedding_fn?, embedder?, redact?, redact_patterns?, decay_half_life_days?)`
+
+Create a Lore instance.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `project` | `str \| None` | `None` | Scope lessons to a project name |
+| `db_path` | `str \| None` | `~/.lore/default.db` | Path to SQLite database |
+| `store` | `Store \| None` | `None` | Custom storage backend |
+| `embedding_fn` | `Callable[[str], list[float]] \| None` | `None` | Custom embedding function |
+| `embedder` | `Embedder \| None` | `None` | Custom embedder instance |
+| `redact` | `bool` | `True` | Enable automatic PII redaction |
+| `redact_patterns` | `list[tuple[str, str]] \| None` | `None` | Custom redaction patterns as `(regex, label)` |
+| `decay_half_life_days` | `float` | `30` | Half-life for lesson score decay |
+
+Lore supports context manager usage:
+
+```python
+with Lore() as lore:
+    lore.publish(problem="...", resolution="...")
+```
+
+### `lore.publish(problem, resolution, context?, tags?, confidence?, source?, project?) → str`
+
+Publish a lesson. Returns the lesson ID (ULID).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `problem` | `str` | *required* | What went wrong |
+| `resolution` | `str` | *required* | How to fix it |
+| `context` | `str \| None` | `None` | Additional context |
+| `tags` | `list[str] \| None` | `[]` | Filterable tags |
+| `confidence` | `float` | `0.5` | Confidence score (0.0–1.0) |
+| `source` | `str \| None` | `None` | Who/what created this lesson |
+| `project` | `str \| None` | instance default | Override project scope |
+
+### `lore.query(text, tags?, limit?, min_confidence?) → list[QueryResult]`
+
+Query lessons by semantic similarity.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `text` | `str` | *required* | Search query |
+| `tags` | `list[str] \| None` | `None` | Filter: lessons must have ALL these tags |
+| `limit` | `int` | `5` | Max results |
+| `min_confidence` | `float` | `0.0` | Minimum confidence threshold |
+
+Returns `list[QueryResult]` sorted by score (cosine similarity × confidence × time decay × vote factor).
+
+### `lore.as_prompt(lessons, max_tokens?) → str`
+
+Format query results as a markdown string for system prompt injection.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `lessons` | `list[QueryResult]` | *required* | Results from `query()` |
+| `max_tokens` | `int` | `1000` | Approximate token budget (1 token ≈ 4 chars) |
+
+### `lore.get(lesson_id) → Lesson | None`
+
+Retrieve a single lesson by ID.
+
+### `lore.list(project?, limit?) → list[Lesson]`
+
+List lessons, optionally filtered by project.
+
+### `lore.delete(lesson_id) → bool`
+
+Delete a lesson. Returns `True` if found and deleted.
+
+### `lore.upvote(lesson_id) → None`
+
+Increment a lesson's upvote count. Raises `LessonNotFoundError` if not found.
+
+### `lore.downvote(lesson_id) → None`
+
+Increment a lesson's downvote count. Raises `LessonNotFoundError` if not found.
+
+### `lore.export_lessons(path?) → list[dict]`
+
+Export lessons as JSON-serializable dicts. If `path` is given, writes to file.
+
+### `lore.import_lessons(path?, data?) → int`
+
+Import lessons from file or data. Skips duplicates by ID. Returns count imported.
+
+### `lore.close() → None`
+
+Close the underlying store.
+
+## TypeScript API Reference
+
+The TypeScript SDK mirrors the Python API. See [ts/README.md](ts/README.md) for full details.
+
+Key differences:
+- All store operations are `async`
+- Constructor takes an options object: `new Lore({ project, dbPath, embeddingFn, ... })`
+- No built-in embedding model — you must provide `embeddingFn`
+- `asPrompt()` instead of `as_prompt()`
+- `minConfidence` instead of `min_confidence` (camelCase throughout)
+
+## Redaction
+
+Lore automatically redacts sensitive data before storage:
+
+- **API keys** (Bearer tokens, `sk-*`, `key-*`, etc.)
+- **Email addresses**
+- **Phone numbers**
+- **IP addresses** (IPv4 and IPv6)
+- **Credit card numbers** (with Luhn validation)
+
+```python
+lore.publish(
+    problem="Auth failed with key sk-abc123def456ghi789jkl012mno",
+    resolution="Rotate the key",
+)
+# Stored as: "Auth failed with key [REDACTED:api_key]"
+```
+
+Add custom patterns:
+
+```python
+lore = Lore(redact_patterns=[
+    (r"ACCT-\d{8}", "account_id"),
+])
+```
+
+Disable redaction entirely with `redact=False`.
+
+## Scoring
+
+Query results are ranked by:
+
+```
+score = cosine_similarity × confidence × time_decay × vote_factor
+```
+
+- **Time decay:** Lessons lose relevance over time (configurable half-life, default 30 days)
+- **Vote factor:** `1.0 + (upvotes - downvotes) × 0.1`, floored at 0.1
+- **Confidence:** Author's self-assessed confidence (0.0–1.0)
+
+## Examples
+
+See [`examples/`](examples/) for runnable scripts:
+- [`basic_usage.py`](examples/basic_usage.py) — publish, query, format
+- [`custom_embeddings.py`](examples/custom_embeddings.py) — bring your own embedding function
+- [`redaction_demo.py`](examples/redaction_demo.py) — see redaction in action
+
+## License
+
+MIT
+]]>

lore_sdk-0.1.0/README.md

@@ -0,0 +1,219 @@
+<![CDATA[# Lore
+
+[![PyPI](https://img.shields.io/pypi/v/lore-sdk)](https://pypi.org/project/lore-sdk/)
+[![npm](https://img.shields.io/npm/v/lore-sdk)](https://www.npmjs.com/package/lore-sdk)
+[![Tests](https://img.shields.io/github/actions/workflow/status/amitpaz/lore/ci.yml?label=tests)](https://github.com/amitpaz/lore/actions)
+[![License](https://img.shields.io/github/license/amitpaz/lore)](LICENSE)
+
+**Cross-agent memory.** Agents publish what they learn, other agents query it. PII redacted automatically.
+
+## Why Lore?
+
+Your agents keep making the same mistakes. Agent A discovers Stripe rate-limits at 100 req/min. Agent B hits the same wall tomorrow. No learning transfer.
+
+Lore fixes this. It's a tiny library — no server, no infra — that gives agents a shared memory of operational lessons. Publish a lesson in one line, query it in another. Sensitive data is redacted before storage automatically.
+
+**What Lore is:** A local-first SDK for storing and retrieving structured lessons across agent runs. SQLite-backed, embedding-powered semantic search, automatic PII redaction.
+
+**What Lore is not:** A conversation memory store (see Mem0/Zep), a vector database, or a RAG framework.
+
+## Quickstart
+
+```python
+from lore import Lore
+
+lore = Lore()  # zero config — local SQLite, built-in embeddings
+
+lore.publish(
+    problem="Stripe API returns 429 after 100 req/min",
+    resolution="Exponential backoff starting at 1s, cap at 32s",
+    tags=["stripe", "rate-limit"],
+    confidence=0.9,
+)
+
+lessons = lore.query("stripe rate limiting")
+prompt = lore.as_prompt(lessons)  # ready for system prompt injection
+```
+
+```typescript
+import { Lore } from 'lore-sdk';
+
+const lore = new Lore({ embeddingFn: yourEmbedFn });
+
+await lore.publish({
+  problem: 'Stripe API returns 429 after 100 req/min',
+  resolution: 'Exponential backoff starting at 1s, cap at 32s',
+  tags: ['stripe', 'rate-limit'],
+  confidence: 0.9,
+});
+
+const lessons = await lore.query('stripe rate limiting');
+const prompt = lore.asPrompt(lessons);
+```
+
+## Install
+
+**Python** (3.9+):
+```bash
+pip install lore-sdk
+```
+
+**TypeScript** (Node 18+):
+```bash
+npm install lore-sdk
+```
+
+## Python API Reference
+
+### `Lore(project?, db_path?, store?, embedding_fn?, embedder?, redact?, redact_patterns?, decay_half_life_days?)`
+
+Create a Lore instance.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `project` | `str \| None` | `None` | Scope lessons to a project name |
+| `db_path` | `str \| None` | `~/.lore/default.db` | Path to SQLite database |
+| `store` | `Store \| None` | `None` | Custom storage backend |
+| `embedding_fn` | `Callable[[str], list[float]] \| None` | `None` | Custom embedding function |
+| `embedder` | `Embedder \| None` | `None` | Custom embedder instance |
+| `redact` | `bool` | `True` | Enable automatic PII redaction |
+| `redact_patterns` | `list[tuple[str, str]] \| None` | `None` | Custom redaction patterns as `(regex, label)` |
+| `decay_half_life_days` | `float` | `30` | Half-life for lesson score decay |
+
+Lore supports context manager usage:
+
+```python
+with Lore() as lore:
+    lore.publish(problem="...", resolution="...")
+```
+
+### `lore.publish(problem, resolution, context?, tags?, confidence?, source?, project?) → str`
+
+Publish a lesson. Returns the lesson ID (ULID).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `problem` | `str` | *required* | What went wrong |
+| `resolution` | `str` | *required* | How to fix it |
+| `context` | `str \| None` | `None` | Additional context |
+| `tags` | `list[str] \| None` | `[]` | Filterable tags |
+| `confidence` | `float` | `0.5` | Confidence score (0.0–1.0) |
+| `source` | `str \| None` | `None` | Who/what created this lesson |
+| `project` | `str \| None` | instance default | Override project scope |
+
+### `lore.query(text, tags?, limit?, min_confidence?) → list[QueryResult]`
+
+Query lessons by semantic similarity.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `text` | `str` | *required* | Search query |
+| `tags` | `list[str] \| None` | `None` | Filter: lessons must have ALL these tags |
+| `limit` | `int` | `5` | Max results |
+| `min_confidence` | `float` | `0.0` | Minimum confidence threshold |
+
+Returns `list[QueryResult]` sorted by score (cosine similarity × confidence × time decay × vote factor).
+
+### `lore.as_prompt(lessons, max_tokens?) → str`
+
+Format query results as a markdown string for system prompt injection.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `lessons` | `list[QueryResult]` | *required* | Results from `query()` |
+| `max_tokens` | `int` | `1000` | Approximate token budget (1 token ≈ 4 chars) |
+
+### `lore.get(lesson_id) → Lesson | None`
+
+Retrieve a single lesson by ID.
+
+### `lore.list(project?, limit?) → list[Lesson]`
+
+List lessons, optionally filtered by project.
+
+### `lore.delete(lesson_id) → bool`
+
+Delete a lesson. Returns `True` if found and deleted.
+
+### `lore.upvote(lesson_id) → None`
+
+Increment a lesson's upvote count. Raises `LessonNotFoundError` if not found.
+
+### `lore.downvote(lesson_id) → None`
+
+Increment a lesson's downvote count. Raises `LessonNotFoundError` if not found.
+
+### `lore.export_lessons(path?) → list[dict]`
+
+Export lessons as JSON-serializable dicts. If `path` is given, writes to file.
+
+### `lore.import_lessons(path?, data?) → int`
+
+Import lessons from file or data. Skips duplicates by ID. Returns count imported.
+
+### `lore.close() → None`
+
+Close the underlying store.
+
+## TypeScript API Reference
+
+The TypeScript SDK mirrors the Python API. See [ts/README.md](ts/README.md) for full details.
+
+Key differences:
+- All store operations are `async`
+- Constructor takes an options object: `new Lore({ project, dbPath, embeddingFn, ... })`
+- No built-in embedding model — you must provide `embeddingFn`
+- `asPrompt()` instead of `as_prompt()`
+- `minConfidence` instead of `min_confidence` (camelCase throughout)
+
+## Redaction
+
+Lore automatically redacts sensitive data before storage:
+
+- **API keys** (Bearer tokens, `sk-*`, `key-*`, etc.)
+- **Email addresses**
+- **Phone numbers**
+- **IP addresses** (IPv4 and IPv6)
+- **Credit card numbers** (with Luhn validation)
+
+```python
+lore.publish(
+    problem="Auth failed with key sk-abc123def456ghi789jkl012mno",
+    resolution="Rotate the key",
+)
+# Stored as: "Auth failed with key [REDACTED:api_key]"
+```
+
+Add custom patterns:
+
+```python
+lore = Lore(redact_patterns=[
+    (r"ACCT-\d{8}", "account_id"),
+])
+```
+
+Disable redaction entirely with `redact=False`.
+
+## Scoring
+
+Query results are ranked by:
+
+```
+score = cosine_similarity × confidence × time_decay × vote_factor
+```
+
+- **Time decay:** Lessons lose relevance over time (configurable half-life, default 30 days)
+- **Vote factor:** `1.0 + (upvotes - downvotes) × 0.1`, floored at 0.1
+- **Confidence:** Author's self-assessed confidence (0.0–1.0)
+
+## Examples
+
+See [`examples/`](examples/) for runnable scripts:
+- [`basic_usage.py`](examples/basic_usage.py) — publish, query, format
+- [`custom_embeddings.py`](examples/custom_embeddings.py) — bring your own embedding function
+- [`redaction_demo.py`](examples/redaction_demo.py) — see redaction in action
+
+## License
+
+MIT
+]]>