Metadata-Version: 2.4
Name: slimx
Version: 0.5.1
Summary: A slim, intuitive, lightweight Python library for calling LLMs (high-level + low-level) with multi-provider support.
Author: Amjad Yousef Majid
License: MIT License
        
        Copyright (c) 2026 SlimX
        
        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.
License-File: LICENSE
Keywords: anthropic,gemini,llm,ollama,openai,sdk,streaming,tools
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: pyright>=1.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Description-Content-Type: text/markdown

# SlimX (`slimx`) — v0.5.1

SlimX is a tiny, inspectable LLM runtime for building vendor-neutral AI software across cloud and local models.

It is designed around **two clearly separated APIs**:

* **High-level API** (`slimx`) — “1-minute productivity”: `llm(...)`, `.stream(...)`, `.json(...)`, tools, retries.
* **Low-level API** (`slimx.low`) — “systems builder primitives”: explicit `Client`, `ChatRequest`, `Message`, provider registry, middleware.

SlimX supports **multiple providers** — OpenAI, Anthropic, Ollama, and Google Gemini — plus **provider plugins** for third-party providers without modifying core.

---

## Install

### For users

Create a new project and install SlimX:

```bash
uv init my-project
cd my-project
uv add slimx
```

Run Python through `uv` so it uses the project virtual environment:

```bash
uv run python
```

Or install with pip:

```bash
pip install slimx
```

### For contributors

```bash
git clone https://github.com/slimx-ai/slimx.git
cd slimx
uv sync --all-extras
uv run pytest -q
```

> `uv sync` reads `pyproject.toml` and `uv.lock` when present.
> Keeping `uv.lock` committed helps contributors and CI use a reproducible development environment.

---

## Supported providers

| Provider      |       Prefix | Environment variable                 | Notes                                            |
| ------------- | -----------: | ------------------------------------ | ------------------------------------------------ |
| OpenAI        |    `openai:` | `OPENAI_API_KEY`                     | Default provider when no prefix is given         |
| Google Gemini |    `google:` | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | Supports chat, streaming, JSON output, and tools |
| Anthropic     | `anthropic:` | `ANTHROPIC_API_KEY`                  | Claude-compatible API                            |
| Ollama        |    `ollama:` | optional `OLLAMA_BASE_URL`           | Local models through Ollama                      |

---

## Configure providers

### OpenAI

```bash
export OPENAI_API_KEY="..."
# optional:
export OPENAI_BASE_URL="https://api.openai.com/v1"
```

### Google Gemini

```bash
export GOOGLE_API_KEY="..."
# or:
export GEMINI_API_KEY="..."

# optional:
export GOOGLE_BASE_URL="https://generativelanguage.googleapis.com/v1beta"
```

### Anthropic

```bash
export ANTHROPIC_API_KEY="..."
# optional:
export ANTHROPIC_BASE_URL="https://api.anthropic.com"
export ANTHROPIC_VERSION="2023-06-01"
```

### Ollama local models

```bash
export OLLAMA_BASE_URL="http://localhost:11434"
```

For Ollama, make sure the server is running and the model is available:

```bash
ollama serve
```

In another terminal:

```bash
ollama pull llama3.2:3b
ollama list
```

---

## Quickstart

### OpenAI

```python
from slimx import llm

m = llm("openai:gpt-4.1-nano", temperature=0.2)
res = m("Write a haiku about fog and streetlights.")

print(res.text)
```

### Google Gemini

```python
from slimx import llm

m = llm("google:gemini-3.5-flash", temperature=0.2)
res = m("Write a haiku about small, inspectable AI software.")

print(res.text)
```

### Ollama local model

```python
from slimx import llm

m = llm("ollama:llama3.2:3b", temperature=0.2, timeout=120)
res = m("Explain why small libraries are easier to inspect.")

print(res.text)
```

## Response structure

Calling a SlimX model returns a `Result` object.

```python
from slimx import llm

m = llm("ollama:llama3.2:3b", timeout=120)
res = m("Explain why small libraries are easier to inspect.")

print(res.text)
```

