Metadata-Version: 2.4
Name: aetherkit
Version: 0.1.0
Summary: Minimalist Python library for simple LLM integration, easy RAG, test/prod modes and cost tracking
Author: AetherKit Contributors
License: MIT
Project-URL: Homepage, https://github.com/yourusername/aetherkit
Project-URL: Documentation, https://github.com/yourusername/aetherkit
Project-URL: Repository, https://github.com/yourusername/aetherkit
Keywords: llm,ai,rag,openai,agents,cost-tracking
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 :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.40.0
Requires-Dist: pydantic>=2.7
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: httpx>=0.27
Requires-Dist: tiktoken>=0.7
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# AetherKit

**Minimalist Python library for simple LLM integration, transparent cost tracking and first-class test/production modes.**

> Simple. Transparent. Controllable.

AetherKit helps you go from idea to clean LLM code without fighting a heavy framework.

## Features (v0.1.0)

- **Unified LLM client** (OpenAI-compatible + Ollama ready)
- **Test mode / Production mode** as a first-class concept
- **Automatic token & cost tracking**
- **Simple RAG** (improved recursive chunking + in-memory vector store + query)
- **Lightweight ReAct agent** with tools
- **Structured output** (Pydantic models)
- **Conversation memory**
- **Streaming** (token by token)
- **Agent + Memory** integration
- Clean configuration via code or environment variables
- Built with Pydantic v2
- Extremely small surface area – easy to read and extend

> More advanced features (streaming, multi-agent…) can be added next.

## Installation

```bash
# From the project root
pip install -e ".[dev]"
```

## Quick Start

### Test mode (default – no API key required)

```python
from aetherkit import AetherClient

client = AetherClient()  # mode="test" by default

response = client.chat("What is the capital of France?")
print(response.content)
# → [TEST MODE] Mock response to: « What is the capital of France? » (model=gpt-4o-mini)

print(client.costs.summary())
```

### Production mode

```python
from aetherkit import AetherClient

client = AetherClient(
    mode="production",
    model="gpt-4o-mini",
    # api_key="sk-...",          # or export OPENAI_API_KEY=...
)

response = client.chat(
    "Explain quantum entanglement simply.",
    system="You are a physics teacher who explains clearly.",
)

print(response.content)
print(f"Tokens: {response.total_tokens}")
print(f"Cost  : ${response.cost_usd:.6f}")
print(client.costs.summary())
```

### Local models with Ollama

```python
client = AetherClient(
    mode="production",
    provider="ollama",
    model="llama3.2",
    base_url="http://localhost:11434/v1",
)

print(client.ask("Write a haiku about programming"))
```

### Lightweight Agent

\`\`\`python
from aetherkit import AetherClient, Agent, tool

@tool(description="Add two numbers")
def add(a: int, b: int) -> int:
    return a + b

client = AetherClient(mode="test")
agent = Agent(client, tools=[add])
result = agent.run("What is 15 + 27?")
print(result.answer)
\`\`\`

### Simple RAG

```python
from aetherkit import AetherClient, SimpleRAG

client = AetherClient(mode="test")
rag = SimpleRAG(client)

rag.add_documents([
    "Python is a programming language created by Guido van Rossum.",
    "FastAPI is a modern Python web framework for APIs.",
])

answer = rag.query("What is Python?")
print(answer.content)
```

## Configuration

You can configure via constructor or environment variables (`AETHER_` prefix):

| Setting       | Env variable          | Default        |
|---------------|-----------------------|----------------|
| mode          | `AETHER_MODE`         | `test`         |
| model         | `AETHER_MODEL`        | `gpt-4o-mini`  |
| api_key       | `AETHER_API_KEY` or `OPENAI_API_KEY` | –     |
| base_url      | `AETHER_BASE_URL`     | –              |
| temperature   | `AETHER_TEMPERATURE`  | `0.7`          |

## API Overview

```python
client = AetherClient(mode="test" | "production", model="...", ...)

# Main methods
response = client.chat(messages, system=None, model=None, temperature=None, ...)
text     = client.ask("Just give me the text")

# Response object
response.content
response.model
response.prompt_tokens
response.completion_tokens
response.total_tokens
response.cost_usd

# Cost tracking
client.costs.summary()
client.costs.total
client.costs.history
client.costs.reset()

# Introspection
client.info()
```

## Running examples & tests

```bash
# Examples
python examples/basic_usage.py
python examples/cost_tracking.py

# Tests
pytest
```

## Roadmap

- [x] Core client + test/prod modes + cost tracking
- [x] Simple RAG pipeline
- [ ] Structured output (Pydantic)
- [ ] Basic tool calling
- [ ] Light ReAct-style agent
- [ ] More providers & richer model catalog

## Philosophy

- Prefer clarity over magic
- Make the happy path extremely short
- Keep the source code readable
- Give the developer full visibility (tokens, costs, mode)

---

**AetherKit** – From idea to clean LLM code.
