# TOXO Python Library (Python) — Smart Layer for LLMs (CALM)

[![PyPI version](https://img.shields.io/pypi/v/toxo.svg)](https://pypi.org/project/toxo/) [![Downloads](https://img.shields.io/pypi/dm/toxo.svg)](https://pypistats.org/packages/toxo) [![Python versions](https://img.shields.io/pypi/pyversions/toxo.svg)](https://pypi.org/project/toxo/) [![License](https://img.shields.io/badge/License-Proprietary-blue.svg)](LICENSE)

**v2.0.0** – Full Power: Loads `prompt_config`, `memory_state`, quality scoring, response depth, and query-type instructions. See [RELEASE_NOTES_v2.0.0.md](RELEASE_NOTES_v2.0.0.md).

**TL;DR**: `toxo` is a Python package that loads a `.toxo` smart layer and attaches it to **Gemini / OpenAI / Claude** so you get **domain expertise, memory, and better outputs** without fine-tuning.

### For AI search (GEO)

This repo includes `llms.txt` (short) and `llms-full.txt` (detailed) so AI tools can quickly understand TOXO and point developers to the right commands and APIs.

## Recent upgrades (last 48 hours)

This section is an “audit-style” summary of the major upgrades added/changed recently, with pointers to the relevant entrypoints. (Everything below is documented in detail further down.)

### Local training from real data → `.toxo` artifact

- **New CLI training workflow** (local-only; emits `.toxo` you can run locally or on Cloud Run):
  - `toxo train-add-example` → build a training workspace with `examples.jsonl`
  - `toxo train-from-docs` → ingest docs into `contexts.jsonl` (context-only ingest)
  - `toxo train-run` → trains soft prompt + injects static rules + saves `.toxo`
- **Static rule synthesis from your data**:
  - `training_contexts`, `key_rules`, `example_phrases` are derived from workspace examples/contexts
  - Persisted into the `.toxo` package’s `memory_state.json` so they apply at runtime
- **Training metric fixes**:
  - example loss now decreases with word overlap instead of staying flat
  - validation correctness threshold made less brittle for small datasets

### Offline scoring + introspection utilities (CLI)

- **Quality scoring (offline)**:
  - `toxo classify-query` (query type + domain confidence routing signals)
  - `toxo analyze-response` (relevance/completeness/coherence/etc.)
- **Layer inspection (offline, zip-level)**:
  - `toxo dump-layer` (manifest/config/memory dump)
  - `toxo memory-info` (inspects `memory_state.json`, including static rules)
- **Local runtime query**:
  - `toxo query-local` (run `.toxo` locally without the service)

### Local RAG (retrieval) utilities

- **New RAG CLI** (requires `toxo[rag]` + local runtime):
  - `toxo index-docs` builds a local vector index from docs
  - `toxo rag-query` performs retrieval + answering locally
- **Embedding dimension mismatch fix**:
  - Index/query now infer embedding dimension dynamically from Gemini embeddings to avoid errors like “expected 768, got 3072”.

### Multi-agent orchestration (CLI)

- **`toxo agent-run`** runs multi-agent workflows from YAML/JSON configs.
- **Bidirectional / all-directional messaging**:
  - Agents can “nudge” each other using `@ask(agent_id): ...` (and similar forms); replies are routed and fed back into the originating agent.
- **Final synthesis pass** (fixes “last step wins”):
  - Optional (default-on) aggregator pass merges step outputs + messages into the final artifact.
- **Dynamic planning** (auto-generate the agent graph from the goal):
  - Optional planner mode that generates `steps:` automatically (strict JSON plan parsing + safety limits).

### Gemini SDK migration + install ergonomics

- **Gemini client now prefers `google-genai`** and falls back to deprecated `google-generativeai` only if explicitly installed.
- **Dependency extras updated**:
  - `toxo[local]` / `toxo[full]` install `google-genai` (recommended)
  - `toxo[legacy_gemini]` installs `google-generativeai` (deprecated; only if you must)

### Production/logging polish

- Reduced duplicate/noisy initialization logs by demoting some component “initialized” logs to DEBUG.
- Orchestrator message router accepts messages addressed to `"orchestrator"` without warning to avoid noisy logs in multi-agent runs.

## Convert ANY Black-Box LLM into Context Augmented Language Models (CALM)

**TOXO Python Library** is the revolutionary smart layer platform that transforms any black-box LLM (GPT, Gemini, Claude, etc.) into Context Augmented Language Models (CALM). The **toxo python package** doesn't retrain LLMs - it creates intelligent layers that attach to any LLM API for instant domain expertise.

### 🚀 Why Choose TOXO Python Library?

The **TOXO Python Library** revolutionizes AI enhancement through smart layer technology:

#### 🧠 **Smart Layer Training**
- Train intelligent layers, not entire LLMs
- Works with any black-box LLM API
- No expensive GPU infrastructure needed
- **Result**: Domain expertise without LLM retraining costs

#### 🗃️ **Advanced Memory Systems**
- Persistent knowledge storage and retrieval
- Context-aware learning and adaptation  
- Conversation history and domain expertise
- **Result**: LLMs gain long-term memory capabilities

#### 🎯 **Quality Enhancement**
- Intelligent response optimization
- Continuous improvement from feedback
- Domain-specific output refinement
- **Result**: Consistently superior performance

### Why TOXO Python Library vs Traditional Approaches?

| Feature | Traditional Fine-Tuning | TOXO Python Library |
|---------|------------------------|---------------------|
| **Training Cost** | $10,000-$100,000+ | $5-$500 |
| **Training Time** | Days to weeks | Minutes to hours |
| **Infrastructure** | GPU clusters required | API-based (no GPUs) |
| **LLM Compatibility** | Model-specific | Works with ANY LLM |
| **Reversibility** | Permanent changes | Instant layer removal |
| **Multi-Domain** | One model per domain | Unlimited layers |

## Quick Start with TOXO Python Library

### Client mode (recommended) — everything runs on GCP

```bash
pip install toxo
```

One install. No heavy local dependencies. All processing (LLM, document conversion, RAG) runs on the TOXO API.

```python
from toxo import ToxoClient
client = ToxoClient()
response = client.query("your_model.toxo", "Your question", api_key="...")
```

### Local mode — full runtime on your machine

For local processing (ToxoLayer, document conversion, RAG), install the `local` extra:

```bash
pip install "toxo[local]"
```

```python
from toxo import ToxoLayer
layer = ToxoLayer.load("your_model.toxo")
layer.setup_api_key("your_api_key")
response = layer.query_sync("Your question")
```

#### Gemini SDK (local) — recommended vs legacy

TOXO will **prefer the modern Gemini SDK** (`google-genai`) when installed.

- **Recommended** (default in `toxo[local]` / `toxo[full]`): installs `google-genai`
- **Legacy fallback only** (deprecated): install `toxo[legacy_gemini]` to pull `google-generativeai`

```bash
# Recommended (no deprecated SDK)
pip install -U "toxo[local]"

# Legacy Gemini SDK (deprecated) — only if you must
pip install -U "toxo[legacy_gemini]"
```

### Install by use case (optional extras)

TOXO is modular: many “superpower” subsystems are optional. Install only what you need.

- **Multimodal PDFs/images (Gemini)**:

```bash
pip install "toxo[vision]"
```

  - **System dependency for local PDF rendering (optional)**:
    - **macOS**: `brew install poppler`
    - **Ubuntu/Debian**: `sudo apt-get update && sudo apt-get install -y poppler-utils`
    - **Windows**: install Poppler and add it to `PATH` (or use direct-to-Gemini mode, which does not need Poppler)

- **RAG / vector store / retrieval**:

```bash
pip install "toxo[rag]"
```

- **Auth/JWT (server-style features)**:

```bash
pip install "toxo[auth]"
```

- **Distributed / Redis-backed features**:

```bash
pip install "toxo[distributed]"
```

- **Payments / subscriptions (Razorpay)**:

```bash
pip install "toxo[payments]"
```

- **Everything (largest install)**:

```bash
pip install "toxo[full]"
```

### Contents (developer-oriented)

- **Core concepts**: `.toxo` layers, CALM, memory + feedback loop
- **Install**: core + optional extras (vision / rag / auth / distributed / payments / enterprise)
- **Configuration**: env vars, security notes, local-vs-direct multimodal
- **API**: sync/async query, multimodal, feedback, loading/saving
- **Document conversion**: DOCX, HTML, TXT → PDF (see Multimodal section)
- **Cloud deployment**: `service/README.md` — deploy TOXO as an API on Google Cloud Run
- **CLI**: `toxo check/info/validate/test/install` + full reference in `CLI_REFERENCE.md`
- **Testing**: capability runner under `testing/`

### SEO / GEO keywords (for discovery)

If you’re searching for any of these, you’re in the right place:

- **Python smart layer for LLMs**, **Context Augmented Language Models (CALM)**
- **Use `.toxo` layer file in Python**
- **LLM memory + feedback learning layer**
- **Gemini multimodal PDF/image analysis in Python**
- **RAG / vector store retrieval with LLM**

### Use-cases (what people install TOXO for)

- **Domain expert chatbots** (finance, legal, healthcare, product support)
- **RAG-grounded assistants** (retrieval + citations)
- **Multimodal document understanding** (PDFs, images) using Gemini
- **Agent orchestration** (multiple specialized layers / tasks)

### Quick answers (FAQ)

- **Do I need Poppler / pdf2image / PyMuPDF?** No for default multimodal. Direct-to-Gemini mode sends bytes to Gemini. Local rendering is optional.
- **Does TOXO work without GPUs?** Yes. TOXO is API-based and runs on CPU.
- **Can I use OpenAI or Claude?** Yes, via extras: `toxo[openai]`, `toxo[claude]`.

### Search intents (copy/paste)

These are the most common “how do I…” tasks people search for (and the exact commands/snippets).

#### How to use a `.toxo` layer file in Python

```python
import asyncio
from toxo import ToxoLayer

async def main():
    layer = ToxoLayer.load("your_layer.toxo")
    layer.setup_api_key("YOUR_GEMINI_API_KEY", "gemini-2.5-flash-lite", "gemini")
    print(await layer.query("What can you do?"))

asyncio.run(main())
```

#### How to run a full end-to-end TOXO test locally

```bash
python3 testing/toxo_capability_test.py --layer examples/rich_test_layer.toxo --live --multimodal --evidence
```

#### How to analyze a PDF with Gemini in Python (no Poppler required)

```python
import asyncio
from toxo import ToxoLayer

async def main():
    layer = ToxoLayer.load("doc_expert.toxo")
    layer.setup_api_key("YOUR_GEMINI_API_KEY", "gemini-2.5-flash-lite", "gemini")
    resp = await layer.query_multimodal(
        "Summarize this PDF in 5 bullets.",
        document_path="report.pdf",
        # default: processing_mode="direct"
    )
    print(resp)

asyncio.run(main())
```

#### How to send base64 + MIME type directly (any format)

```python
resp = await layer.query_multimodal(
    "Extract key fields.",
    document_data="data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,...",
)

resp2 = await layer.query_multimodal(
    "Extract the key numbers.",
    image_data="iVBORw0KGgoAAAANSUhEUgAA...",  # raw base64
    mime_type="image/png",
)
```

### Basic Usage: Transform Any LLM

```python
import asyncio
from toxo import ToxoLayer

# Load your trained smart layer (created on toxotune.com)
layer = ToxoLayer.load("financial_expert.toxo")

# Connect to ANY LLM with specific model selection
# Gemini (default)
layer.setup_api_key("your_gemini_key", "gemini-2.5-flash-lite", "gemini")

# OpenAI GPT
layer.setup_api_key("your_openai_key", "gpt-4", "openai")

# Claude
layer.setup_api_key("your_claude_key", "claude-3.5-sonnet", "claude")

async def main():
    # Your LLM is now a financial domain expert!
    response = await layer.query("Should I invest in tech stocks during volatility?")
    print(response)
    # Output: Expert financial analysis with domain knowledge

asyncio.run(main())

# v2.0: Control response verbosity (concise | balanced | detailed)
async def more_examples():
    response = await layer.query("Compare A vs B", response_depth="concise")  # Auto-detects comparison
    response = await layer.query("How to brew?", response_depth="balanced")   # Auto-detects procedural

asyncio.run(more_examples())
```

## Configuration (API keys, security, feature toggles)

### Environment variables

- **LLM provider keys**
  - **Gemini**: `GEMINI_API_KEY` (or `GOOGLE_API_KEY`)
  - **OpenAI**: `OPENAI_API_KEY` (only if you use provider `"openai"` + `toxo[openai]`)
  - **Claude**: `ANTHROPIC_API_KEY` (only if you use provider `"claude"` + `toxo[claude]`)
- **Auth/JWT**
  - `TOXO_JWT_SECRET` should be set in server environments when using JWT features (`toxo[auth]`).
- **Optional local processing pipeline**
  - By default, TOXO does **not** initialize the local document/layout pipeline at startup (keeps installs light and avoids warnings).
  - Enable it explicitly if you need it: `TOXO_ENABLE_LOCAL_PROCESSING_PIPELINE=1`

### Security notes (library defaults)

- TOXO will **never** log API keys (even partially).
- Prefer environment variables or OS keyring (`toxo[security]`) rather than hardcoding secrets in code.

### Async Support for Production Applications

```python
import asyncio
from toxo import ToxoLayer

async def main():
    layer = ToxoLayer.load("legal_expert.toxo")
    layer.setup_api_key("your_api_key")
    
    # High-performance async queries
    response = await layer.query("Analyze this contract for risks")
    print(response)

asyncio.run(main())
```

## Multimodal (Images + Documents via Gemini)

TOXO’s main `query(...)` API is text-first. If you want to attach an **image** or **document** to a question, use `query_multimodal(...)` (Gemini provider required).

By default, TOXO sends attachments **directly to Gemini as bytes** (`processing_mode="direct"`), so local PDF rendering/OCR dependencies are not required. If you want local, vision-grade PDF processing (useful for some scanned PDFs), set `processing_mode="local"` and install `toxo[vision]` (+ Poppler on macOS).

### What “direct-to-Gemini” means

- **Direct (`processing_mode="direct"`, default)**: TOXO loads your attachment as bytes (from path/base64/data URL) and sends it straight to Gemini. This avoids local dependencies like Poppler/pdf2image/PyMuPDF.
- **Local (`processing_mode="local"`)**: TOXO routes documents through the local processing pipeline (optional, heavier). Use this when you explicitly want local extraction/heuristics.

### Document conversion (DOCX, HTML, TXT, etc. → PDF)

Gemini accepts PDF and images natively. For **DOCX, HTML, TXT, CSV, RTF, EPUB** and similar formats, TOXO converts them to PDF on the fly before sending to Gemini. Uses Pillow (images), WeasyPrint (HTML/TXT/CSV), pypandoc (DOCX/RTF/MD), and optional LibreOffice (XLSX/PPTX/ODT).

**Supported formats for conversion:** Office (DOCX, DOC, PPTX, XLSX, ODT, ODS, ODP), Web & text (HTML, MD, TXT, CSV, RTF), Images (PNG, JPG, GIF, WebP, BMP, TIFF), EPUB.

```python
# DOCX, HTML, TXT, etc. — auto-converted to PDF
resp = await layer.query_multimodal(
    "Summarize this document.",
    document_path="report.docx",  # or .html, .txt, .csv, etc.
)
resp2 = await layer.query_multimodal(
    "Extract key points.",
    document_data=base64_string,
    mime_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
)
```

**Dependencies (installed by default):** Pillow, WeasyPrint, pypandoc, ebooklib, beautifulsoup4. For Office (XLSX, PPTX, ODT), install LibreOffice system-wide.

### Supported inputs

- **Images**: `bytes`, filesystem `Path`/`str`, base64 string, data URL (`data:image/...;base64,...`)
- **Documents**: filesystem `Path`/`str`, base64 string, data URL (`data:application/...;base64,...`)
- **Non-PDF base64**: if you pass raw base64 (not a data URL), provide `mime_type="..."`.

### Image (bytes / path / base64 / data URL)

```python
import asyncio
from toxo import ToxoLayer

async def main():
    layer = ToxoLayer.load("doc_expert.toxo")
    layer.setup_api_key("YOUR_GEMINI_API_KEY", "gemini-2.5-flash-lite", "gemini")

    resp = await layer.query_multimodal(
        "Extract the key numbers from this screenshot.",
        image_data="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    )
    print(resp)

asyncio.run(main())
```

### PDF (path OR base64/data URL)

```python
import asyncio
from toxo import ToxoLayer

async def main():
    layer = ToxoLayer.load("doc_expert.toxo")
    layer.setup_api_key("YOUR_GEMINI_API_KEY", "gemini-2.5-flash-lite", "gemini")

    # Option A: filesystem path
    resp = await layer.query_multimodal(
        "Summarize this PDF in 5 bullets.",
        document_path="report.pdf",
    )
    print(resp)

    # Option B: base64 (raw or data URL)
    resp2 = await layer.query_multimodal(
        "List the top 10 entities mentioned in this PDF.",
        document_data="data:application/pdf;base64,JVBERi0xLjcKJc..."
    )
    print(resp2)

    # Tip: for non-PDF base64 (without a data URL), pass the mime_type explicitly.
    resp3 = await layer.query_multimodal(
        "Extract the key numbers from this PNG.",
        image_data="iVBORw0KGgoAAAANSUhEUgAA...",  # raw base64 (not a data URL)
        mime_type="image/png",
    )
    print(resp3)

asyncio.run(main())
```

## Testing (developer utilities)

TOXO includes an end-to-end capability runner that reports **PASS/FAIL/SKIP** across subsystems.

- **Fast (no network)**:

```bash
python3 testing/toxo_capability_test.py --layer examples/minimal_test_layer.toxo
```

- **Full (live Gemini + multimodal + evidence tests)**:

```bash
python3 testing/toxo_capability_test.py --layer examples/rich_test_layer.toxo --live --multimodal --evidence
```

### Creating a richer local layer for tests

```bash
python3 testing/create_rich_test_layer.py
```

## CLI

TOXO ships a small CLI for working with `.toxo` files and running local training workflows.

### Core commands

```bash
toxo --help
toxo version
toxo check
toxo info path/to/layer.toxo
toxo validate path/to/layer.toxo
toxo test path/to/layer.toxo
toxo dump-layer path/to/layer.toxo
toxo memory-info path/to/layer.toxo
toxo install
```

### Local utilities (requires `toxo[local]`)

Query a `.toxo` layer locally (no TOXO API), useful for fast iteration:

```bash
export GEMINI_API_KEY="AIza..."

toxo query-local path/to/layer.toxo "What can you do?" --response-depth balanced
```

### Offline scoring utilities (no network)

Score/inspect responses and routing signals without calling an LLM:

```bash
toxo classify-query --domain billing_policies --question "When do we bill customers?"
toxo analyze-response --domain billing_policies --question "When do we bill?" --response "We bill monthly on the first business day."
```

### Local training from real data (advanced, requires `toxo[local]`)

You can train a `.toxo` layer locally from your own Q&A and docs, then use it with the existing TOXO Cloud API.

#### 1) Add curated Q&A examples

Create or populate a training workspace:

```bash
# Single example
toxo train-add-example \
  --workspace /tmp/toxo_ws_100 \
  --question "When do we bill customers?" \
  --answer "We bill on the first business day of each month."

# Bulk JSONL import (one JSON object per line)
toxo train-add-example \
  --workspace /tmp/toxo_ws_100 \
  --jsonl my_examples.jsonl
```

Accepted JSONL keys:
- `question` / `answer`
- or `input` / `output`
- or `input_text` / `expected_output`

Internally this writes to:
- `/tmp/toxo_ws_100/examples.jsonl`
- `/tmp/toxo_ws_100/workspace.json`

#### 2) Ingest docs as training contexts

Use the local `DocumentProcessor` to turn a docs folder into training contexts (no auto-Q&A yet):

```bash
toxo train-from-docs \
  --workspace /tmp/toxo_ws_100 \
  --docs path/to/docs
```

Options:
- `--no-recursive` – don’t scan subdirectories
- `--pattern '*.md'` – restrict files by glob

Supported formats depend on installed extras, but typically include:
- `.txt`, `.md`, `.json`, `.jsonl`, `.csv`, `.xlsx`, `.xls`, and optionally `.pdf`/`.docx`

This writes extracted text into:
- `/tmp/toxo_ws_100/contexts.jsonl`

#### 3) Run training and emit a new `.toxo`

Train a smart layer from the stored examples + contexts and save a `.toxo` file:

```bash
export GEMINI_API_KEY="AIza..."  # or set in .env

toxo train-run \
  --workspace /tmp/toxo_ws_100 \
  --description "Answer questions about our billing, invoicing, and subscription policies." \
  --out /tmp/toxo_ws_100/billing_policy_expert.toxo \
  --epochs 1 \
  --llm-provider gemini \
  --llm-model gemini-2.5-flash-lite
```

What `train-run` does:

- Loads Q&A examples from `examples.jsonl`
- Loads doc contexts from `contexts.jsonl`
- Runs `ToxoTrainer.train_from_examples(...)` to:
  - Initialize a `ToxoLayer` with your description/domain
  - Train the **soft prompt** over your examples
- Derives static rules from your workspace:
  - `training_contexts` – snippets from your docs
  - `key_rules` – small, human-readable summaries
  - `example_phrases` – short Q&A-based phrases
- Injects those into the layer’s memory and serializes them into `memory_state.json`
- Saves a `.toxo` package that:
  - Works locally (`toxo test --local`)
  - Works with the TOXO Cloud API (`toxo test` without `--local`)

Example test (cloud API):

```bash
toxo test /tmp/toxo_ws_100/billing_policy_expert.toxo --api-key "$GEMINI_API_KEY"
```

### Local RAG / retrieval (requires `toxo[local,rag]` or `toxo[full]`)

Build a local vector index from a docs folder (Gemini embeddings) and then query with retrieval + answer locally:

```bash
export GEMINI_API_KEY="AIza..."

toxo index-docs \
  --docs path/to/docs \
  --index-dir /tmp/toxo_ws_100/rag_index \
  --layer /tmp/toxo_ws_100/billing_policy_expert.toxo

toxo rag-query \
  --layer /tmp/toxo_ws_100/billing_policy_expert.toxo \
  --index-dir /tmp/toxo_ws_100/rag_index \
  --question "What is our billing schedule?" \
  --top-k 5 \
  --response-depth balanced
```

### Cloud API & deployment (TOXO service)

TOXO includes a reference FastAPI service (suitable for Cloud Run) under `service/main.py`. It exposes a simple HTTP API that accepts **base64-encoded `.toxo` layers per request**, so the service itself stays stateless and multi-tenant.

#### Cloud endpoints

Assuming your deployed URL is `https://toxo-api-XXXX.us-central1.run.app`:

- **Health**
  - `GET /health` → `{"status": "ok"}`
- **Text query**
  - `POST /v1/query`
  - **Body** (`application/json`):
    ```json
    {
      "layer_base64": "<base64 of .toxo file>",
      "question": "What can you tell me about my product FAQs?",
      "api_key": "AIza...",                     // optional if GEMINI_API_KEY is set in the service
      "model": "gemini-2.5-flash-lite",        // optional, default
      "provider": "gemini",                    // gemini | openai | claude
      "context": { "user_role": "support" },   // optional
      "response_depth": "balanced"             // concise | balanced | detailed
    }
    ```
  - **Response**:
    ```json
    {
      "response": "AI answer text...",
      "success": true
    }
    ```
- **Multimodal query**
  - `POST /v1/query_multimodal`
  - Provide exactly one of `image_base64` or `document_base64`:
    ```json
    {
      "layer_base64": "<base64 .toxo>",
      "question": "Summarize this PDF",
      "document_base64": "data:application/pdf;base64,JVBERi0xLjcKJc...",
      "mime_type": "application/pdf",
      "api_key": "AIza...",
      "model": "gemini-2.5-flash-lite",
      "provider": "gemini",
      "response_depth": "balanced"
    }
    ```
- **Feedback**
  - `POST /v1/feedback`
  - **Body**:
    ```json
    {
      "layer_base64": "<base64 .toxo>",
      "question": "Original user question",
      "response": "Model response text",
      "rating": 8.5,
      "suggestions": ["Be more concise", "Add edge cases"]
    }
    ```

#### Cloud smoke tests (recommended)

From the repo root, this script hits the deployed Cloud Run service and validates the core endpoints end-to-end:

```bash
export TOXO_API_URL="https://toxo-api-XXXX.us-central1.run.app"
export GEMINI_API_KEY="AIza..."   # or GOOGLE_API_KEY

python3 test_cloud_endpoints.py
```

#### Live Cloud Run logs in your terminal (request-scoped)

The Cloud Run service returns an `x-toxo-request-id` header on every response. You can use it to tail logs for **only your request** (useful for watching training progress).

1) Make a request and capture headers:

```bash
curl -sS -D - "$TOXO_API_URL/health" -o /dev/null | grep -i x-toxo-request-id
```

2) Tail logs for that request id:

