Metadata-Version: 2.4
Name: togolm
Version: 0.1.1
Summary: Minimal Python client for the TogoLM API
Project-URL: Repository, https://github.com/omarfarouk228/togolm
License: MIT
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# togolm

Minimal Python client for the [TogoLM API](https://github.com/omarfarouk228/togolm/blob/main/docs/api-reference.md).

Requires Python 3.9+. Built on [httpx](https://www.python-httpx.org/).

## Install

```bash
pip install togolm
```

## Get an API key

```python
from togolm import TogoLM

client = TogoLM()  # no key needed for this call
result = client.register_key(email="you@example.com", name="Your Name")
api_key = result["api_key"]
```

You can also call `client.query(...)` without a key — public access is rate-limited (see [rate limits](https://github.com/omarfarouk228/togolm/blob/main/docs/api-reference.md#rate-limits)).

## Usage

```python
from togolm import TogoLM

client = TogoLM(api_key="your_api_key")

result = client.query("Comment créer une entreprise au Togo ?")
print(result["answer"], result["sources"])
```

### Streaming

```python
for event in client.query_stream("Comment créer une entreprise au Togo ?"):
    if event["type"] == "chunk":
        print(event["text"], end="")
    if event["type"] == "sources":
        print("Sources:", event["sources"])
```

### Local development

Point at a local API instead of production:

```python
client = TogoLM(base_url="http://localhost:8000/v1")
```

### Error handling

Non-2xx responses raise `TogoLMError` (`status` and `body` attributes):

```python
from togolm import TogoLM, TogoLMError

try:
    client.query("...")
except TogoLMError as err:
    print(err.status, err.body)
```

### Context manager

`TogoLM` holds an `httpx.Client`; use it as a context manager to close it automatically:

```python
with TogoLM(api_key="your_api_key") as client:
    result = client.query("...")
```

## All methods

| Method | Description |
|--------|-------------|
| `query(question, category=None, language=None)` | RAG query, full response |
| `query_stream(question, category=None, language=None)` | RAG query, SSE stream (generator) |
| `embed(text)` | Generate an embedding vector |
| `search(q)` | Full-text search over the corpus |
| `categories()` | List available corpus categories |
| `stats()` | Public corpus statistics |
| `documents(page=None, limit=None, category=None)` | Paginated document list |
| `document(doc_id)` | Document detail, including chunks |
| `register_key(email=None, name=None)` | Request a free API key |
| `me()` | Current API key info and usage |
| `close()` | Close the underlying HTTP client |

Full request/response shapes: [API reference](https://github.com/omarfarouk228/togolm/blob/main/docs/api-reference.md).
