Metadata-Version: 2.4
Name: clawdb
Version: 0.1.1
Summary: Zero-config database for AI agents.
License: MIT
Keywords: agents,ai,clawdb,database,grpc,langchain,memory,openai
Classifier: Development Status :: 3 - Alpha
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 :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: grpcio-tools>=1.60.0
Requires-Dist: grpcio>=1.60.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: protobuf>=4.25.0
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: structlog>=24.2
Requires-Dist: tenacity>=8.2.0
Provides-Extra: async
Requires-Dist: grpcio>=1.64; extra == 'async'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == 'langchain'
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == 'openai'
Description-Content-Type: text/markdown

# clawdb (Python SDK)

The official Python client for **ClawDB**.

This package is a network client, not the database engine itself. It connects to a running `clawdb-server` instance locally or to a hosted cloud endpoint.

```bash
pip install clawdb
```

Before using the SDK locally, make sure `clawdb-server` is running. The intended local-first path is:

```bash
npx @clawdb/cli@latest init
```

If you operate your own server, set `CLAWDB_ENDPOINT` to that address instead.

## Sync usage

```python
from clawdb import ClawDB

db = ClawDB(endpoint="http://localhost:50050", agent_id="my-agent")

# Store a memory
id = db.memory.remember("Deploy at 3 PM UTC", memory_type="task", tags=["ops"])

# Search
results = db.memory.search("deploy schedule", top_k=5)
for r in results:
    print(f"{r.score:.3f}  {r.memory.content}")

# Recall by ID
memories = db.memory.recall([id])

# Forget
db.memory.forget(id)
```

## Async usage

```python
import asyncio
from clawdb.aio import AsyncClawDB

async def main():
    async with AsyncClawDB(endpoint="http://localhost:50050") as db:
        id = await db.memory.remember("Async test")
        results = await db.memory.search("test")

asyncio.run(main())
```

## Branches

```python
branch = db.branches.fork("my-experiment")
db.memory.remember("hypothesis", tags=["experiment"])  # writes to current branch
db.branches.merge("my-experiment", into="trunk")
```

## LangChain integration

```python
from clawdb.langchain import ClawDBRetriever
retriever = ClawDBRetriever(db=db, top_k=10)
docs = retriever.get_relevant_documents("deploy schedule")
```

## Configuration

| Env var | Description |
|---|---|
| `CLAWDB_ENDPOINT` | gRPC endpoint (default `http://localhost:50050`) |
| `CLAWDB_API_KEY` | API key (`ck_live_...` or `ck_test_...`) |
| `CLAWDB_AGENT_ID` | Agent identifier |

## Runtime model

- Python talks to `clawdb-server` over gRPC.
- `clawdb-server` hosts the Rust runtime and storage engine.
- For cloud usage, point `CLAWDB_ENDPOINT` at your hosted deployment and provide `CLAWDB_API_KEY`.

## Development

```bash
pip install -e ".[dev]"
pytest
```