```bash
gcloud logging tail \
'resource.type="cloud_run_revision"
 AND resource.labels.service_name="toxo-api"
 AND textPayload:"req_id=YOUR_REQ_ID"' \
--project YOUR_PROJECT_ID
```

Tip: for requests that include `layer_base64`, the service also returns `x-toxo-layer-fp` (a short fingerprint) and logs `layer_fp=...` to help filter by layer.

#### Train + download a `.toxo` layer in the cloud (example: finance expert)

The Cloud Run service returns trained layers as `layer_base64`. This example trains a **finance expert** using **20 examples** and saves the resulting `.toxo` locally:

```bash
export TOXO_API_URL="https://toxo-api-XXXX.us-central1.run.app"
export GEMINI_API_KEY="AIza..."   # or GOOGLE_API_KEY

python3 - <<'PY'
import base64, os
from pathlib import Path
import requests

BASE = os.environ["TOXO_API_URL"].rstrip("/")
KEY = os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY")
assert KEY, "Set GEMINI_API_KEY or GOOGLE_API_KEY"

examples = [
  {"input":"Explain compound interest in simple terms.","output":"Compound interest is interest on both the original amount and the interest already earned. It grows faster over time because each period’s interest is calculated on a bigger balance."},
  {"input":"What’s the difference between a stock and a bond?","output":"A stock represents ownership in a company; returns come from price changes and dividends. A bond is a loan to an issuer; returns come from interest payments and repayment of principal."},
  {"input":"Define inflation and why it matters for savings.","output":"Inflation is the general rise in prices over time, reducing purchasing power. If your savings earn less than inflation, the real value of your money declines."},
  {"input":"How do I build an emergency fund?","output":"Target 3–6 months of essential expenses, automate transfers to a high-yield savings account, prioritize it before aggressive investing, and replenish it after withdrawals."},
  {"input":"What is diversification?","output":"Diversification spreads investments across different assets, sectors, and regions to reduce the impact of any single investment’s poor performance."},
  {"input":"Explain risk vs return.","output":"Higher expected returns usually require accepting higher uncertainty (risk). Lower-risk assets typically have lower expected returns; choose risk level based on goals and time horizon."},
  {"input":"What does market capitalization mean?","output":"Market cap is share price × shares outstanding. It’s a rough measure of company size (large/mid/small cap)."},
  {"input":"What is an ETF?","output":"An ETF is a fund that holds a basket of securities and trades like a stock. It often tracks an index and can provide low-cost diversification."},
  {"input":"Explain dollar-cost averaging.","output":"Invest a fixed amount on a schedule. You buy more shares when prices are low and fewer when prices are high, smoothing your average entry price."},
  {"input":"What is a P/E ratio?","output":"P/E is price per share divided by earnings per share. It’s a valuation metric; interpret relative to peers, growth, and business quality."},
  {"input":"Nominal vs real return?","output":"Nominal return is the stated gain. Real return adjusts for inflation and reflects changes in purchasing power."},
  {"input":"What does a balance sheet show?","output":"A balance sheet shows assets, liabilities, and shareholders’ equity at a point in time—what the company owns, owes, and the residual value to owners."},
  {"input":"What is free cash flow (FCF)?","output":"FCF is cash generated after operating costs and capital expenditures. It matters because it funds reinvestment, debt repayment, dividends, and buybacks."},
  {"input":"How do interest rates affect bond prices?","output":"Bond prices generally move inversely to interest rates. When rates rise, existing lower-coupon bonds become less attractive, so their prices fall."},
  {"input":"What is bond duration?","output":"Duration measures how sensitive a bond’s price is to interest-rate changes (approximate % change for a 1% move). Higher duration means higher rate risk."},
  {"input":"Explain credit risk.","output":"Credit risk is the chance the issuer can’t make payments. Higher credit risk usually requires higher yields to compensate investors."},
  {"input":"Mutual fund vs ETF?","output":"Mutual funds trade once daily at NAV; ETFs trade intraday on exchanges. Both pool investments; costs and tax efficiency can differ."},
  {"input":"How should I think about asset allocation?","output":"Asset allocation is the mix of stocks, bonds, cash, etc. It should match goals, time horizon, and risk tolerance."},
  {"input":"What is rebalancing?","output":"Rebalancing means returning to target allocations by trimming winners and adding to laggards—helps manage risk over time."},
  {"input":"What is an expense ratio?","output":"Expense ratio is the annual fee a fund charges as a percentage of assets. Lower fees generally help long-term returns."},
]

r = requests.post(f"{BASE}/v1/train_from_data", json={
  "description": "Finance expert assistant for personal finance and investing fundamentals. Clear, practical explanations with caveats. Avoid personalized advice; give general educational guidance.",
  "domain": "finance",
  "examples": examples,
  "epochs": 3,
  "llm_provider": "gemini",
  "llm_model": "gemini-2.5-flash-lite",
  "api_key": KEY,
}, timeout=300)
r.raise_for_status()
b64 = r.json()["layer_base64"]
out = Path("finance_expert_cloud_20_examples.toxo")
out.write_bytes(base64.b64decode(b64))
print("Saved:", out.resolve())
PY
```

