Chat
okra chat is the unified entry point for all chat. It routes automatically based on what you pass:
# General question (no document)
okra chat "what is a 10-K filing?"
# Single document
okra chat "how many pages?" --doc ocr-abc123
# Multi-document comparison
okra chat "compare revenue" --doc ocr-abc123,ocr-def456
# Collection
okra chat "summarize key metrics" -c "TSMC 2024 Filings"
| Flag | Description |
|---|
--doc <ids> | Comma-separated job IDs (ocr-*) |
-c, --collection <name> | Collection name or ID |
-m, --message <text> | Message (alternative to positional) |
--schema <json> | JSON Schema for structured output |
--model <model> | Model override |
--share | Generate a public share link |
--agent <type> | Agent type: canvas (LLM-driven canvas manipulation) |
--tools <type> | Tool mode (coming soon) |
-q, --quiet | Suppress spinners (just the answer) |
Routing
| What you pass | Mode | Backend |
|---|
No --doc, no -c | General chat | Fireworks (no document context) |
--doc ocr-XXX (single) | Single-doc | DocumentAgent DO /completion |
--doc ocr-XXX,ocr-YYY | Multi-doc | Lead agent + DO fan-out |
-c my-collection | Multi-doc | Same as above, resolves collection first |
--doc ocr-XXX --agent canvas | Canvas agent | CanvasAgent DO /canvas/completion |
General chat
Ask anything without a document — helpful for finance questions, OCR concepts, or quick lookups.
okra chat "what is EBITDA?"
okra chat "explain the difference between 10-K and 10-Q filings"
Single-document chat
Query a specific extracted document. The agent has tools to search text, query tables, and retrieve pages.
okra chat "what was total revenue?" --doc ocr-abc123
okra chat "list all tables on page 5" --doc ocr-abc123
Multi-document chat
Compare across documents. The lead agent fans out queries to each document and synthesizes results.
okra chat "compare the risk factors" --doc ocr-abc123,ocr-def456
# Or use a collection
okra chat "what are the common themes?" -c "Q4 Reports"
Canvas agent (--agent canvas)
Use --agent canvas for LLM-driven canvas manipulation — the agent can read and modify the document canvas using tool calls.
okra chat "highlight all revenue figures" --doc ocr-abc123 --agent canvas
okra chat "redact PII on page 3" --doc ocr-abc123 --agent canvas
DOCUMENT_AGENT_SHARED_SECRET to be set. Streams tool calls and text deltas to the terminal, with cost and tool-call count reported at the end.
--agent canvas only supports single-document mode. The first --doc ID is used if multiple are provided.
Structured output (--schema)
Pass a JSON Schema to get structured JSON responses. Works with single-doc mode.
# Inline schema
okra chat "get company info" --doc ocr-abc123 \
--schema '{"type":"object","properties":{"companyName":{"type":"string"}}}'
# Quiet mode — pure JSON, no spinners
okra chat "get company info" --doc ocr-abc123 \
--schema '{"type":"object","properties":{"companyName":{"type":"string"}}}' \
--quiet
{
"companyName": "Stock Code 00700 - Hong Kong Listed Equity Issuer"
}
Combine --schema with --quiet for pipeline-friendly output you can pipe straight into jq.
Parallel sessions
Run multiple single-doc queries in parallel — each runs independently.
QUESTION="What was total revenue for FY2023?"
for jobId in ocr-abc1 ocr-abc2 ocr-abc3; do
okra chat "$QUESTION" --doc "$jobId" > "results/${jobId}.json" &
done
wait
Legacy syntax
The old send subcommand still works:
okra chat send ocr-abc123 -m "What tables are in this document?"
Prefer the new syntax: okra chat "question" --doc ocr-abc123
