Metadata-Version: 2.4
Name: analogaisdk
Version: 0.5.0
Summary: Minimal Python SDK for AnalogAI completion endpoints
Author: AnalogAI
Requires-Python: >=3.9,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: python-dotenv (>=1.0.1)
Requires-Dist: requests (>=2.31.0)
Description-Content-Type: text/markdown

# AnalogAI SDK (minimal)

Tiny Python client for the Deepthink OpenAI-compatible chat server
(`analogai.deepthink.chat`). It calls `POST {CHAT_BASE_URL}/v1/chat/completions`
— a stateful endpoint: memory tenancy is keyed by `user_id` + `agent_id`
(both created server-side on first use), Deepthink memory is retrieved per
turn, and messages are ingested in the background.

## Install

```bash
pip install analogaisdk
```

## Setup

Set environment variables in `.env`:
- `CHAT_BASE_URL` (default `https://cloud.analogai.net:8010`; set to `http://localhost:8010` for a local server)
- `ANALOGAI_API_KEY` (optional, if your server requires auth)
- `ANALOGAI_MODEL` (optional; server default is used when omitted)

## Usage

```python
from analogaisdk import AnalogAIClient

client = AnalogAIClient(agent_id="my-agent", user_id="my-user")

# Non-streaming (default).
print(client.generate_completion("are humans mortal?"))

# Streaming.
for chunk in client.generate_streaming_completion("are humans mortal?"):
    print(chunk, end="", flush=True)
```

### Working memory

Working memory (a string or list of strings) is appended to the LLM system
prompt alongside the Deepthink memory:

```python
client.generate_completion(
    "is Socrates mortal?",
    working_memory=["Socrates is a human"],
)
```

### Explicit messages and model

```python
client.generate_completion(
    messages=[
        {"role": "user", "content": "Say hello"},
    ],
    model="azure:gpt-4o-mini",  # optional, provider-prefixed
    temperature=0.2,
)
```

### Token usage and per-request USD cost

Every call surfaces the gateway's `usage` block (same field names as the
OpenAI API: `prompt_tokens`, `completion_tokens`, `total_tokens`) plus a
USD cost computed from a pricing table.

Built-in defaults price `gpt-5.4-mini` at **$0.75 per 1M prompt tokens**
and **$4.50 per 1M completion tokens**. Override or extend via the
`pricing=` constructor argument (values are USD per 1,000,000 tokens):

```python
client = AnalogAIClient(
    agent_id="my-agent",
    user_id="my-user",
    pricing={
        "gpt-5.4-mini": {"prompt": 0.75, "completion": 4.50},
        "azure:gpt-4o-mini": {"prompt": 0.15, "completion": 0.60},
    },
    print_usage=True,  # also prints a stderr summary per request
)
```

Non-streaming — the return value is still a `str`, plus usage/cost:

```python
result = client.generate_completion("are humans mortal?")
print(result)                    # assistant text
print(result.prompt_tokens)      # int
print(result.completion_tokens)  # int
print(result.total_tokens)       # int
print(result.cost_usd)           # float, USD
print(result.usage.as_dict())    # full breakdown incl. prompt/completion cost
```

Streaming — `.usage` is populated once the iterator is drained (the SDK
sends `stream_options={"include_usage": True}` so OpenAI-compatible
gateways emit a final chunk carrying the usage block):

```python
stream = client.generate_streaming_completion("are humans mortal?")
for chunk in stream:
    print(chunk, end="", flush=True)
print(stream.usage.prompt_tokens, stream.usage.completion_tokens, stream.usage.total_cost_usd)
```

The most recent usage is also cached on the client as `client.last_usage`.
Set `ANALOGAISDK_PRINT_USAGE=1` in the environment (or pass
`print_usage=True`) to print a one-line summary to stderr after every
request:

```
[analogaisdk] model=gpt-5.4-mini prompt_tokens=812 completion_tokens=134 total_tokens=946 cost_usd=0.001212
```