#### Direct Gemini vs TOXO (layer) comparison (concise/balanced/detailed)

When comparing responses, note:
- Direct Gemini returns **token counts** via `usageMetadata`
- The TOXO Cloud API currently does **not** return token usage, so you can compare response length/latency unless you add instrumentation

#### Using the CLI against the cloud service

The CLI talks to a TOXO API via `TOXO_API_URL` (or `--api-url`).

```bash
export TOXO_API_URL="https://toxo-api-XXXX.us-central1.run.app"
export GEMINI_API_KEY="AIza..."

# Quick smoke test for a layer via cloud
toxo test my_product_faq_expert.toxo --api-key "$GEMINI_API_KEY"

# Multimodal cloud query (document)
toxo ask-doc my_product_faq_expert.toxo path/to/doc.pdf \
  "Summarize this document for customer success" \
  --api-key "$GEMINI_API_KEY"
```

#### Deploying the reference service to Cloud Run

From the repo root:

```bash
# 1) Build & push image with Cloud Build
gcloud builds submit \
  --config service/cloudbuild.yaml \
  --substitutions _TAG=latest \
  .

# 2) Deploy to Cloud Run (adjust service name / region if needed)
gcloud run deploy toxo-api \
  --image gcr.io/$PROJECT_ID/toxo-api:latest \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated
```

