Metadata-Version: 2.4
Name: talkory
Version: 0.0.2
Summary: Talkory — AI answer comparison and consensus platform. Official Python SDK.
Project-URL: Homepage, https://talkory.ai
Project-URL: Documentation, https://www.talkory.ai/docs/api
Project-URL: Repository, https://github.com/talkory-ai/talkory-python-pip
Author-email: Abhishek Chand <abhishekchand62@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,comparison,consensus,llm,multi-llm,talkory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# talkory

Official Python SDK for [Talkory.ai](https://talkory.ai) — ask once, hear from five LLMs (GPT, Claude, Gemini, Grok, Perplexity), get a consensus answer.

```bash
pip install talkory
```

## Quickstart

Create an API key at [app.talkory.ai](https://app.talkory.ai) (Settings → API Keys), then:

```python
from talkory import Talkory

client = Talkory()  # reads TALKORY_API_KEY from the environment

result = client.queries.run("Best commuter motorcycles under $5000?")
print(result.consensus)       # synthesized consensus answer
print(result.common_answer)   # what the models agreed on
print(result.confidence)      # 0-100
print(result.charged)         # USD charged for this run
```

`queries.run()` blocks until the run finishes (can take a few minutes — the read timeout defaults to 600s per the API docs).

## Fire-and-forget + poll

```python
run = client.queries.create("Compare Python web frameworks in 2026")
result = client.queries.wait(run.id)      # polls with gentle backoff
```

## Choosing models

```python
models = client.models.list()             # free
result = client.queries.run(
    "Is a heat pump worth it in Delhi?",
    models=["gpt", "claude"],             # subset (max 10)
    recursive=True,                       # round-2 self-review before consensus
    country="in",                         # localization
)
```

## Free endpoints

```python
client.health.check()                     # LLM provider health
client.wallet.get()                       # balance
client.usage.get(from_="2026-06-01")      # usage stats for this key
client.queries.retrieve(query_id)         # past result by id
for q in client.queries.list(limit=50):   # auto-paginating history
    print(q.id, q.prompt, q.charged)
```

## Deferred consensus

```python
result = client.queries.run("...", consensus=False)   # cheaper
later = client.queries.consensus(result.id)           # idempotent; cached re-calls charge $0
```

## Errors

Every documented API error maps to a typed exception carrying `code`, `status`, `message`, and `request_id` (quote the `request_id` in support tickets):

```python
from talkory import RateLimitError, InsufficientBalanceError, TalkoryError

try:
    result = client.queries.run("...")
except RateLimitError as e:
    time.sleep(e.retry_after or 30)
except InsufficientBalanceError:
    ...  # top up at app.talkory.ai
except TalkoryError as e:
    print(e.code, e.request_id)
```

## Wallet safety

The SDK **never auto-retries paid POST requests**. If a connection drops after a run starts, the run still completes (and charges) server-side — retrying blindly would double-spend your wallet. On timeout/disconnect, check `client.queries.retrieve(id)` first. Free idempotent GETs *are* retried automatically on 429/500/503, honoring `Retry-After`.

## Security

- Key resolution: explicit `api_key=` argument → `TALKORY_API_KEY` env var. The SDK never reads or writes keys to disk.
- Keys are redacted everywhere they could leak: `repr()`, exception messages, logs show `tk_live_***a1b2` at most.
- HTTPS is enforced; a plain-HTTP `base_url` is refused unless you explicitly pass `allow_insecure=True` (local testing only).
- Zero telemetry: the SDK makes no network calls other than the API requests you invoke. The only metadata sent is `User-Agent: talkory-python/{version} python/{py_version}`.
- Never embed keys in frontend/browser code — call Talkory from your backend.

See [SECURITY.md](SECURITY.md) for vulnerability reporting.

## Requirements

Python 3.9+ · [httpx](https://www.python-httpx.org/) · [pydantic v2](https://docs.pydantic.dev/). Fully typed (`py.typed`).

## Links

- [API reference](https://www.talkory.ai/docs/api)
- [Dashboard / API keys](https://app.talkory.ai)
- [Changelog](CHANGELOG.md)

## License

MIT
