# toxo-cloud

Lightweight Python client and CLI for TOXO Cloud.

`toxo-cloud` is a connector package:
- your `.toxo` layer stays with you
- your API key stays with you
- heavy runtime (query, multimodal, training, RAG, agents) runs in TOXO Cloud

## What is TOXO?

TOXO is a smart layer platform for LLMs. Instead of fine-tuning the full model, you train or use a portable `.toxo` layer that adds domain behavior, memory signals, and task guidance on top of provider models like Gemini.

In short:
- **Base LLM** gives general intelligence
- **`.toxo` layer** gives domain specialization
- **TOXO Cloud** executes the runtime workflows at scale

This keeps your client lightweight while still supporting advanced features like multimodal understanding, retrieval-augmented generation (RAG), training from examples, and multi-agent orchestration.

## How TOXO is used in practice

Common production patterns:
- **Domain expert assistants**: support, finance, legal, healthcare, product operations
- **Document understanding**: summarize PDFs, analyze screenshots, extract structured insights
- **RAG systems**: index internal docs and answer grounded questions with context
- **Workflow automation**: run multi-agent plans for research, drafting, validation, and synthesis

High-level flow:
1. Create or obtain a `.toxo` layer
2. Send layer + question/input through `toxo-cloud`
3. Receive a domain-aware response from TOXO Cloud runtime
4. Optionally send feedback or retrain from data to improve outcomes

## Functionality parity with main TOXO package

Using the main `README.md` as reference:

- **Supported in `toxo-cloud` (cloud runtime):**
  - text query (`/v1/query`)
  - multimodal query for images/documents (`/v1/query_multimodal`)
  - feedback loop (`/v1/feedback`)
  - training from data (`/v1/train_from_data`)
  - context extraction from docs (`/v1/train/extract_contexts`)
  - RAG index and query (`/v1/rag/index`, `/v1/rag/query`)
  - multi-agent orchestration (`/v1/agent/run`)

- **Main `toxo` package local-only capabilities (not `toxo-cloud`):**
  - local runtime (`ToxoLayer.query_sync/query`) without cloud calls
  - offline scoring utilities (`classify-query`, `analyze-response`)
  - local document conversion and local processing pipeline controls
  - local CLI workflows that execute fully on your machine

This means `toxo-cloud` gives you broad cloud feature coverage while keeping the install lightweight.

## Why use `toxo-cloud`?

- **Simple integration**: Python API + CLI
- **No heavy local runtime**: cloud handles expensive processing
- **Portable layer artifacts**: `.toxo` files work across workflows
- **Fast adoption path**: start with text query, expand to multimodal/RAG/agents

## Who should use this package?

`toxo-cloud` is best when you want:
- a thin Python client for TOXO Cloud APIs
- minimal local dependencies
- cloud execution for query, multimodal, training, RAG, and agent orchestration

If you want the full local runtime stack, use the main `toxo` package.

## Install

```bash
pip install -U toxo-cloud
```

## Quick start

### Python

```python
from toxo_cloud import ToxoCloudClient

client = ToxoCloudClient(api_key="YOUR_GEMINI_API_KEY")

answer = client.query(
    layer="finance_expert.toxo",
    question="Explain inflation in simple words.",
)
print(answer)
```

### CLI

```bash
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

toxo-cloud health
toxo-cloud query finance_expert.toxo "Explain inflation in simple words."
```

## Use-case quick recipes

### 1) Build a domain expert API quickly

```python
from toxo_cloud import ToxoCloudClient

client = ToxoCloudClient()
response = client.query(
    layer="my_support_expert.toxo",
    question="How should we handle a failed payment escalation?",
    response_depth="balanced",
)
print(response)
```

### 2) Analyze documents and images

```python
doc_answer = client.query_multimodal(
    layer="ops_expert.toxo",
    question="Summarize this policy and list action items.",
    document_path="policy.pdf",
)

image_answer = client.query_multimodal(
    layer="ops_expert.toxo",
    question="Extract metrics from this dashboard screenshot.",
    image_path="dashboard.png",
)
```