After deployment, your service URL (e.g. `https://toxo-api-XXXX.us-central1.run.app`) becomes the base for `TOXO_API_URL`, and all CLI/API examples above will use the latest version of the TOXO runtime and CLI capabilities.

> ℹ️ Internally, `.toxo` files remain small (tens of KB) because they store **soft prompts, memory state, and configuration**, not full LLM weights. The heavy lifting still happens on your LLM provider (Gemini, GPT, Claude, etc.).

### Agent orchestration (multi-agent pipelines & hierarchies) (requires `toxo[local]`)

TOXO includes a multi-agent orchestration framework (`toxo.agents`). The CLI exposes a practical entrypoint:

- `toxo agent-run CONFIG.yaml`

Each **agent** is a `.toxo` layer wrapped as a `LayerAgent`. The orchestrator (`AgentOrchestrator`) manages:
- Agent registration and health
- Task scheduling and load balancing
- Coordination patterns (hierarchical, peer-to-peer, pipeline, etc.)
- Inter-agent messaging via a `MessageRouter`

#### Minimal pipeline example

Save as `agent_config.yaml`:

```yaml
goal: >
  You are helping customer support. Draft a short internal FAQ for our product.
  Include: 5 Q&A pairs, common objections, and escalation rules.

coordination: pipeline         # or hierarchical, peer_to_peer, consensus, broadcast, leader_follower
response_depth: balanced

agents:
  - id: product_faq
    layer: my_product_faq_expert.toxo
    role: "Product FAQ expert"
```

