areev 0.1.6

# Areev Rust SDK

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

## Installation

```toml
[dependencies]
areev = "0.1"
```

For gRPC transport:
```toml
[dependencies]
areev = { version = "0.1", features = ["grpc"] }
```

## Quick Start

```rust
use areev::Areev;

#[tokio::main]
async fn main() -> areev::Result<()> {
    let areev = Areev::from_env(); // reads AREEV_API_KEY, AREEV_URL from env

    areev.remember("John likes coffee").await?;

    let results = areev.recall("what does John like?").await?;
    for hit in &results.results {
        println!("{}: {:?}", hit.grain_type, hit.fields);
    }

    Ok(())
}
```

### Configuration

The client reads from environment variables by default:

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

Or pass them explicitly:

```rust
let areev = Areev::new(
    Some("ar_..."),                // api_key
    Some("https://dub.areev.ai"), // url
    Some("my-memory"),            // memory_id
);
```

## API

| Method | Description |
|--------|-------------|
| `remember(text)` | Store natural-language memory (LLM extracts structure) |
| `recall(query)` | Search memories |
| `forget(hash)` | Delete a memory by hash |
| `add(req)` | Add a typed grain (low-level) |
| `get(hash)` | Get a grain by hash |
| `supersede(req)` | Update a grain |
| `chat_interactive(slug, conv_id, msg, executors)` | Harness chat with auto pause/resume for `client://` tools |
| `harness_chat(slug, req)` | Single harness turn (`completed` or `requires_action`) |
| `chat_resume(slug, req)` | Resume a paused session with client-side tool outputs |
| `cancel_chat_session(slug, session_id)` | Cancel a paused session (idempotent) |
| `health()` | Health check |
| `stats()` | Database statistics |
| `flush()` | Flush write buffer |

### Low-Level Client

For advanced use cases (custom request objects, gRPC transport):

```rust
use areev::{HttpClient, AddRequest, GrainType};

let client = HttpClient::new("http://localhost:4009", "default", Some("api-key"));
let resp = client.add(&AddRequest {
    grain_type: GrainType::Belief,
    fields: serde_json::json!({"subject": "john", "relation": "likes", "object": "coffee"}),
    options: None,
}).await?;
```

### Harness Chat

Use `chat_interactive` to drive a harness (Areev's LLM-plus-tools runtime) with client-side tool executors. The helper runs the pause/resume loop for you when the model calls a `client://` tool:

```rust
use std::pin::Pin;
use areev::{Areev, ChatExecutors};
use serde_json::json;

let areev = Areev::from_env();

let mut executors: ChatExecutors = ChatExecutors::new();
executors.insert("get_weather", Box::new(|_name, args| {
    Pin::from(Box::new(async move {
        let city = args.get("city").and_then(|v| v.as_str()).unwrap_or("unknown");
        Ok(json!({ "city": city, "temp_c": 22, "conditions": "sunny" }))
    }))
}));

let response = areev
    .chat_interactive("weather-harness", "conv-1", "What's the weather in Paris?", &executors)
    .await?;

println!("{}", response.text);
```

`harness_chat`, `chat_resume`, and `cancel_chat_session` are the low-level primitives if you want to run the loop yourself.

## Transports

| Transport | Feature | Default |
|-----------|---------|---------|
| HTTP/REST | `http` | Yes |
| gRPC | `grpc` | No |

## License

BUSL-1.1