slimx 0.5.0__tar.gz

slimx-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+      - run: uv run pyright
+      - run: uv run pytest -q
+      - run: uv run python -m build

slimx-0.5.0/.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Deploy Docs (MkDocs)
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install deps (docs extras)
+        run: uv sync --locked --all-extras
+
+      - name: Build site
+        run: uv run python -m mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

slimx-0.5.0/.gitignore

@@ -0,0 +1,120 @@
+# =========================
+# Python
+# =========================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Bytecode / compiled / optimized
+*.pyd
+*.pyo
+
+# =========================
+# Virtual environments (uv / venv)
+# =========================
+.venv/
+.venv_test/
+venv/
+ENV/
+env/
+
+# =========================
+# Environment variables / secrets
+# =========================
+.env
+.env.*
+!.env.example
+*.key
+*.pem
+
+# =========================
+# Packaging / build artifacts
+# =========================
+build/
+dist/
+*.egg-info/
+.eggs/
+pip-wheel-metadata/
+wheelhouse/
+
+# PEP 582 (if someone uses it)
+__pypackages__/
+
+# =========================
+# Test / coverage / profiling
+# =========================
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pyre/
+.dmypy.json
+.prof
+.profraw
+
+# =========================
+# Type checkers / linters / formatters
+# =========================
+.mypy_cache/
+.ruff_cache/
+.pyright/
+.pytype/
+.pylint.d/
+
+# =========================
+# IDEs / editors
+# =========================
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+
+# =========================
+# Jupyter / notebooks
+# =========================
+.ipynb_checkpoints/
+
+# =========================
+# OS files
+# =========================
+.DS_Store
+.DS_Store?
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# =========================
+# MkDocs / docs build output
+# =========================
+site/
+
+# =========================
+# Logs and internal docs
+# =========================
+*.log
+internal_docs/
+
+# =========================
+# Local caches / temp
+# =========================
+.cache/
+.tmp/
+tmp/
+*.tmp
+*.swp
+*.swo
+
+# =========================
+# Node (in case mkdocs-material or tooling pulls nodeenv)
+# =========================
+node_modules/
+
+# =========================
+# Local overrides
+# =========================
+*.local

slimx-0.5.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## v0.4.0 (2026-01-03)
+
+- Multi-provider support (OpenAI, Anthropic, Ollama)
+- Provider registry + plugin loading via entry points
+- Sync + async clients and streaming
+- Tool calling + optional auto tool loop (sync + async)
+- Structured JSON output parsing (dataclasses)
+- MkDocs docs scaffold + GitHub Actions CI/docs/publish
+
+## v0.5.0 (2026-06-03)
+
+- Added built-in Google Gemini provider support.
+- Added synchronous and asynchronous Google provider implementations.
+- Added Google Gemini streaming support.
+- Added Google Gemini structured JSON output mapping.
+- Added Google Gemini tool/function-call mapping.
+- Added Google provider tests with fake HTTP clients.
+- Added Google Gemini quickstart example.
+- Updated provider documentation to include Google Gemini.

