thinai 0.1.0__tar.gz

thinai-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

thinai-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `Thinai` (sync) and `AsyncThinai` (asyncio) clients for the phone's `/api/*` routes: `chat`, `generate`, `embed`, `models`, `running`, `show`.
+- NDJSON streaming, tool calls, and generation metrics (tokens per second).
+- LAN discovery with `discover()` / `adiscover()`, which scan the local /24 for the Thinai fingerprint. `Thinai()` connects automatically.
+- `client.openai()`, which returns an OpenAI SDK client pointed at the phone's `/v1` API.
+- `thinai` command line: `discover`, `models`, `chat`.

thinai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thinai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thinai-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: thinai
+Version: 0.1.0
+Summary: Python SDK for Thinai: discover and use LLMs running on an Android phone over your local network.
+Project-URL: Homepage, https://github.com/ATmega-Software-Technologies/thinai-python-sdk
+Project-URL: Repository, https://github.com/ATmega-Software-Technologies/thinai-python-sdk
+Project-URL: Issues, https://github.com/ATmega-Software-Technologies/thinai-python-sdk/issues
+Project-URL: Changelog, https://github.com/ATmega-Software-Technologies/thinai-python-sdk/blob/main/CHANGELOG.md
+Project-URL: Thinai app, https://play.google.com/store/apps/details?id=in.atmega.thinai
+Author-email: Thinai <dev.atmega@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: android,gguf,lan,llm,local-llm,offline,ollama,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# thinai
+
+Python SDK for **[Thinai](https://play.google.com/store/apps/details?id=in.atmega.thinai&hl=en_IN)**, the Android app that runs LLMs offline on your phone and serves them to your Wi-Fi.
+
+Point your laptop at the phone and use its models from Python. There are no API keys and no cloud, and your data stays on your network.
+
+```bash
+pip install thinai
+```
+
+```python
+from thinai import Thinai
+
+client = Thinai()  # finds the phone on your Wi-Fi
+print(client.chat("Explain RAG in one sentence.").content)
+```
+
+## Set up the phone
+
+1. Open Thinai, download a model, and go to the **Server** tab.
+2. Press **Start**.
+3. Turn on **Share on local network**.
+4. Keep the computer on the same Wi-Fi. The app shows the address, for example `http://192.168.1.36:11434`.
+
+## Connecting
+
+```python
+from thinai import Thinai, discover
+
+client = Thinai()                           # scan the local /24 for Thinai
+client = Thinai("192.168.1.36")             # known IP
+client = Thinai("192.168.1.36", port=8080)  # custom port from the app
+client = Thinai("http://192.168.1.36:11434", model="gemma-3-270m-it-q8_0")
+
+for server in discover():                   # every phone on the network
+    print(server.base_url, server.models)
+```
+
+When you don't pass `host`, the client looks in this order:
+
+1. `$THINAI_HOST`
+2. a Thinai app on this machine
+3. a scan of your local subnet
+
+The app doesn't advertise itself on the network yet. The scan probes `GET /` on each address and matches the `Thinai is running` reply, which usually takes 1–2 seconds. Pass `discover(subnets=["10.0.0.0/24"])` if your network isn't a /24.
+
+## Chat
+
+```python
+from thinai import Message
+
+response = client.chat(
+    [Message.system("You are concise."), Message.user("What is a GGUF file?")],
+    temperature=0.3,
+    num_ctx=4096,      # clamped by the phone to client.show().context_cap
+    num_predict=256,
+)
+print(response.content, response.done_reason)
+print(f"{response.metrics.tokens_per_second:.1f} tok/s on the phone")
+```
+
+To stream the reply as it's generated:
+
+```python
+for chunk in client.chat("Write a haiku about the monsoon.", stream=True):
+    print(chunk.content, end="", flush=True)
+```
+
+If you leave out `model`, the client uses the model already loaded on the phone. Swapping models on a phone is slow.
+
+Tool calling uses OpenAI-format tool definitions:
+
+```python
+tools = [{"type": "function", "function": {
+    "name": "get_weather",
+    "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
+}}]
+response = client.chat("Weather in Chennai?", tools=tools)
+for call in response.tool_calls:
+    print(call.name, call.arguments)
+```
+
+## Generate, embed, models
+
+```python
+client.generate("Once upon a time", num_predict=50).response
+client.embed(["hello", "world"], model="<embedding-model-id>").embeddings  # needs an embedding model
+client.models()          # installed models
+client.running()         # loaded model
+client.show()            # architecture, trained context_length, context_cap
+```
+
+## Async
+
+```python
+import asyncio
+from thinai import AsyncThinai
+
+async def main():
+    async with AsyncThinai() as client:
+        async for chunk in await client.chat("Hi!", stream=True):
+            print(chunk.content, end="")
+
+asyncio.run(main())
+```
+
+## OpenAI-compatible API
+
+The phone also serves `/v1/chat/completions`, `/v1/embeddings` and `/v1/models`. To use them through the official client:
+
+```bash
+pip install 'thinai[openai]'
+```
+
+```python
+oai = Thinai().openai()
+oai.chat.completions.create(model="lfm2.5-350m-q8_0", messages=[{"role": "user", "content": "hi"}])
+```
+
+This means LangChain, LlamaIndex and other OpenAI-compatible tools work too. Give them `client.base_url + "/v1"` as the base URL.
+
+## Command line
+
+```bash
+thinai discover
+thinai models --host 192.168.1.36
+thinai chat "What is the capital of Tamil Nadu?"
+```
+
+## Errors
+
+| Exception | When |
+| --- | --- |
+| `DiscoveryError` | No phone found on the network |
+| `APIConnectionError` / `APITimeoutError` | Phone unreachable (server stopped, sharing off, different Wi-Fi) |
+| `NotFoundError` | Unknown model id |
+| `BadRequestError` | Invalid request, such as embedding with a chat model |
+| `ServerError` | Inference failed on the phone |
+| `StreamError` | Server reported an error mid-stream |
+
+All of them inherit from `thinai.ThinaiError`.
+
+## Good to know
+
+- **No authentication.** Anyone on the same Wi-Fi can use the phone's models while sharing is on. Only enable it on networks you trust.
+- **One request at a time.** The phone processes requests in a queue, so concurrent calls wait. Cancelling a request on the client doesn't stop generation on the phone.
+- **`/api/chat` and `/api/generate` can return engine errors as text.** For example, "request exceeds the available context size" may arrive as the reply content instead of an HTTP error.
+- **`num_ctx` only works on `/api/*` routes.** The OpenAI-compatible `/v1/chat/completions` always uses the context size set in the app.
+
+## Development
+
+```bash
+uv sync
+uv run pytest                                    # unit tests (offline)
+THINAI_HOST=192.168.1.36 uv run pytest -m live   # against a real phone
+uv run ruff check . && uv run mypy
+uv build && uv run twine check dist/*
+```
+
+## License
+
+MIT

thinai-0.1.0/README.md

@@ -0,0 +1,162 @@
+# thinai
+
+Python SDK for **[Thinai](https://play.google.com/store/apps/details?id=in.atmega.thinai&hl=en_IN)**, the Android app that runs LLMs offline on your phone and serves them to your Wi-Fi.
+
+Point your laptop at the phone and use its models from Python. There are no API keys and no cloud, and your data stays on your network.
+
+```bash
+pip install thinai
+```
+
+```python
+from thinai import Thinai
+
+client = Thinai()  # finds the phone on your Wi-Fi
+print(client.chat("Explain RAG in one sentence.").content)
+```
+
+## Set up the phone
+
+1. Open Thinai, download a model, and go to the **Server** tab.
+2. Press **Start**.
+3. Turn on **Share on local network**.
+4. Keep the computer on the same Wi-Fi. The app shows the address, for example `http://192.168.1.36:11434`.
+
+## Connecting
+
+```python
+from thinai import Thinai, discover
+
+client = Thinai()                           # scan the local /24 for Thinai
+client = Thinai("192.168.1.36")             # known IP
+client = Thinai("192.168.1.36", port=8080)  # custom port from the app
+client = Thinai("http://192.168.1.36:11434", model="gemma-3-270m-it-q8_0")
+
+for server in discover():                   # every phone on the network
+    print(server.base_url, server.models)
+```
+
+When you don't pass `host`, the client looks in this order:
+
+1. `$THINAI_HOST`
+2. a Thinai app on this machine
+3. a scan of your local subnet
+
+The app doesn't advertise itself on the network yet. The scan probes `GET /` on each address and matches the `Thinai is running` reply, which usually takes 1–2 seconds. Pass `discover(subnets=["10.0.0.0/24"])` if your network isn't a /24.
+
+## Chat
+
+```python
+from thinai import Message
+
+response = client.chat(
+    [Message.system("You are concise."), Message.user("What is a GGUF file?")],
+    temperature=0.3,
+    num_ctx=4096,      # clamped by the phone to client.show().context_cap
+    num_predict=256,
+)
+print(response.content, response.done_reason)
+print(f"{response.metrics.tokens_per_second:.1f} tok/s on the phone")
+```
+
+To stream the reply as it's generated:
+
+```python
+for chunk in client.chat("Write a haiku about the monsoon.", stream=True):
+    print(chunk.content, end="", flush=True)
+```
+
+If you leave out `model`, the client uses the model already loaded on the phone. Swapping models on a phone is slow.
+
+Tool calling uses OpenAI-format tool definitions:
+
+```python
+tools = [{"type": "function", "function": {
+    "name": "get_weather",
+    "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
+}}]
+response = client.chat("Weather in Chennai?", tools=tools)
+for call in response.tool_calls:
+    print(call.name, call.arguments)
+```
+
+## Generate, embed, models
+
+```python
+client.generate("Once upon a time", num_predict=50).response
+client.embed(["hello", "world"], model="<embedding-model-id>").embeddings  # needs an embedding model
+client.models()          # installed models
+client.running()         # loaded model
+client.show()            # architecture, trained context_length, context_cap
+```
+
+## Async
+
+```python
+import asyncio
+from thinai import AsyncThinai
+
+async def main():
+    async with AsyncThinai() as client:
+        async for chunk in await client.chat("Hi!", stream=True):
+            print(chunk.content, end="")
+
+asyncio.run(main())
+```
+
+## OpenAI-compatible API
+
+The phone also serves `/v1/chat/completions`, `/v1/embeddings` and `/v1/models`. To use them through the official client:
+
+```bash
+pip install 'thinai[openai]'
+```
+
+```python
+oai = Thinai().openai()
+oai.chat.completions.create(model="lfm2.5-350m-q8_0", messages=[{"role": "user", "content": "hi"}])
+```
+
+This means LangChain, LlamaIndex and other OpenAI-compatible tools work too. Give them `client.base_url + "/v1"` as the base URL.
+
+## Command line
+
+```bash
+thinai discover
+thinai models --host 192.168.1.36
+thinai chat "What is the capital of Tamil Nadu?"
+```
+
+## Errors
+
+| Exception | When |
+| --- | --- |
+| `DiscoveryError` | No phone found on the network |
+| `APIConnectionError` / `APITimeoutError` | Phone unreachable (server stopped, sharing off, different Wi-Fi) |
+| `NotFoundError` | Unknown model id |
+| `BadRequestError` | Invalid request, such as embedding with a chat model |
+| `ServerError` | Inference failed on the phone |
+| `StreamError` | Server reported an error mid-stream |
+
+All of them inherit from `thinai.ThinaiError`.
+
+## Good to know
+
+- **No authentication.** Anyone on the same Wi-Fi can use the phone's models while sharing is on. Only enable it on networks you trust.
+- **One request at a time.** The phone processes requests in a queue, so concurrent calls wait. Cancelling a request on the client doesn't stop generation on the phone.
+- **`/api/chat` and `/api/generate` can return engine errors as text.** For example, "request exceeds the available context size" may arrive as the reply content instead of an HTTP error.
+- **`num_ctx` only works on `/api/*` routes.** The OpenAI-compatible `/v1/chat/completions` always uses the context size set in the app.
+
+## Development
+
+```bash
+uv sync
+uv run pytest                                    # unit tests (offline)
+THINAI_HOST=192.168.1.36 uv run pytest -m live   # against a real phone
+uv run ruff check . && uv run mypy
+uv build && uv run twine check dist/*
+```
+
+## License
+
+MIT

thinai-0.1.0/examples/openai_compat.py

@@ -0,0 +1,14 @@
+"""Use the official OpenAI SDK against the phone. Requires: pip install 'thinai[openai]'."""
+
+from thinai import Thinai
+
+client = Thinai()
+oai = client.openai()
+
+model = client.running()[0].name
+completion = oai.chat.completions.create(
+    model=model,
+    messages=[{"role": "user", "content": "Say hello from my phone."}],
+    max_tokens=40,
+)
+print(completion.choices[0].message.content)

thinai-0.1.0/examples/quickstart.py

@@ -0,0 +1,18 @@
+"""Find the phone, list its models, and ask a question.
+
+python examples/quickstart.py                 # auto-discover
+THINAI_HOST=192.168.1.36 python examples/quickstart.py
+"""
+
+from thinai import Thinai
+
+with Thinai() as client:
+    print(f"Connected to {client.base_url}")
+    loaded = {m.name for m in client.running()}
+    for model in client.models():
+        print(f"  {'*' if model.name in loaded else ' '} {model.name}")
+
+    response = client.chat("In one sentence, why run an LLM on a phone?", num_predict=80)
+    print("\n" + response.content.strip())
+    if response.metrics and response.metrics.tokens_per_second:
+        print(f"\n[{response.metrics.tokens_per_second:.1f} tokens/s on the phone]")

thinai-0.1.0/examples/streaming.py

@@ -0,0 +1,35 @@
+"""A tiny terminal chat that streams replies from the phone, sync and async."""
+
+import asyncio
+
+from thinai import AsyncThinai, Thinai
+
+
+def sync_chat() -> None:
+    client = Thinai()
+    history = [{"role": "system", "content": "You are a helpful, concise assistant."}]
+    print(f"Chatting with {client.base_url} (empty line to quit)")
+    while True:
+        prompt = input("\nyou> ").strip()
+        if not prompt:
+            break
+        history.append({"role": "user", "content": prompt})
+        reply = ""
+        print("ai> ", end="")
+        for chunk in client.chat(history, stream=True):
+            print(chunk.content, end="", flush=True)
+            reply += chunk.content
+        print()
+        history.append({"role": "assistant", "content": reply})
+
+
+async def async_once() -> None:
+    async with AsyncThinai() as client:
+        async for chunk in await client.chat("Give me three Tamil greetings.", stream=True):
+            print(chunk.content, end="", flush=True)
+        print()
+
+
+if __name__ == "__main__":
+    asyncio.run(async_once())
+    sync_chat()

thinai-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "thinai"
+dynamic = ["version"]
+description = "Python SDK for Thinai: discover and use LLMs running on an Android phone over your local network."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Thinai", email = "dev.atmega@gmail.com" }]
+keywords = ["llm", "local-llm", "android", "ollama", "offline", "gguf", "lan", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+
+[project.scripts]
+thinai = "thinai.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/ATmega-Software-Technologies/thinai-python-sdk"
+Repository = "https://github.com/ATmega-Software-Technologies/thinai-python-sdk"
+Issues = "https://github.com/ATmega-Software-Technologies/thinai-python-sdk/issues"
+Changelog = "https://github.com/ATmega-Software-Technologies/thinai-python-sdk/blob/main/CHANGELOG.md"
+"Thinai app" = "https://play.google.com/store/apps/details?id=in.atmega.thinai"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "openai>=1.0",
+    "twine>=5",
+]
+
+[tool.hatch.version]
+path = "src/thinai/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/thinai"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/thinai", "tests", "examples", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = "-m 'not live'"
+markers = ["live: needs a running Thinai app on the local network (run with -m live)"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]

thinai-0.1.0/src/thinai/__init__.py

@@ -0,0 +1,71 @@
+"""Python SDK for Thinai: LLMs running on an Android phone, served over your Wi-Fi.
+
+>>> from thinai import Thinai
+>>> client = Thinai()            # finds the phone on the local network
+>>> print(client.chat("Hello!").content)
+"""
+
+from ._base import DEFAULT_PORT
+from ._version import __version__
+from .async_client import AsyncThinai
+from .client import Thinai
+from .discovery import adiscover, afind_server, discover, find_server
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    DiscoveryError,
+    NotFoundError,
+    ServerError,
+    StreamError,
+    ThinaiError,
+)
+from .types import (
+    ChatChunk,
+    ChatResponse,
+    EmbedResponse,
+    GenerateChunk,
+    GenerateResponse,
+    Message,
+    Metrics,
+    Model,
+    ModelInfo,
+    RunningModel,
+    Server,
+    ToolCall,
+)
+
+__all__ = [
+    "DEFAULT_PORT",
+    "__version__",
+    "Thinai",
+    "AsyncThinai",
+    "discover",
+    "adiscover",
+    "find_server",
+    "afind_server",
+    "ThinaiError",
+    "DiscoveryError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ServerError",
+    "StreamError",
+    "ChatChunk",
+    "ChatResponse",
+    "EmbedResponse",
+    "GenerateChunk",
+    "GenerateResponse",
+    "Message",
+    "Metrics",
+    "Model",
+    "ModelInfo",
+    "RunningModel",
+    "Server",
+    "ToolCall",
+]