### 3) Add cloud RAG over your docs

```python
client.rag_index(
    index_id="handbook_v1",
    docs=["docs/employee_handbook.pdf", "docs/benefits.md"],
    domain="hr",
)

result = client.rag_query(
    layer="hr_assistant.toxo",
    index_id="handbook_v1",
    question="What is our parental leave policy?",
)
print(result["response"])
```

## Authentication

`toxo-cloud` resolves API keys in this order:
1. explicit `api_key=...` argument
2. `GEMINI_API_KEY`
3. `GOOGLE_API_KEY`

If none is available, requests that require provider access will fail.

## Python API

### `ToxoCloudClient(...)`

```python
from toxo_cloud import ToxoCloudClient
client = ToxoCloudClient(api_key="...", timeout=120)
```

- `api_key`: optional, can come from env vars
- `timeout`: default HTTP timeout in seconds

### Text query

```python
response = client.query(
    layer="my_layer.toxo",
    question="What can you help with?",
    provider="gemini",
    model="gemini-2.5-flash-lite",
    response_depth="balanced",  # concise | balanced | detailed
)
```

### Multimodal query (image or document)

Exactly one source is required:
- `image_path`
- `document_path`
- `image_base64`
- `document_base64`

```python
# Document from path (mime type auto-inferred)
doc_resp = client.query_multimodal(
    layer="my_layer.toxo",
    question="Summarize this report in 5 bullets.",
    document_path="report.pdf",
)

# Image from base64
img_resp = client.query_multimodal(
    layer="my_layer.toxo",
    question="Extract key values from this screenshot.",
    image_base64="iVBORw0KGgoAAAANSUhEUgAA...",
    mime_type="image/png",
)
```

Notes:
- `document_path` now works without explicit `mime_type` (auto inference).
- Raw base64 is automatically wrapped into a `data:<mime>;base64,...` format.

### Feedback

```python
result = client.feedback(
    layer="my_layer.toxo",
    question="Original user question",
    response="Model answer",
    rating=8.5,
    suggestions=["Be more concise", "Include caveats"],
)
```

### Train from data

```python
examples = [
    {"input": "What is inflation?", "output": "Inflation is a rise in prices over time."},
]

result = client.train_from_data(
    description="Finance helper for basic personal finance questions.",
    out_path="finance_layer.toxo",
    examples=examples,
    epochs=3,
    llm_provider="gemini",
    llm_model="gemini-2.5-flash-lite",
)
```

### Extract contexts from documents

```python
result = client.train_extract_contexts(
    docs=["docs/policy.md", "docs/faq.pdf"],
    index_id="billing_contexts",
    domain="billing",
)
```

### Cloud RAG

```python
index_result = client.rag_index(
    index_id="product_docs_v1",
    docs=["docs/guide.md", "docs/faq.pdf"],
    domain="product",
)

query_result = client.rag_query(
    layer="my_layer.toxo",
    index_id="product_docs_v1",
    question="What are the cancellation rules?",
    top_k=5,
)
```

### Agent orchestration

```python
result = client.agent_run(
    config="agent_config.yaml",
    layer_map={
        "research": "research_expert.toxo",
        "writer": "writer_expert.toxo",
    },
    llm_provider="gemini",
    llm_model="gemini-2.5-flash-lite",
)

print(result.get("final"))
```

## CLI reference

```bash
toxo-cloud --help
```

Core commands:
- `toxo-cloud root`
- `toxo-cloud health`
- `toxo-cloud query <layer> "<question>"`
- `toxo-cloud ask-doc <layer> <document> "<question>"`
- `toxo-cloud ask-image <layer> <image> "<question>"`
- `toxo-cloud feedback <layer> "<question>" "<response>" [--rating 8.5] [--suggestion "..."]`

