# aqoon

[![PyPI](https://img.shields.io/pypi/v/aqoon)](https://pypi.org/project/aqoon/)

Python SDK for [aqoon](https://aqoon.ai) — make your knowledge available to any AI.

## Installation

```bash
pip install aqoon
```

## Quick Start

```python
from aqoon import Aqoon

client = Aqoon(api_key="aqn_your_api_key")

# Search your knowledge base
results = client.search("machine learning basics")
for r in results["results"]:
    print(f"{r['title']} (score: {r['score']:.3f})")
    print(f"  {r['content'][:100]}...")
```

## Usage

### Search

```python
# Search all collections
results = client.search("your query")

# Search a specific collection
results = client.search("your query", collection="my-docs")

# Limit results
results = client.search("your query", limit=10)
```

### Collections

```python
# List your collections
collections = client.list_collections()

# Get collection details
collection = client.get_collection("collection-uuid")

# Subscribe to a public collection
client.subscribe("collection-slug")

# Unsubscribe
client.unsubscribe("collection-slug")
```

### Documents

```python
# List documents (with optional filters)
docs = client.list_documents()
docs = client.list_documents(collection="my-docs")
docs = client.list_documents(tag="important")

# Get document with content and chunks
doc = client.get_document("document-uuid")
print(doc["content_text"])
for chunk in doc["chunks"]:
    print(f"  Chunk {chunk['chunk_index']}: {chunk['content'][:50]}...")
```

### API Keys

```python
# List keys
keys = client.list_keys()

# Create a full-access key
new_key = client.create_key("My New Key", is_full_access=True)
print(f"Key: {new_key['key']}")  # Only shown once!

# Create a scoped key
new_key = client.create_key("Scoped Key", collections=["docs", "policies"])

# Revoke a key
client.revoke_key("key-uuid")

# Rotate a key
rotated = client.rotate_key("key-uuid")
print(f"New key: {rotated['key']}")
```

### Usage Stats

```python
# Aggregate usage across all keys
stats = client.usage(days=7)
print(f"Total requests: {stats['total_requests']}")

# Per-key usage
key_stats = client.key_usage("key-uuid", days=30)
```

## Error Handling

```python
from aqoon import Aqoon, NotFoundError, RateLimitError, AuthenticationError

client = Aqoon(api_key="aqn_your_key")

try:
    doc = client.get_document("nonexistent-uuid")
except NotFoundError:
    print("Document not found")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
```

## Context Manager

```python
with Aqoon(api_key="aqn_your_key") as client:
    results = client.search("your query")
# Connection automatically closed
```

## Configuration

```python
client = Aqoon(
    api_key="aqn_your_key",
    base_url="https://aqoon.ai",  # default
    timeout=30.0,                  # seconds, default
)
```

## Requirements

- Python 3.10+
- An aqoon account with an API key ([get one here](https://aqoon.ai/keys/))

## License

MIT
