Metadata-Version: 2.4
Name: toxo
Version: 2.0.2
Summary: TOXO Python library: load a .toxo smart layer and attach it to Gemini/OpenAI/Claude to add domain expertise, memory, and improved responses without fine-tuning.
Home-page: https://toxotune.github.io/toxo-docs
Author: ToxoTune
Author-email: ToxoTune <support@toxotune.com>
Maintainer-email: ToxoTune <support@toxotune.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://toxotune.github.io/toxo-docs
Project-URL: Documentation, https://toxotune.github.io/toxo-docs
Project-URL: Repository, https://github.com/toxotune/toxo-docs
Project-URL: Bug Reports, https://github.com/toxotune/toxo-docs/issues
Project-URL: Changelog, https://toxotune.github.io/toxo-docs
Keywords: toxo,toxo python library,smart layer,calm,context augmented language models,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,ai smart layers,llm memory,ai enhancement
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Education
Classifier: Topic :: Office/Business
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-generativeai>=0.3.0
Requires-Dist: numpy
Requires-Dist: requests>=2.25.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: pydantic>=1.8.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: pyyaml>=5.4.0
Requires-Dist: loguru>=0.7.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
Requires-Dist: black>=21.0.0; extra == "dev"
Requires-Dist: flake8>=3.8.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: claude
Requires-Dist: anthropic>=0.7.0; extra == "claude"
Provides-Extra: security
Requires-Dist: keyring; extra == "security"
Requires-Dist: cryptography; extra == "security"
Provides-Extra: rag
Requires-Dist: sqlalchemy; extra == "rag"
Requires-Dist: chromadb>=0.4.0; extra == "rag"
Requires-Dist: scikit-learn>=1.0.0; extra == "rag"
Provides-Extra: vision
Requires-Dist: pillow; extra == "vision"
Requires-Dist: pytesseract; extra == "vision"
Requires-Dist: pdf2image; extra == "vision"
Requires-Dist: PyMuPDF; extra == "vision"
Requires-Dist: openpyxl; extra == "vision"
Requires-Dist: opencv-python; extra == "vision"
Provides-Extra: auth
Requires-Dist: PyJWT; extra == "auth"
Requires-Dist: bcrypt; extra == "auth"
Provides-Extra: payments
Requires-Dist: razorpay; extra == "payments"
Requires-Dist: python-dotenv; extra == "payments"
Provides-Extra: distributed
Requires-Dist: redis; extra == "distributed"
Provides-Extra: enterprise
Requires-Dist: redis; extra == "enterprise"
Requires-Dist: psutil; extra == "enterprise"
Requires-Dist: prometheus-client; extra == "enterprise"
Requires-Dist: opentelemetry-api; extra == "enterprise"
Requires-Dist: opentelemetry-sdk; extra == "enterprise"
Provides-Extra: full
Requires-Dist: openai>=1.0.0; extra == "full"
Requires-Dist: anthropic>=0.7.0; extra == "full"
Requires-Dist: sqlalchemy; extra == "full"
Requires-Dist: chromadb>=0.4.0; extra == "full"
Requires-Dist: sentence-transformers>=2.2.0; extra == "full"
Requires-Dist: scikit-learn>=1.0.0; extra == "full"
Requires-Dist: pandas>=1.3.0; extra == "full"
Requires-Dist: openpyxl; extra == "full"
Requires-Dist: PyJWT; extra == "full"
Requires-Dist: bcrypt; extra == "full"
Requires-Dist: redis; extra == "full"
Requires-Dist: razorpay; extra == "full"
Requires-Dist: python-dotenv; extra == "full"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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.

## 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

### Install the TOXO Python Package

```bash
pip install toxo
```

The **toxo python library** provides everything you need to create Context Augmented Language Models (CALM).

### Install by use case (recommended)

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
- **CLI**: `toxo check/info/validate/test/install`
- **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.

### 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:

```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 install
```

## 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), minimal local deps.
- **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)
- **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