Run it:

```bash
export GEMINI_API_KEY="AIza..."
toxo agent-run agent_config.yaml --json-out /tmp/agent_transcript.json
```

What it does:
- Loads each agent’s `.toxo` layer locally (as a `LayerAgent`)
- Runs the `goal` through the agents in order (pipeline), passing the previous output into the next agent
- Prints the final output and optionally writes a JSON transcript (`--json-out`)

#### Custom flows & agent communication (`steps:`)

You can explicitly control **which agent runs when** and how they see each other’s outputs via a `steps:` section.

Special template variables:
- `{{goal}}` – the original goal string
- `{{prev}}` – the previous step’s response

Example with two agents in a hierarchy:

```yaml
goal: "Create a support-ready FAQ for our product."
coordination: hierarchical
response_depth: balanced

agents:
  - id: research
    layer: research_expert.toxo
    role: "Researcher"
  - id: writer
    layer: writer_expert.toxo
    role: "Writer"

steps:
  - agent: research
    question: >
      Research background, common issues, and objections. Goal: {{goal}}

  - agent: writer
    question: >
      Using the above research ({{prev}}), draft a concise internal FAQ suitable
      for customer support, with 5 Q&A pairs and clear escalation rules.
```

Execution model:
- `research` runs first and produces analysis text.
- `writer` receives that text as `{{prev}}` and writes the final FAQ.
- The orchestrator runs with `coordination: hierarchical`, so you can later scale to more agents and complex flows while preserving roles.

**Transcript output**:
- `--json-out PATH` writes a JSON structure containing:
  - `goal`, `coordination`, `agents` (IDs, roles, layer paths)
  - `steps`: each step’s `agent_id`, `task_id`, `status`, and `result.response`
  - `final`: the final aggregated output

