Metadata-Version: 2.4
Name: analogaisdk
Version: 0.7.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.

The return types follow the **OpenAI Python SDK schema** exactly, so
migrating a script is a one-line client swap:

```python
completion = client.generate_completion("hi")
print(completion.choices[0].message.content)
print(completion.usage.prompt_tokens, completion.usage.completion_tokens)
```

## 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)

## Non-streaming

Returns a `ChatCompletion` matching the OpenAI response shape.

```python
from analogaisdk import AnalogAIClient

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

completion = client.generate_completion("are humans mortal?")
print(completion.choices[0].message.content)
print("prompt_tokens    =", completion.usage.prompt_tokens)
print("completion_tokens=", completion.usage.completion_tokens)
print("total_tokens     =", completion.usage.total_tokens)
```

## Streaming

Yields `ChatCompletionChunk` objects. The final chunk carries `usage`
with token counts (the SDK sends `stream_options={"include_usage": true}`
automatically).

```python
for chunk in client.generate_streaming_completion("are humans mortal?"):
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage is not None:
        print()
        print(chunk.usage.prompt_tokens, chunk.usage.completion_tokens)
```

## 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-5.4-mini",  # optional, provider-prefixed
    temperature=0.2,
)
```

## Response schema

- `ChatCompletion.id / object / created / model`
- `ChatCompletion.choices[i].index / .finish_reason`
- `ChatCompletion.choices[i].message.role / .content / .tool_calls`
- `ChatCompletion.usage.prompt_tokens / .completion_tokens / .total_tokens`
- `ChatCompletion.raw` — the parsed JSON body from the server, unchanged

For streaming:

- `ChatCompletionChunk.choices[i].delta.role / .content / .tool_calls`
- `ChatCompletionChunk.choices[i].finish_reason`
- `ChatCompletionChunk.usage` — `None` on intermediate chunks, populated
  on the final chunk when the server honours `stream_options.include_usage`.

