Metadata-Version: 2.4
Name: toxo-cloud
Version: 0.1.3
Summary: Lightweight TOXO Cloud client and CLI for .toxo layers
Author-email: ToxoTune <support@toxotune.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://toxotune.com
Project-URL: Documentation, https://toxotune.github.io/toxo-docs
Project-URL: Source, https://github.com/spiderdev27/toxo-cloud
Project-URL: Issues, https://github.com/spiderdev27/toxo-cloud/issues
Keywords: toxo,toxo-cloud,llm,multimodal,rag,agent,gemini,python-client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: pyyaml>=5.4.0

# toxo-cloud

Lightweight Python client and CLI for TOXO Cloud — use TOXO without heavy local dependencies.

---

## What is TOXO?

**TOXO** is a smart layer platform that turns any black-box LLM (Gemini, GPT, Claude) into a **Context Augmented Language Model (CALM)** — giving it domain expertise, memory, and better outputs **without fine-tuning**.

### The idea

- **Base LLM** (Gemini, GPT, Claude) = general intelligence
- **`.toxo` layer** = domain specialization, memory, rules, soft prompt
- **TOXO runtime** = runs the layer on top of the LLM

`.toxo` files are small (tens of KB): soft prompts, memory state, and configuration. No LLM weights. The heavy compute stays on your LLM provider.

### Why TOXO vs fine-tuning

| Fine-tuning | TOXO |
|-------------|------|
| $10k–$100k+ per domain | $5–$500 |
| Days to weeks | Minutes to hours |
| GPU clusters | API-based, no GPUs |
| One model per domain | Unlimited layers |
| Permanent changes | Remove layer anytime |
| Model-specific | Works with any LLM |

---

## TOXO features and capabilities

TOXO provides:

### Smart layer training
- Train domain experts from Q&A examples and documents
- No GPUs — uses your LLM API
- Derives static rules, contexts, and example phrases from your data
- Output: portable `.toxo` layer you can run anywhere

### Advanced memory
- Persistent knowledge storage and retrieval
- Context-aware learning
- Conversation history and domain expertise
- Memory state baked into the `.toxo` layer

### Quality enhancement
- Response depth control: concise, balanced, detailed
- Feedback loop: rate responses, add suggestions
- Query-type intelligence (factual, procedural, comparison, etc.)
- Domain-specific output refinement

### Multimodal understanding
- Images: PNG, JPG, screenshots
- Documents: PDF, DOCX, HTML, TXT, CSV, RTF, EPUB
- Direct-to-Gemini: no local rendering deps
- MIME auto-inference for documents and images

### RAG (retrieval-augmented generation)
- Index documents into a vector store
- Query with grounded answers and citations
- Works with cloud or local index

### Multi-agent orchestration
- Pipeline, hierarchical, peer-to-peer coordination
- Agents can ask each other questions (nudges)
- Dynamic planning: auto-generate execution plan from goal
- Final synthesis pass merges step outputs into one artifact

### Universal LLM support
- Gemini (recommended)
- OpenAI GPT
- Anthropic Claude

### No-code layer creation
- Create layers at [toxotune.com](https://toxotune.com)
- Upload examples, download `.toxo`
- Use with any TOXO runtime (cloud or local)

---

## toxo-cloud: thin client for TOXO Cloud

`toxo-cloud` is a **lightweight Python client** that talks to TOXO Cloud. Your `.toxo` layer and API key stay on your side; all heavy processing runs in the cloud.

### What toxo-cloud supports (via TOXO Cloud)

| Capability | Endpoint | Python method |
|------------|----------|---------------|
| Text query | `POST /v1/query` | `client.query()` |
| Multimodal (image/document) | `POST /v1/query_multimodal` | `client.query_multimodal()` |
| Feedback | `POST /v1/feedback` | `client.feedback()` |
| Train from data | `POST /v1/train_from_data` | `client.train_from_data()` |
| Extract contexts | `POST /v1/train/extract_contexts` | `client.train_extract_contexts()` |
| RAG index | `POST /v1/rag/index` | `client.rag_index()` |
| RAG query | `POST /v1/rag/query` | `client.rag_query()` |
| Agent workflow | `POST /v1/agent/run` | `client.agent_run()` |

### When to use toxo-cloud

- You want **minimal install** (requests + pyyaml)
- You prefer **cloud execution** — no local LLM, doc conversion, or vector store
- You have a `.toxo` layer and want to call TOXO Cloud from Python or the CLI

### Alternative: local runtime

The `toxo` package (`pip install toxo`) provides the full local runtime: `ToxoLayer`, training, RAG, agents — all on your machine. Use it when you need offline execution or heavy local workflows.

### End-to-end flow with toxo-cloud

1. Create a `.toxo` layer (train via `train_from_data`, use toxotune.com, or use an existing layer)
2. Call TOXO Cloud with `toxo-cloud` (Python or CLI)
3. Get domain-aware responses; optionally send feedback or retrain

---

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