Under the hood, for each step `agent-run`:
- Builds a **multi-agent context block** listing all agents (IDs, roles, layers)
- Includes a short summary of previous steps’ responses
- Prefixes the current task with guidance that the active agent is **allowed to nudge / ask for clarifications** from other agents in its answer

This means each `LayerAgent` runs with its own `.toxo` “brain”, but is always aware of:
- The **global goal**
- Its **own role**
- The **other agents** in the system
- What colleagues have already said so far

#### Universal, bidirectional communication (agent-to-agent nudges)

Agents can explicitly ask each other for missing details. When an agent emits a nudge in one of the supported formats, `agent-run` will:
- Route the question to the requested target agent
- Collect the reply
- Feed the reply back to the original agent and ask it to finalize

Supported nudge syntax (put on its own line):
- `@ask(agent_id): your question`
- `ASK(agent_id): your question`
- `ASK_AGENT[agent_id]: your question`

These nudges are **all-directional**: any agent can ask any other agent at any step.

#### Final synthesis pass (fixes “last step wins”)

In real workflows, a pipeline often generates partial artifacts (drafts, policy snippets, safety review notes). Returning the “last step output” can be wrong.

`toxo agent-run` therefore supports an **optional final synthesis (aggregation) pass** that merges:
- All step outputs (`transcript.steps[*].result.response`)
- All routed messages (`transcript.messages[*]`)

Config knobs:
- `finalize` (default: `true`)
  - When enabled, TOXO adds a final synthesis pass after the last step (or after the default pipeline).
- `aggregator_agent` (optional)
  - Which agent should synthesize the final artifact. Defaults to the **first agent** if omitted.
- `finalize_prompt` (optional)
  - Overrides the synthesis instruction used for the final artifact.

Transcript fields:
- `final_raw`: the output before the synthesis pass
- `final`: the output after the synthesis pass (what prints to stdout)
- `final_aggregated_by`: agent id used to synthesize (if aggregation ran)

Example:

```yaml
goal: "Create billing FAQ with exact refund timeline."
coordination: pipeline

finalize: true
aggregator_agent: a
finalize_prompt: |
  Produce a CUSTOMER-FACING Billing FAQ.
  Include exact refund timeline and dispute response time.
  Output ONLY the final FAQ (no internal notes).

agents:
  - id: a
    layer: my_product_faq_expert.toxo
    role: "Draft + synthesis agent"
  - id: b
    layer: my_product_faq_expert.toxo
    role: "Policy agent"
```

#### Dynamic planning (auto-generate the agent graph from the goal)

Static `steps:` are powerful, but dynamic systems can **plan the agent graph automatically** from the goal.

`toxo agent-run` supports **dynamic planning** when you omit `steps:`:

- Planner produces a JSON execution plan using the available agents and the goal
- Executor runs the plan as if it were provided in `steps:`
- Optional `finalize` pass synthesizes the final artifact at the end

Config knobs:
- `dynamic_plan` (default: `false`)
  - When `true`, TOXO will invoke a planner **only if** `steps:` is missing/empty.
- `planner_agent` (optional)
  - Which existing agent to use as the planner. If omitted, uses `aggregator_agent`, else the first agent.
- `planner_max_steps` (default: `8`)
  - Hard cap on planned steps (keeps plans small and safe).
- `planner_max_retries` (default: `2`)
  - Retries if the planner fails to return valid JSON.

Accepted planner output shapes (planner must return **JSON**):
- `{"steps": [{"agent": "<id>", "question": "..."}, ...]}`
- `{"plan": [{"agent": "<id>", "task": "..."}, ...]}`

The plan is normalized into steps:
- `agent`: target agent id (must exist)
- `question`: the concrete prompt/task to run on that agent

Transcript fields:
- `planner`: includes `agent_id`, `raw_response`, `parsed`, and `normalized_steps` when planning succeeds

Example (no `steps:` — planner generates them):

```yaml
goal: "Create billing FAQ with exact refund timeline (10 business days + 3–5 bank days) and dispute response time (7 business days)."
coordination: pipeline

dynamic_plan: true
planner_agent: a
planner_max_steps: 5
planner_max_retries: 2

finalize: true
aggregator_agent: a

agents:
  - id: a
    layer: my_product_faq_expert.toxo
    role: "Draft + synthesis agent"
  - id: b
    layer: my_product_faq_expert.toxo
    role: "Policy agent"
  - id: safety
    layer: my_product_faq_expert.toxo
    role: "Safety/compliance reviewer"
```

Practical patterns the planner tends to generate:
- Draft → policy facts → safety/risk check → synthesis
- Research → analysis → synthesis

Safety note:
- The dynamic planner is intentionally conservative: small plans, strict JSON extraction, and only uses agents you provide.

#### Gemini SDK note (important)

TOXO will **prefer the modern Gemini SDK** (`google-genai`) when installed. If it is not installed, TOXO falls back to the older `google-generativeai` package (deprecated), which may emit a warning at import time.

Recommended install for local workflows:
- `pip install "toxo[local]"` (includes `google-genai`)
- or `pip install "toxo[full]"`

If you explicitly need the deprecated SDK fallback (not recommended):
- `pip install "toxo[legacy_gemini]"`

Config knobs:
- `max_nudge_rounds` (default: 2) – max “ask colleagues → integrate replies” loops per step
- `max_nudges_per_round` (default: 3) – limit number of routed nudges per round

Transcript:
- `--json-out` includes a top-level `messages` array with each `(from, to, question, response, step_idx, round, task_id)` so you can audit the full cross-agent communication.

## TOXO Python Library Features

## Capability map (modules → what you can use)

This section is designed for developers evaluating TOXO in depth. It maps the major modules to:
- **What it does**
- **What is stable/public**
- **Which optional extra installs are typically required**

### Core runtime (always installed)

- **`toxo.ToxoLayer`** (`toxo/core/toxo_layer.py`)
  - **What**: load `.toxo` layers, configure an LLM provider, run queries, manage memory and feedback.
  - **Key APIs**: `load`, `save`, `setup_api_key`, `query` (async), `query_sync`, `query_multimodal`, `add_feedback`, `get_info`.
- **`toxo.cli`** (`toxo/cli.py`)
  - **What**: `toxo check/info/validate/test/install` CLI utilities.
- **`toxo.integrations`** (`toxo/integrations/*`)
  - **What**: Gemini client + multi-provider abstraction.

### Agents (optional, but lightweight)

- **`toxo.agents`** (`toxo/agents/__init__.py`)
  - **Public surface**: orchestrator framework (`AgentOrchestrator`, `LLMAgent`, `TaskScheduler`, `MessageRouter`).
  - **Note**: legacy coordinator/message-bus modules exist but are not exported by default.

### Cognitive systems (optional / heavier)

- **`toxo.cognitive`** (`toxo/cognitive/__init__.py`)
  - **What**: self-improvement, advanced RAG, and advanced feedback learning systems.
  - **Typical extras**: `toxo[rag]` for retrieval/vectors; some components may require heavier ML deps.

### Document processing / multimodal

