Metadata-Version: 2.4
Name: areev
Version: 0.0.0
Summary: Python SDK for the Areev knowledge database — HTTP, gRPC, and MCP transports
Project-URL: Repository, https://github.com/AreevAI/areev-sdk-python
Project-URL: Documentation, https://areev.ai/docs
License-Expression: BUSL-1.1
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: datamodel-code-generator>=0.26; extra == 'dev'
Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: grpc
Requires-Dist: grpcio>=1.60; extra == 'grpc'
Requires-Dist: protobuf>=5.0; extra == 'grpc'
Description-Content-Type: text/markdown

# Areev Python SDK

Python client library for the [Areev](https://areev.ai) knowledge database.

## Installation

```bash
pip install areev
```

For gRPC transport:
```bash
pip install areev[grpc]
```

## Quick Start

```python
from areev import Areev

areev = Areev()  # reads AREEV_API_KEY, AREEV_URL from env
areev.remember("John likes coffee")

results = areev.recall("what does John like?")
for hit in results.results:
    print(f"  {hit.grain_type}: {hit.fields}")
```

### Configuration

The client reads from environment variables by default:

| Variable | Default | Description |
|----------|---------|-------------|
| `AREEV_API_KEY` | — | API key (sent as `X-API-Key` header) |
| `AREEV_URL` | `https://app.areev.ai` | Server endpoint |
| `AREEV_MEMORY_ID` | `default` | Memory database ID |

Or pass them explicitly:

```python
areev = Areev(api_key="ar_...", url="https://dub.areev.ai", memory_id="my-memory")
```

### Async

```python
from areev import AsyncAreev

async with AsyncAreev() as areev:
    await areev.remember("John likes coffee")
    results = await areev.recall("what does John like?")
```

## API

| Method | Description |
|--------|-------------|
| `remember(text)` | Store natural-language memory (LLM extracts structure) |
| `recall(query)` | Search memories |
| `forget(hash)` | Delete a memory by hash |
| `add(grain_type, **fields)` | Add a typed grain (low-level) |
| `get(hash)` | Get a grain by hash |
| `supersede(old_hash, grain_type, **fields)` | Update a grain |
| `health()` | Health check |
| `stats()` | Database statistics |
| `flush()` | Flush write buffer |

### Low-Level Client

For advanced use cases (custom request objects, full async control):

```python
from areev import HttpClient, AreevConfig, AddRequest, GrainType

config = AreevConfig(url="http://localhost:4009", memory_id="default", api_key="your-key")
async with HttpClient(config) as client:
    resp = await client.add(AddRequest(
        grain_type=GrainType.BELIEF,
        fields={"subject": "john", "relation": "likes", "object": "coffee"},
    ))
```

## Transports

| Transport | Extra | Status |
|-----------|-------|--------|
| HTTP/REST | _(default)_ | Available |
| gRPC | `areev[grpc]` | Available |
| MCP | — | Planned |

## Code Generation

Generate gRPC stubs and Pydantic models from the Areev spec:

```bash
pip install areev[dev]
./scripts/generate.sh
```

## License

BUSL-1.1
