onemillionbrain 0.1.0__tar.gz

onemillionbrain-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Build outputs
+dist/
+build/
+.next/
+out/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+
+# Database
+*.db
+*.db-journal
+*.db-shm
+*.db-wal
+
+# Test
+coverage/
+
+# Docker volumes
+data/
+redis-data/

onemillionbrain-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: onemillionbrain
+Version: 0.1.0
+Summary: Python client SDK for the 1MBrain REST API — portable memory layer for AI agents.
+Project-URL: Homepage, https://github.com/mrizkiiy04/1mbrain
+Project-URL: Repository, https://github.com/mrizkiiy04/1mbrain
+Project-URL: Documentation, https://github.com/mrizkiiy04/1mbrain/tree/main/packages/sdk/python
+License: MIT
+Keywords: 1mbrain,agent,ai,llm,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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: async
+Requires-Dist: httpx>=0.27.0; extra == 'async'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 1MBrain Python SDK
+
+Python client for the [1MBrain](https://github.com/mrizkiiy04/1mbrain) REST API — a portable, holographic memory layer for AI agents.
+
+## Installation
+
+```bash
+# Sync client (zero extra dependencies — uses stdlib urllib)
+pip install onemillionbrain
+
+# Async client (requires httpx)
+pip install onemillionbrain[async]
+```
+
+## Quick Start
+
+### Sync
+
+```python
+from onemillionbrain import OneMBrainClient
+
+client = OneMBrainClient(
+    api_url="http://localhost:3001",
+    api_key="your-api-key",
+    agent_id="my-agent",
+)
+
+# Store a memory
+memory = client.remember("User prefers Bahasa Indonesia as primary language", type="semantic")
+print(memory.id)
+
+# Search memories
+results = client.recall("language preference", limit=5)
+for r in results:
+    print(f"[{r.score:.3f}] {r.memory.content}")
+
+# Create an explicit association
+client.associate(results[0].memory.id, results[1].memory.id, strength=0.8)
+
+# Forget a memory
+client.forget(memory.id)
+```
+
+### Async
+
+```python
+import asyncio
+from onemillionbrain import AsyncOneMBrainClient
+
+async def main():
+    async with AsyncOneMBrainClient(
+        api_url="http://localhost:3001",
+        api_key="your-api-key",
+        agent_id="my-agent",
+    ) as client:
+        memory = await client.remember("User asked about pricing on 2026-06-10", type="episodic")
+        results = await client.recall("pricing questions")
+        await client.forget(memory.id)
+
+asyncio.run(main())
+```
+
+### Agent Integration
+
+To ensure your LLM agent knows exactly how and when to use 1MBrain, the SDK exports a pre-written `AGENT_SYSTEM_PROMPT`. Inject this into your agent's system instructions.
+
+```python
+from onemillionbrain import AGENT_SYSTEM_PROMPT
+
+system_instruction = f"""
+You are a helpful AI assistant.
+{AGENT_SYSTEM_PROMPT}
+"""
+
+# Pass system_instruction to LangChain, OpenAI, Anthropic, etc.
+```
+
+### LangChain Integration
+
+```python
+from langchain.tools import tool
+from onemillionbrain import OneMBrainClient
+
+brain = OneMBrainClient(
+    api_url="http://localhost:3001",
+    api_key="your-api-key",
+    agent_id="langchain-agent",
+)
+
+@tool
+def remember_tool(content: str) -> str:
+    """Store something in long-term memory."""
+    memory = brain.remember(content, type="episodic")
+    return f"Stored memory: {memory.id}"
+
+@tool
+def recall_tool(query: str) -> str:
+    """Search long-term memory."""
+    results = brain.recall(query, limit=5)
+    if not results:
+        return "No memories found."
+    return "\n".join(f"- {r.memory.content}" for r in results)
+```
+
+## API Reference
+
+### `OneMBrainClient(api_url, api_key, agent_id=None)`
+
+| Parameter  | Type  | Description                                            |
+|------------|-------|--------------------------------------------------------|
+| `api_url`  | `str` | Base URL of the 1MBrain API (e.g. `http://localhost:3001`) |
+| `api_key`  | `str` | Your API key (passed as `X-API-Key` header)            |
+| `agent_id` | `str` | Default agent namespace (can be overridden per call)   |
+
+### Methods
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `remember` | `(content, *, type, importance, tags, metadata, agent_id)` | `Memory` |
+| `recall` | `(query, *, limit, type, tags, max_hops, activation_threshold, blend_weight, agent_id)` | `list[RecallResult]` |
+| `forget` | `(memory_id, *, agent_id)` | `bool` |
+| `associate` | `(source_id, target_id, *, strength, origin, agent_id)` | `AssociateResult` |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

onemillionbrain-0.1.0/README.md

@@ -0,0 +1,129 @@
+# 1MBrain Python SDK
+
+Python client for the [1MBrain](https://github.com/mrizkiiy04/1mbrain) REST API — a portable, holographic memory layer for AI agents.
+
+## Installation
+
+```bash
+# Sync client (zero extra dependencies — uses stdlib urllib)
+pip install onemillionbrain
+
+# Async client (requires httpx)
+pip install onemillionbrain[async]
+```
+
+## Quick Start
+
+### Sync
+
+```python
+from onemillionbrain import OneMBrainClient
+
+client = OneMBrainClient(
+    api_url="http://localhost:3001",
+    api_key="your-api-key",
+    agent_id="my-agent",
+)
+
+# Store a memory
+memory = client.remember("User prefers Bahasa Indonesia as primary language", type="semantic")
+print(memory.id)
+
+# Search memories
+results = client.recall("language preference", limit=5)
+for r in results:
+    print(f"[{r.score:.3f}] {r.memory.content}")
+
+# Create an explicit association
+client.associate(results[0].memory.id, results[1].memory.id, strength=0.8)
+
+# Forget a memory
+client.forget(memory.id)
+```
+
+### Async
+
+```python
+import asyncio
+from onemillionbrain import AsyncOneMBrainClient
+
+async def main():
+    async with AsyncOneMBrainClient(
+        api_url="http://localhost:3001",
+        api_key="your-api-key",
+        agent_id="my-agent",
+    ) as client:
+        memory = await client.remember("User asked about pricing on 2026-06-10", type="episodic")
+        results = await client.recall("pricing questions")
+        await client.forget(memory.id)
+
+asyncio.run(main())
+```
+
+### Agent Integration
+
+To ensure your LLM agent knows exactly how and when to use 1MBrain, the SDK exports a pre-written `AGENT_SYSTEM_PROMPT`. Inject this into your agent's system instructions.
+
+```python
+from onemillionbrain import AGENT_SYSTEM_PROMPT
+
+system_instruction = f"""
+You are a helpful AI assistant.
+{AGENT_SYSTEM_PROMPT}
+"""
+
+# Pass system_instruction to LangChain, OpenAI, Anthropic, etc.
+```
+
+### LangChain Integration
+
+```python
+from langchain.tools import tool
+from onemillionbrain import OneMBrainClient
+
+brain = OneMBrainClient(
+    api_url="http://localhost:3001",
+    api_key="your-api-key",
+    agent_id="langchain-agent",
+)
+
+@tool
+def remember_tool(content: str) -> str:
+    """Store something in long-term memory."""
+    memory = brain.remember(content, type="episodic")
+    return f"Stored memory: {memory.id}"
+
+@tool
+def recall_tool(query: str) -> str:
+    """Search long-term memory."""
+    results = brain.recall(query, limit=5)
+    if not results:
+        return "No memories found."
+    return "\n".join(f"- {r.memory.content}" for r in results)
+```
+
+## API Reference
+
+### `OneMBrainClient(api_url, api_key, agent_id=None)`
+
+| Parameter  | Type  | Description                                            |
+|------------|-------|--------------------------------------------------------|
+| `api_url`  | `str` | Base URL of the 1MBrain API (e.g. `http://localhost:3001`) |
+| `api_key`  | `str` | Your API key (passed as `X-API-Key` header)            |
+| `agent_id` | `str` | Default agent namespace (can be overridden per call)   |
+
+### Methods
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `remember` | `(content, *, type, importance, tags, metadata, agent_id)` | `Memory` |
+| `recall` | `(query, *, limit, type, tags, max_hops, activation_threshold, blend_weight, agent_id)` | `list[RecallResult]` |
+| `forget` | `(memory_id, *, agent_id)` | `bool` |
+| `associate` | `(source_id, target_id, *, strength, origin, agent_id)` | `AssociateResult` |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

onemillionbrain-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "onemillionbrain"
+version = "0.1.0"
+description = "Python client SDK for the 1MBrain REST API — portable memory layer for AI agents."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["ai", "agent", "memory", "1mbrain", "llm"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+async = ["httpx>=0.27.0"]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.23.0",
+  "httpx>=0.27.0",
+  "respx>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/mrizkiiy04/1mbrain"
+Repository = "https://github.com/mrizkiiy04/1mbrain"
+Documentation = "https://github.com/mrizkiiy04/1mbrain/tree/main/packages/sdk/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/onemillionbrain"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

onemillionbrain-0.1.0/src/onemillionbrain/__init__.py

@@ -0,0 +1,32 @@
+"""1MBrain Python SDK — portable memory layer for AI agents."""
+
+from .client import OneMBrainClient, OneMBrainError
+from .models import (
+    AssociateInput,
+    AssociateResult,
+    AssociationRelationType,
+    ConsolidationResult,
+    Memory,
+    MemoryType,
+    RecallInput,
+    RecallResult,
+    RememberInput,
+)
+from .prompts import AGENT_SYSTEM_PROMPT
+
+__all__ = [
+    "OneMBrainClient",
+    "OneMBrainError",
+    "Memory",
+    "MemoryType",
+    "RememberInput",
+    "RecallInput",
+    "RecallResult",
+    "AssociateInput",
+    "AssociateResult",
+    "AssociationRelationType",
+    "ConsolidationResult",
+    "AGENT_SYSTEM_PROMPT",
+]
+
+__version__ = "0.1.0"