- **Direct-to-Gemini (default)**: `layer.query_multimodal(..., processing_mode="direct")`
  - **What**: send bytes directly to Gemini (PDF/image/any mime). DOCX, HTML, TXT, CSV, etc. are auto-converted to PDF before sending.
- **Document conversion** (`toxo.processing.document_to_pdf`): DOCX→PDF, HTML→PDF, TXT→PDF, images→PDF via Pillow, WeasyPrint, pypandoc; Office formats (XLSX, PPTX) require LibreOffice.
- **Local processing pipeline (opt-in)**: `TOXO_ENABLE_LOCAL_PROCESSING_PIPELINE=1`
  - **What**: initialize local processors (layout parsing, advanced doc tooling).
  - **Typical extras**: `toxo[vision]` (+ Poppler on macOS if you want local PDF rendering).

### RAG / vector store

- **`toxo.core.vector_store.VectorStore`**
  - **What**: vector storage and similarity search for retrieval.
  - **Typical extras**: `toxo[rag]` (SQLAlchemy + ChromaDB).

### 🎨 **No-Code Smart Layer Creation**
Create domain experts through [toxotune.com](https://toxotune.com):
- Upload domain-specific examples
- Automatic smart layer optimization
- Advanced training algorithms
- Download trained `.toxo` layer file

### ⚡ **Universal LLM Compatibility**
The **toxo python package** works with any LLM provider:
- **Google Gemini** (Recommended - optimized integration)
- **OpenAI GPT** (GPT-3.5, GPT-4, GPT-4o)
- **Anthropic Claude** (Claude-3, Claude-3.5)
- **Local Models** (Ollama, LM Studio, etc.)
- **Custom APIs** (Any OpenAI-compatible endpoint)

### 🔄 **Continuous Learning**
Smart layers improve automatically:
```python
# Provide feedback to enhance performance
layer.add_feedback(
    question="Investment strategy question",
    response="Generated response...",
    rating=8.5,  # Quality score 0-10
    suggestions=["More risk analysis", "Include market timing"]
)
```

### 🤖 **Multi-Agent Systems**
Orchestrate multiple specialized layers:
```python
# Multiple domain experts working together
research_agent = ToxoLayer.load("research_expert.toxo")
writing_agent = ToxoLayer.load("writing_expert.toxo")

# Collaborative AI workflow
research = await research_agent.query("Research quantum computing")
report = await writing_agent.query(f"Write report: {research}")
```

### 🎯 **TOXO v2.0 Full Power – Quality Scoring & Query Intelligence**
```python
from toxo import ToxoLayer
from toxo.core import classify_query, analyze_response, compute_domain_confidence, should_use_layer, compute_info_density, QUALITY_WEIGHTS

# Classify query type (factual, procedural, comparison, technical, vague)
qtype = classify_query("how to dial in espresso", "coffee")  # -> "procedural"
qtype = classify_query("compare aeropress vs v60", "coffee")  # -> "comparison"

# Should you use the layer for this query? (domain confidence)
use_layer, confidence = should_use_layer("random trivia question", "finance", threshold=0.6)

# Analyze response quality with expert-weighted scoring
scores = analyze_response(response_text, query, domain="linkedin")

# Domain confidence and info density
conf = compute_domain_confidence("espresso ratio", "coffee")
density = compute_info_density(response_text, query, domain="finance")

# Layer automatically uses: response depth, query-type instructions, compression
response = layer.query_sync("Compare A vs B", response_depth="concise")  # Auto-formats comparison
```

## TOXO Python Library API Reference

### Core Methods

#### `ToxoLayer.load(path)`
Load a trained smart layer from `.toxo` file.
```python
layer = ToxoLayer.load("path/to/domain_expert.toxo")
```

#### `layer.setup_api_key(api_key, model, provider)`
Connect smart layer to any LLM API with model selection.
```python
# Gemini (default)
layer.setup_api_key("your_gemini_key", "gemini-2.5-flash-lite", "gemini")

# OpenAI GPT
layer.setup_api_key("your_openai_key", "gpt-4", "openai")

# Claude
layer.setup_api_key("your_claude_key", "claude-3.5-sonnet", "claude")
```

#### `layer.query(question, context=None, response_depth=None, **kwargs)`
Enhanced query with smart layer processing.
```python
response = layer.query_sync("Domain-specific question")

# With additional context
response = layer.query_sync(
    "Analyze this data", 
    context={"user_role": "analyst", "priority": "high"}
)

# v2.0: Response depth - concise, balanced, or detailed
response = layer.query_sync("Quick tip?", response_depth="concise")    # 1-3 sentences
response = layer.query_sync("Compare X vs Y", response_depth="balanced")  # Auto-escalates for comparisons
response = layer.query_sync("Full guide please", response_depth="detailed")
```

#### `layer.query_async(question, context=None)`
Asynchronous query for high-performance applications.
```python
response = await layer.query("Your question")      # preferred
response = await layer.query_async("Your question") # alias
```

#### `layer.query_sync(question, ...)`
Synchronous wrapper for `query(...)`.
```python
response = layer.query_sync("Your question")
```

### Information & Analytics

#### `layer.get_info()`
Get comprehensive layer information.
```python
info = layer.get_info()
print(f"Domain: {info['domain']}")
print(f"Performance Score: {info['performance_score']}")
```

#### `layer.get_capabilities()`
Discover layer capabilities.
```python
capabilities = layer.get_capabilities()
print(capabilities)
```

#### `layer.get_performance_metrics()`
Monitor smart layer performance.
```python
metrics = layer.get_performance_metrics()
print(f"Response Quality: {metrics['avg_quality_score']}")
```

## Creating Smart Layers

### Training Process on ToxoTune Platform

1. **🎯 Domain Selection**: Choose your area of expertise
2. **📚 Data Upload**: Provide domain-specific examples  
3. **🏋️ Smart Layer Training**: Advanced algorithms create your layer
4. **📦 Download**: Get your trained `.toxo` file
5. **🚀 Deploy**: Use with any LLM via this Python library

### Example Training Data

**Financial Advisory Layer:**
- "Should I diversify my portfolio?" → Expert diversification advice
- "Impact of inflation on investments?" → Inflation-hedging strategies
- "Best retirement planning approach?" → Comprehensive retirement guidance

**Legal Expert Layer:**
- "Contract risk analysis needed" → Detailed legal risk assessment
- "Compliance requirements review" → Regulatory compliance guidance
- "Intellectual property questions" → IP law expert consultation

## Domain Expert Examples

### 🏦 Financial Expert with Different Models
```python
finance_layer = ToxoLayer.load("financial_advisor.toxo")

# Using Gemini (recommended)
finance_layer.setup_api_key("your_gemini_key", "gemini-2.5-flash-lite", "gemini")
advice = finance_layer.query_sync("Portfolio allocation for retirement")

# Using GPT-4
finance_layer.setup_api_key("your_openai_key", "gpt-4", "openai")
advice = finance_layer.query_sync("Portfolio allocation for retirement")

# Using Claude
finance_layer.setup_api_key("your_claude_key", "claude-3.5-sonnet", "claude")
advice = finance_layer.query_sync("Portfolio allocation for retirement")
# Output: Expert financial planning with risk assessment
```

### ⚖️ Legal Expert with Model Selection
```python
legal_layer = ToxoLayer.load("legal_advisor.toxo")

# Choose the best model for legal analysis
legal_layer.setup_api_key("your_api_key", "gpt-4", "openai")
analysis = legal_layer.query_sync("Review this contract for issues")
# Output: Comprehensive legal analysis with risk identification
```

### 🔬 Research Assistant with Multiple Models
```python
research_layer = ToxoLayer.load("research_assistant.toxo")

# Use Claude for research (excellent at analysis)
research_layer.setup_api_key("your_claude_key", "claude-3.5-sonnet", "claude")
review = research_layer.query_sync("Latest developments in quantum computing")
# Output: Detailed research summary with current insights
```

### 💻 Code Expert with Model Flexibility
```python
code_layer = ToxoLayer.load("python_expert.toxo")

# Use GPT-4 for code analysis (excellent at programming)
code_layer.setup_api_key("your_openai_key", "gpt-4", "openai")
review = code_layer.query_sync("Optimize this function for performance")
# Output: Expert code analysis with optimization recommendations
```

## Advanced Usage Patterns

### Context-Aware Processing
```python
# Rich context for enhanced responses
context = {
    "user_profile": {
        "role": "portfolio_manager",
        "experience": "senior"
    },
    "session_data": {
        "previous_topics": ["risk_assessment", "market_analysis"]
    }
}

response = layer.query_sync("Investment recommendation", context=context)
```

### Batch Processing
```python
# Process multiple queries efficiently
queries = [
    "Analyze AAPL performance",
    "Tech sector risk assessment", 
    "Q4 2024 market outlook"
]

results = []
for query in queries:
    result = await layer.query(query)
    results.append(result)
```

## Installation & Requirements

### Standard Installation
```bash
pip install toxo
```

### Optional extras (recommended)

```bash
pip install "toxo[openai]"        # OpenAI provider support
pip install "toxo[claude]"        # Anthropic provider support
pip install "toxo[rag]"           # Vector store + retrieval
pip install "toxo[vision]"        # Optional local document/image tooling
pip install "toxo[auth]"          # JWT + bcrypt
pip install "toxo[distributed]"   # Redis-backed features
pip install "toxo[enterprise]"    # Monitoring/telemetry (optional)
pip install "toxo[full]"          # Everything (largest install)
```

### Installation with Specific LLM Providers
```bash
# For OpenAI GPT models
pip install toxo[openai]

# For Claude models
pip install toxo[claude]

# For all providers
pip install toxo[full]
```

### Development Installation
```bash
pip install toxo[dev]
```

### System Requirements
- **Python**: 3.9+ (3.10+ recommended)
- **Memory**: 4GB RAM minimum
- **Internet**: Required for LLM API calls
- **API Keys**: Supported LLM provider account

### Supported LLM Providers
- ✅ **Google Gemini** (Recommended - included by default)
  - `gemini-2.5-flash-lite`, `gemini-1.5-pro`, `gemini-1.5-flash`
- ✅ **OpenAI GPT** (Install with `pip install toxo[openai]`)
  - `gpt-4`, `gpt-4o`, `gpt-3.5-turbo`
- ✅ **Anthropic Claude** (Install with `pip install toxo[claude]`)
  - `claude-3.5-sonnet`, `claude-3-opus`, `claude-3-haiku`
- 🔄 **Local Models** (Coming soon)

## Performance Benefits

### Cost Comparison
- **Traditional Fine-tuning**: $10,000-$100,000+ per domain
- **TOXO Smart Layers**: $5-$500 per domain
- **Savings**: Up to 1000x cost reduction

### Time Comparison  
- **Traditional Fine-tuning**: Days to weeks
- **TOXO Smart Layers**: Minutes to hours
- **Speed**: Up to 500x faster deployment

### Quality Results
- **Performance**: 95-98% of fine-tuned model quality
- **Consistency**: Superior response reliability
- **Adaptability**: Continuous improvement from feedback

## Community & Support

### 📚 Resources
- **Documentation**: [TOXO docs](https://toxotune.github.io/toxo-docs)
- **Providers**: [Live multi-provider guide](https://toxotune.github.io/toxo-docs/providers.html)
- **API Reference**: See `README.md` + `toxo --help` + source modules under `toxo/`
- **Tutorials**: See `examples/` and `testing/`

### 💬 Community
- **Discord**: [discord.gg/toxotune](https://discord.gg/toxotune)
- **GitHub**: [github.com/toxotune/toxo-python](https://github.com/toxotune/toxo-python)
- **Stack Overflow**: Tag `toxo-python-library`

### 🏢 Enterprise
- **Enterprise Support**: [enterprise@toxotune.com](mailto:enterprise@toxotune.com)
- **Custom Solutions**: Large-scale deployments
- **Priority Support**: 24/7 technical assistance

## Frequently Asked Questions

### What is the TOXO Python Library?
The **TOXO Python Library** is a smart layer platform that enhances any black-box LLM with domain expertise, memory, and continuous learning capabilities without expensive retraining.

### How does TOXO differ from fine-tuning?
TOXO creates intelligent layers that attach to existing LLMs, achieving 95-98% of fine-tuned performance with 1000x cost reduction and universal LLM compatibility.

### Can I use TOXO with any LLM?
Yes! The **toxo python package** works with any LLM API including GPT, Gemini, Claude, and local models. Smart layers are completely LLM-agnostic.

### What's inside a .toxo file?
`.toxo` files contain trained smart layer components, memory systems, and configuration - everything needed to transform any LLM into a domain expert.

### Is TOXO production-ready?
Absolutely! The **TOXO Python Library** includes enterprise features like monitoring, scaling, security, and professional support options.

### How much training data do I need?
TOXO's smart layer training is extremely efficient - most domains need only 10-100 examples compared to thousands required for traditional approaches.

## Getting Started Checklist

- [ ] **Install**: `pip install toxo`
- [ ] **Sign Up**: Create account at [toxotune.com](https://toxotune.com)
- [ ] **Choose Domain**: Select your expertise area
- [ ] **Upload Examples**: Provide domain-specific data
- [ ] **Train Layer**: Create your smart layer
- [ ] **Download**: Get your `.toxo` file
- [ ] **Test**: Load and test with this Python library
- [ ] **Deploy**: Integrate into your application
- [ ] **Optimize**: Provide feedback for improvement

## License

The **TOXO Python Library** is proprietary software. See [LICENSE](LICENSE) file for details.

---

**TOXO Python Library** - Revolutionizing AI with Smart Layers 🧠⚡

*Transform any LLM into a domain expert with the power of smart layer technology*

**Ready to experience revolutionary LLM enhancement? Start with `pip install toxo` and join the smart layer revolution!**

---

**Keywords**: toxo python library, smart layer training, context augmented language models, calm, black-box llm enhancement, llm conversion, domain expert ai, toxo layer, python library, ai augmentation, llm enhancement, no llm retraining, toxo python package, ai layer training, toxo ai, toxo library