Training and retrieval:
- `toxo-cloud train-auto "<description>" --out layer.toxo`
- `toxo-cloud train-from-data --description "..." --out layer.toxo --examples-jsonl examples.jsonl --contexts-file contexts.txt`
- `toxo-cloud train-extract-contexts --docs docs/ --recursive --pattern "*.md"`
- `toxo-cloud rag-index --index-id docs_v1 --docs docs/ --recursive`
- `toxo-cloud rag-query --layer layer.toxo --index-id docs_v1 --question "..." --top-k 5`

Agents:
- `toxo-cloud agent-run --config agent_config.yaml --layer research=research.toxo --layer writer=writer.toxo`

## Endpoint coverage

`toxo-cloud` supports:
- `GET /`
- `GET /health`
- `POST /v1/query`
- `POST /v1/query_multimodal`
- `POST /v1/feedback`
- `POST /v1/train_from_data`
- `POST /v1/train/extract_contexts`
- `POST /v1/rag/index`
- `POST /v1/rag/query`
- `POST /v1/agent/run`

## Endpoint-by-endpoint examples

All examples below use the `toxo-cloud` Python client. For raw HTTP testing, `curl` examples are also included.

```python
from toxo_cloud import ToxoCloudClient

client = ToxoCloudClient(api_key="YOUR_GEMINI_API_KEY")
```

### 1) `GET /` (service root)

```python
info = client.root()
print(info)
```

```bash
curl -s https://toxo-api-cwsddklqcq-uc.a.run.app/
```

### 2) `GET /health` (health check)

```python
health = client.health()
print(health)  # {"status": "ok"}
```

```bash
curl -s https://toxo-api-cwsddklqcq-uc.a.run.app/health
```

### 3) `POST /v1/query` (text query)

```python
response = client.query(
    layer="finance_expert.toxo",
    question="Explain inflation in 3 bullets.",
    provider="gemini",
    model="gemini-2.5-flash-lite",
    response_depth="balanced",
)
print(response)
```

### 4) `POST /v1/query_multimodal` (image or document query)

```python
# Document path
doc_response = client.query_multimodal(
    layer="finance_expert.toxo",
    question="Summarize this document in 5 bullets.",
    document_path="report.pdf",
)
print(doc_response)

# Image path
img_response = client.query_multimodal(
    layer="finance_expert.toxo",
    question="What key numbers are visible in this image?",
    image_path="dashboard.png",
)
print(img_response)
```

### 5) `POST /v1/feedback` (quality feedback)

```python
result = client.feedback(
    layer="finance_expert.toxo",
    question="What is inflation?",
    response="Inflation is the rise in prices over time.",
    rating=9.0,
    suggestions=["Add one real-world example."],
)
print(result)
```

### 6) `POST /v1/train_from_data` (train and download `.toxo`)

```python
examples = [
    {"input": "What is compound interest?", "output": "Interest on principal plus accumulated interest."},
    {"input": "What is diversification?", "output": "Spreading risk across asset types."},
]

train_result = client.train_from_data(
    description="Finance helper for beginner investing questions.",
    out_path="finance_trained.toxo",
    examples=examples,
    epochs=3,
    llm_provider="gemini",
    llm_model="gemini-2.5-flash-lite",
)
print(train_result.get("summary", {}))
```

### 7) `POST /v1/train/extract_contexts` (extract contexts from docs)

```python
extract_result = client.train_extract_contexts(
    docs=["docs/policies.md", "docs/faq.pdf"],
    index_id="finance_contexts",
    domain="finance",
)
print(extract_result)
```

### 8) `POST /v1/rag/index` (index documents for retrieval)

```python
index_result = client.rag_index(
    index_id="finance_docs_v1",
    docs=["docs/handbook.pdf", "docs/fees.md"],
    domain="finance",
    layer="finance_expert.toxo",  # optional
)
print(index_result)
```