slimx-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing to SlimX
+
+## Dev setup (uv)
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check .
+uv run pyright
+```

slimx-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+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.

slimx-0.5.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: slimx
+Version: 0.5.0
+Summary: A slim, intuitive, lightweight Python library for calling LLMs (high-level + low-level) with multi-provider support.
+Author: SlimX Contributors
+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,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.0
+
+SlimX is a **slim, intuitive, lightweight** Python library for calling LLMs and building LLM systems.
+
+It is intentionally 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 also supports **multiple providers** (OpenAI, Anthropic, Ollama, Google) and **provider plugins** (3rd-party providers without modifying core).
+
+---
+
+## Install (using `uv`)
+
+On Debian/Ubuntu you may hit `externally-managed-environment` (PEP 668) if you try to use system `pip`.
+Use **uv**, which manages an isolated environment cleanly.
+
+### Option A — contributors / repo setup (recommended)
+```bash
+git clone https://github.com/slimx-ai/slimx.git
+cd slimx
+uv sync --all-extras
+```
+
+### Option B — quick test from an extracted zip
+```bash
+unzip slimx_v0_4.zip
+cd slimx_v0_4
+uv sync --all-extras
+uv run python examples/quickstart_openai.py
+```
+
+> `uv sync` reads `pyproject.toml` and (optionally) `uv.lock`.
+> If `uv.lock` is present and committed, installs are reproducible.
+
+---
+
+## 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)
+```bash
+export OLLAMA_BASE_URL="http://localhost:11434"
+```
+
+---
+
+## Quickstart (high-level)
+
+```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)
+```
+
+```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)
+```
+
+Streaming:
+
+```python
+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 (auto-loop):
+
+```python
+from slimx import llm, tool
+
+@tool
+def add(a: int, b: int) -> int:
+    "Add two integers."
+    return a + b
+
+m = llm("openai:gpt-4.1-nano", tools=[add], tool_runtime="auto")
+print(m("What is 12 + 30?").text)
+```
+
+Structured output:
+
+```python
+from dataclasses import dataclass
+from slimx import llm
+
+@dataclass
+class City:
+    name: str
+    country: str
+
+m = llm("openai:gpt-4.1-nano")
+res = m.json("Paris is in France.", schema=City)
+print(res.data)
+```
+
+---
+
+## Repo automation
+
+This bundle includes GitHub Actions:
+- CI (`.github/workflows/ci.yml`)
+- Docs deploy to GitHub Pages (`docs.yml`)
+
+See `README.md` and `docs/` for details.

slimx-0.5.0/README.md

