toxo-cloud 0.1.2

Lightweight TOXO Cloud client and CLI for .toxo layers

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

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

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

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

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