A `Result` contains:

```python
Result(
    text="...",          # Normalized assistant text
    raw={...},           # Raw provider response
    usage=Usage(...),    # Token usage when available
    tool_calls=[],       # Tool/function calls requested by the model
    data=None,           # Parsed structured output, used by .json(...)
    trace={...},         # Runtime metadata: provider, model, latency, retries, tools
)
```

Most applications should use:

```python
print(res.text)
```

Use `res.raw` when you need provider-specific details, and `res.trace` when you want runtime diagnostics such as provider name, model name, elapsed time, retries, and tool-call count.

---


## Response structure

Calling a SlimX model returns a `Result` object.

```python
from slimx import llm

m = llm("ollama:llama3.2:3b", timeout=120)
res = m("Explain why small libraries are easier to inspect.")

print(res.text)
```

A `Result` contains:

```python
Result(
    text="...",          # Normalized assistant text
    raw={...},           # Raw provider response
    usage=Usage(...),    # Token usage when available
    tool_calls=[],       # Tool/function calls requested by the model
    data=None,           # Parsed structured output, used by .json(...)
    trace={...},         # Runtime metadata: provider, model, latency, retries, tools
)
```

Most applications should use:

```python
print(res.text)
```

Use `res.raw` when you need provider-specific details, and `res.trace` when you want runtime diagnostics such as provider name, model name, elapsed time, retries, and tool-call count.



## Streaming

```python
from slimx import llm

m = llm("google:gemini-3.5-flash", temperature=0.2)

for ev in m.stream("Tell a short story in 5 lines."):
    if ev.type == "text_delta":
        print(ev.text, end="", flush=True)

print()
```

---

## Tools

SlimX tools are provider-neutral. The same `@tool` interface can be used across providers that support tool/function calling.

```python
from slimx import llm, tool


@tool
def add(a: int, b: int) -> int:
    "Add two integers."
    return a + b


m = llm("google:gemini-3.5-flash", tools=[add], tool_runtime="auto")
res = m("What is 12 + 30?")

print(res.text)
```

---

## Structured output

SlimX can parse structured JSON output into a dataclass.

```python
from dataclasses import dataclass

from slimx import llm


@dataclass
class City:
    name: str
    country: str


m = llm("google:gemini-3.5-flash")
res = m.json("Paris is in France.", schema=City)

print(res.data)
```

---

## Low-level API

Use the low-level API when you want explicit control over messages, requests, clients, and providers.

```python
from slimx import Message
from slimx.low import ChatRequest, Client
from slimx.providers import get_provider

provider = get_provider("google")
client = Client(provider, timeout=30, retries=2)

req = ChatRequest(
    model="gemini-3.5-flash",
    messages=[Message.user("Explain provider-neutral LLM clients in one paragraph.")],
    temperature=0.2,
)

res = client.chat(req)

print(res.text)
print(res.trace)
```

---

## Provider plugins

SlimX supports third-party provider plugins through the `slimx.providers` entry point group.

Built-in providers are registered lazily, so importing `slimx` does not load provider modules or require API keys.

---

## Troubleshooting

### `ModuleNotFoundError: No module named 'slimx'`

If you installed with `uv add slimx`, run Python through uv:

```bash
uv run python
```

Or activate the virtual environment first:

```bash
source .venv/bin/activate
python
```

### Ollama model not found

Check which models are installed:

```bash
ollama list
```

Pull a model before using it:

```bash
ollama pull llama3.2:3b
```

Then use the exact model name:

```python
m = llm("ollama:llama3.2:3b", timeout=120)
```

### Ollama server not running

Start Ollama:

```bash
ollama serve
```

Then retry your SlimX script.

---

## Development

Run the full validation suite before opening a pull request or tagging a release:

```bash
uv sync --all-extras
uv run ruff check .
uv run pyright
uv run pytest -q
uv run python -m build
```

---

## Repo automation

This repository includes GitHub Actions for:

* CI (`.github/workflows/ci.yml`)
* Docs deployment to GitHub Pages (`docs.yml`)

See `docs/` for more detailed documentation.