@@ -0,0 +1,138 @@
+# SlimX (`slimx`) — v0.5.0
+
+SlimX is a **slim, intuitive, lightweight** Python library for calling LLMs and building LLM systems.
+
+It is intentionally 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 also supports **multiple providers** (OpenAI, Anthropic, Ollama, Google) and **provider plugins** (3rd-party providers without modifying core).
+
+---
+
+## Install (using `uv`)
+
+On Debian/Ubuntu you may hit `externally-managed-environment` (PEP 668) if you try to use system `pip`.
+Use **uv**, which manages an isolated environment cleanly.
+
+### Option A — contributors / repo setup (recommended)
+```bash
+git clone https://github.com/slimx-ai/slimx.git
+cd slimx
+uv sync --all-extras
+```
+
+### Option B — quick test from an extracted zip
+```bash
+unzip slimx_v0_4.zip
+cd slimx_v0_4
+uv sync --all-extras
+uv run python examples/quickstart_openai.py
+```
+
+> `uv sync` reads `pyproject.toml` and (optionally) `uv.lock`.
+> If `uv.lock` is present and committed, installs are reproducible.
+
+---
+
+## 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)
+```bash
+export OLLAMA_BASE_URL="http://localhost:11434"
+```
+
+---
+
+## Quickstart (high-level)
+
+```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)
+```
+
+```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)
+```
+
+Streaming:
+
+```python
+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 (auto-loop):
+
+```python
+from slimx import llm, tool
+
+@tool
+def add(a: int, b: int) -> int:
+    "Add two integers."
+    return a + b
+
+m = llm("openai:gpt-4.1-nano", tools=[add], tool_runtime="auto")
+print(m("What is 12 + 30?").text)
+```
+
+Structured output:
+
+```python
+from dataclasses import dataclass
+from slimx import llm
+
+@dataclass
+class City:
+    name: str
+    country: str
+
+m = llm("openai:gpt-4.1-nano")
+res = m.json("Paris is in France.", schema=City)
+print(res.data)
+```
+
+---
+
+## Repo automation
+
+This bundle includes GitHub Actions:
+- CI (`.github/workflows/ci.yml`)
+- Docs deploy to GitHub Pages (`docs.yml`)
+
+See `README.md` and `docs/` for details.

slimx-0.5.0/docs/api/high.md

@@ -0,0 +1,10 @@
+# High-level API
+
+The high-level API is optimized for quick productivity:
+
+- `llm("provider:model")`
+- `model(prompt)`
+- `model.stream(prompt)`
+- `model.json(prompt, schema=...)`
+
+High-level calls still return normalized `Result` objects with text, usage, tool calls, parsed data, and trace metadata.

slimx-0.5.0/docs/api/low.md

@@ -0,0 +1,14 @@
+# Low-level API
+
+Use the low-level API when building systems such as RAG and agents:
+
+```python
+from slimx import Client, Message
+from slimx.low import ChatRequest
+from slimx.providers import get_provider
+
+client = Client(get_provider("openai"), timeout=30)
+result = client.chat(ChatRequest(model="gpt-4.1-nano", messages=[Message.user("Hello")]))
+```
+
+The low-level API keeps request objects, provider selection, retries, timeouts, and traces explicit.

slimx-0.5.0/docs/api/providers.md

@@ -0,0 +1,3 @@
+# Providers API
+
+See `slimx/providers/*`.

slimx-0.5.0/docs/concepts/architecture.md

@@ -0,0 +1,9 @@
+# Architecture
+
+## High-level view
+
+![SlimX class relationships](../assets/A_flowchart_diagram_visually_represents_the_class_.png)
+
+## Detailed view
+
+![SlimX detailed class relationships](../assets/A_detailed_flowchart_diagram_showcases_the_SlimX_l.png)

slimx-0.5.0/docs/concepts/high_vs_low.md

@@ -0,0 +1,3 @@
+# High vs Low
+
+High-level: `llm()` convenience. Low-level: explicit `Client` + `ChatRequest`.

slimx-0.5.0/docs/concepts/plugins.md

@@ -0,0 +1,3 @@
+# Plugins
+
+Register providers via entry points group `slimx.providers`.

slimx-0.5.0/docs/concepts/provider-capabilities.md

@@ -0,0 +1,7 @@
+# Provider Capabilities And Fallbacks
+
+Every provider exposes a small capability object describing whether it supports tools, structured output, streaming, async chat, and async streaming.
+
+Use this in demo diagnostics and production checks to avoid pretending every provider supports every feature equally.
+
+OpenAI currently supports tools, structured output, and streaming. Ollama is treated as a strong local streaming fallback. Anthropic support is available for chat, with streaming currently implemented as a compatibility wrapper.

slimx-0.5.0/docs/concepts/provider-neutral-calls.md

@@ -0,0 +1,11 @@
+# Provider-neutral Calls
+
+SlimX model IDs use `provider:model` strings. Providers are selected through adapters, while application code keeps using the same request and result shapes.
+
+Examples:
+
+- `openai:gpt-4.1-nano`
+- `anthropic:claude-3-5-haiku-latest`
+- `ollama:llama3.1`
+
+Provider-neutral calls let demos and deployments switch between hosted API models and local sovereignty fallbacks.

slimx-0.5.0/docs/concepts/providers.md

@@ -0,0 +1,3 @@
+# Providers
+
+Use prefixes like `openai:`, `anthropic:`, `ollama:`.

slimx-0.5.0/docs/concepts/slimx-rag.md

@@ -0,0 +1,11 @@
+# Using SlimX Inside SlimX-RAG
+
+SlimX-RAG handles deterministic retrieval. SlimX handles provider-neutral generation.
+
+The customer-demo flow is:
+
+```text
+question -> retrieve chunks -> build grounded prompt -> SlimX model call -> cited answer + trace
+```
+
+This keeps the retrieval trace and model trace separate, which makes the system easier to debug and explain to customers.

slimx-0.5.0/docs/concepts/streaming.md

@@ -0,0 +1,16 @@
+# Streaming Event Contract
+
+SlimX normalizes provider streaming into `StreamEvent` records.
+
+Event types:
+
+- `text_delta`
+- `tool_call`
+- `done`
+- `error`
+
+```python
+for event in model.stream("Tell a short story."):
+    if event.type == "text_delta":
+        print(event.text, end="", flush=True)
+```