### 9) `POST /v1/rag/query` (query indexed docs)

```python
rag_result = client.rag_query(
    layer="finance_expert.toxo",
    index_id="finance_docs_v1",
    question="What are the account closure charges?",
    top_k=5,
    llm_provider="gemini",
    llm_model="gemini-2.5-flash-lite",
    response_depth="balanced",
)
print(rag_result.get("response", rag_result))
```

### 10) `POST /v1/agent/run` (multi-agent workflow)

```python
agent_config = {
    "goal": "Create a concise customer-facing refund policy summary.",
    "coordination": "pipeline",
    "agents": [
        {"id": "research", "layer": "unused", "role": "Policy researcher"},
        {"id": "writer", "layer": "unused", "role": "Customer-facing writer"},
    ],
    "steps": [
        {"agent": "research", "question": "Extract key policy constraints and timelines."},
        {"agent": "writer", "question": "Use {{prev}} and produce a concise final summary."},
    ],
}

agent_result = client.agent_run(
    config=agent_config,
    layer_map={
        "research": "finance_expert.toxo",
        "writer": "finance_expert.toxo",
    },
    llm_provider="gemini",
    llm_model="gemini-2.5-flash-lite",
)
print(agent_result.get("final", agent_result))
```

### CLI one-liners for each endpoint

```bash
toxo-cloud root
toxo-cloud health
toxo-cloud query finance_expert.toxo "Explain inflation briefly."
toxo-cloud ask-doc finance_expert.toxo ./report.pdf "Summarize this report."
toxo-cloud ask-image finance_expert.toxo ./chart.png "What trend is shown?"
toxo-cloud feedback finance_expert.toxo "What is inflation?" "Inflation is..." --rating 8.5 --suggestion "Add an example"
toxo-cloud train-auto "Finance helper for beginner users" --out finance_auto.toxo
toxo-cloud train-from-data --description "Finance helper" --out finance_data.toxo --examples-jsonl examples.jsonl --contexts-file contexts.txt
toxo-cloud train-extract-contexts --docs docs/ --recursive --pattern "*.md"
toxo-cloud rag-index --index-id finance_docs_v1 --docs docs/ --recursive
toxo-cloud rag-query --layer finance_expert.toxo --index-id finance_docs_v1 --question "What are account fees?"
toxo-cloud agent-run --config agent_config.yaml --layer research=finance_expert.toxo --layer writer=finance_expert.toxo
```

## SEO / GEO friendly search intents

This package is relevant for queries like:
- **TOXO Python client**
- **how to use .toxo file in Python**
- **smart layer for LLMs**
- **Context Augmented Language Models (CALM)**
- **Gemini document and image analysis Python**
- **Python RAG client with cloud index**
- **multi-agent LLM workflow Python**
- **lightweight LLM cloud connector package**

## TOXO FAQ

### Does `toxo-cloud` train foundation models?

No. TOXO uses smart layers (`.toxo`) that guide and specialize provider models.

### Do I need to host my own inference servers?

No for this package. `toxo-cloud` is a thin client and the runtime executes in TOXO Cloud.

### Can I use this for multimodal and RAG workflows?

Yes. `toxo-cloud` supports multimodal endpoints plus cloud RAG index/query endpoints.

### Where should I start?

Start with `query(...)`, then add:
- `query_multimodal(...)` for documents/images
- `rag_index(...)` + `rag_query(...)` for grounded retrieval
- `agent_run(...)` for orchestrated multi-agent workflows

## Troubleshooting

- **401/403 or provider errors**: verify `GEMINI_API_KEY` / `GOOGLE_API_KEY`.
- **Layer not found**: check layer path; the client reads layer bytes locally before sending.
- **Multimodal failures**: pass exactly one source (`image_path`, `document_path`, `image_base64`, `document_base64`).
- **YAML config errors for agents**: ensure `pyyaml` is installed (included by default dependency).

## License

Proprietary. See repository license terms.
