Metadata-Version: 2.5
Name: toskar
Version: 0.1.0
Summary: The official Python SDK for Toskar: local AI across your own computers.
Project-URL: Homepage, https://toskar.ai/developers
Project-URL: Repository, https://github.com/yeixio/toskar-sdks
Project-URL: Documentation, https://github.com/yeixio/toskar-sdks/blob/main/reference/python/README.md
Project-URL: Issues, https://github.com/yeixio/toskar-sdks/issues
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,llm,local-ai,sdk,toskar
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.6
Provides-Extra: anywhere
Requires-Dist: cryptography>=42; extra == 'anywhere'
Provides-Extra: dev
Requires-Dist: black==26.10.1; extra == 'dev'
Requires-Dist: cryptography==50.0.2; extra == 'dev'
Requires-Dist: datamodel-code-generator==0.86.0; extra == 'dev'
Requires-Dist: isort==8.0.1; extra == 'dev'
Requires-Dist: mypy==2.4.0; extra == 'dev'
Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
Requires-Dist: pytest==9.1.1; extra == 'dev'
Requires-Dist: respx==0.23.1; extra == 'dev'
Requires-Dist: zeroconf==0.151.5; extra == 'dev'
Provides-Extra: discovery
Requires-Dist: zeroconf>=0.130; extra == 'discovery'
Description-Content-Type: text/markdown

# toskar

The official Python SDK for [Toskar](https://toskar.ai), sync and async. It works on Python 3.10 and later.

```bash
pip install toskar
```

Every class, function, and type: [the reference](https://github.com/yeixio/toskar-sdks/blob/main/reference/python/README.md).

## Quick start

<!-- snippet: run -->
```python
from toskar import Toskar

# This computer's Toskar Core, at http://127.0.0.1:7331, needs no key.
# Elsewhere: Toskar("http://studio.local:7331", api_key="tk_…"),
# or set TOSKAR_URL and TOSKAR_API_KEY.
toskar = Toskar()

# Stream an answer as it's written.
for event in toskar.chat_stream("Plan a three-day trip to Juneau"):
    if event.type == "token":
        print(event.content, end="", flush=True)

# Or wait for the whole answer.
answer = toskar.chat("Summarize this in one line: …")
print(answer.content)
```

For asyncio, use `AsyncToskar`, which has the same methods, awaited:

<!-- snippet: run -->
```python
import asyncio
from toskar import AsyncToskar

async def main():
    async with AsyncToskar() as toskar:
        async for event in toskar.chat_stream("Hi"):
            if event.type == "token":
                print(event.content, end="", flush=True)

asyncio.run(main())
```

## Every route, typed

`toskar.api` has a method for each operation of the API, named after its `operationId`. Answers are Pydantic models from Toskar Core's spec:

```python
models = toskar.api.list_models()               # list[models.Model]
chat = toskar.api.create_conversation(body={"title": "Trip"})
messages = toskar.api.list_conversation_messages(chat.id)  # list[models.Message]
```

The models keep fields a newer Toskar Core adds, and accept values for documented fields that a newer Core adds too.

## Errors

Toskar answers errors with a stable code. The SDK raises them as `ToskarError`:

```python
from toskar import ErrorCodes, ToskarError

try:
    toskar.chat("Hi")
except ToskarError as err:
    if err.code == ErrorCodes.NO_MODEL_INSTALLED:
        ...  # Install one: toskar.api.install_model("qwen2.5-7b-q4")
```

A streamed answer that fails raises too, with the code Toskar sent. One that stops before it finishes raises `CONNECTION_LOST`.

## Events

```python
for event in toskar.events():
    print(event.type)  # such as model.download.progress or automation.completed
```

## Retries and timeouts

Safe requests (GET, HEAD, OPTIONS) that fail to connect, or that Toskar answers with 502, 503, or 504, are retried twice with backoff. A chat is never retried, since it could answer twice. Each request waits 60 seconds for its answer, and a streamed answer then runs for as long as it takes. Change these with `retries` and `timeout`.

## Pairing, as the Toskar apps do

An app can pair as a device, with the code **Connect a device** shows on the computer, instead of using an API key. It then reaches its computer at home and, when the computer has access from anywhere, directly or through its relay, always pinned to the computer's own certificate ([how it works](https://github.com/yeixio/toskar-core/blob/main/docs/connecting.md)).

```bash
pip install "toskar[anywhere]"   # cryptography, to open the computer's address record away from home
```

```python
from toskar import Device, Toskar, pair

# On the computer's network, with the code it shows:
device = pair("192.168.1.20:7331", "123456", "Kitchen tablet",
              confirm=lambda short: ask_the_person(short))  # such as 9B80-D9D9: does the computer show the same?
saved = device.to_dict()  # keep it as a password is kept: its key and route are secrets

toskar = Toskar(device=Device.from_dict(saved))
models = toskar.api.list_models()
print(toskar.path)  # home, direct, or relay
```

`apair` and `AsyncToskar(device=...)` do the same for asyncio. Every connection checks the computer's certificate in the TLS handshake, before anything is sent. A different certificate raises `PinMismatch`, and is never accepted on its own: pair again to trust a new one. Away from home, the client opens the computer's sealed address record from its relay, tries its direct ways in at once and the relay a second later, and keeps the first that answers. `toskar.reconnect()` chooses again, as after the network changes. A device key reaches the routes a device needs. Scripts and servers that need the rest use a key from API Access.

## Find computers on the network

Computers running Toskar announce themselves on the home network (mDNS, `_localai._tcp`). `discover` lists them, so a person can pick one instead of typing an address. It needs the `discovery` extra (zeroconf, LGPL-2.1, imported only when you call it):

```sh
pip install "toskar[discovery]"
```

```python
from toskar import discover

for c in discover(timeout=3.0):
    print(c.name, c.address)
```

Pair with `c.address`. When `c.on_network` is false, the computer answers only on itself: tell the person to turn on Connect a device there, rather than that it's unreachable. A computer can advertise addresses this device can't reach, such as a container network's; `address` is the first one that answers, and `addresses` has them all.
