Metadata-Version: 2.4
Name: aqoon
Version: 0.1.1
Summary: Python SDK for aqoon — make your knowledge available to any AI
Project-URL: Homepage, https://aqoon.ai
Project-URL: Documentation, https://aqoon.ai/docs/
Project-URL: Repository, https://gitlab.com/54startups/aqoon
Author-email: "54 Startups Inc." <hello@54startups.com>
License-Expression: MIT
Keywords: ai,aqoon,knowledge,mcp,rag,search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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 :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27
Provides-Extra: all
Requires-Dist: haystack-ai<3.0,>=2.0; extra == 'all'
Requires-Dist: langchain-core<1.0,>=0.2; extra == 'all'
Requires-Dist: llama-index-core<1.0,>=0.10; extra == 'all'
Provides-Extra: haystack
Requires-Dist: haystack-ai<3.0,>=2.0; extra == 'haystack'
Provides-Extra: langchain
Requires-Dist: langchain-core<1.0,>=0.2; extra == 'langchain'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core<1.0,>=0.10; extra == 'llamaindex'
Description-Content-Type: text/markdown

# 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
