toxo-cloud 0.1.4

Lightweight TOXO Cloud client and CLI for .toxo layers

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
• 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()
Resume training	POST /v1/train_resume_from_data	client.train_resume_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

pip install -U toxo-cloud

Quick start

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

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

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

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

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(...)

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

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

# 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

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

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

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

Cloud RAG

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

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

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.

from toxo_cloud import ToxoCloudClient

client = ToxoCloudClient(api_key="YOUR_GEMINI_API_KEY")

1) GET / (service root)

info = client.root()
print(info)

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

2) GET /health (health check)

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

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

3) POST /v1/query (text query)

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)

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

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)

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_resume_from_data (resume training from an existing .toxo)

This continues training from an existing layer (preserves its learned state) and applies the new examples/contexts on top.

resume_result = client.train_resume_from_data(
    base_layer="finance_trained.toxo",
    description="Finance helper for beginner investing questions (v2).",
    out_path="finance_trained_v2.toxo",
    examples=[
        {"input": "What is diversification?", "output": "Spreading risk across asset types."},
        {"input": "Explain compounding.", "output": "Interest on interest over time."},
    ],
    contexts=[
        "When the user asks for investing help, include risk + disclaimers.",
        "Prefer simple explanations for beginners unless they request details.",
    ],
    epochs=3,
    llm_provider="gemini",
    llm_model="gemini-2.5-flash-lite",
)
print(resume_result.get("summary", {}))

8) POST /v1/train/extract_contexts (extract contexts from docs)

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

9) POST /v1/rag/index (index documents for retrieval)

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)

10) POST /v1/rag/query (query indexed docs)

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

11) POST /v1/agent/run (multi-agent workflow)

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

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-resume-from-data --base-layer finance_trained.toxo --description "Finance helper (v2)" --out finance_trained_v2.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.