Tengu Brain

one natural-language request; Brain plans the work, calls the right FIRM tools server-side, and returns a synthesized answer — you write no tool-calling code.

What Brain is#

The FIRM data API gives you structured financial data and leaves the orchestration to you. Brain holds the full FIRM tool suite and decides — per request — which endpoints to call, in what order, and how to fuse the results. A single prompt like "What did Nancy Pelosi trade recently, and how did NVDA move around those dates?" becomes, internally, a congressional-trades lookup + a market-data pull + a synthesis — none of which you orchestrate.

Because Brain speaks the OpenAI and Anthropic wire formats, you point your existing SDK at it and change only the base_url and model. No new client, no tool schemas to maintain.

Requirements#

Brain requires the Enterprise plan — it has autonomous access to the entire FIRM product suite, so it is bundled at the tier that includes every product. A request without Brain entitlement returns 403 CHAT_ENTITLEMENT_REQUIRED.

Brain does not use the FIRM error envelope. It answers with RFC 7807 application/problem+json, so parse code/detail here rather than FIRM's error/detail. A Free-plan key calling POST /v1/chat/completions receives this error shape:

1{2  "type": "tengu:problem:chat-entitlement-required",3  "title": "Chat entitlement required",4  "status": 403,5  "code": "CHAT_ENTITLEMENT_REQUIRED",6  "detail": "Chat is a Wealthnow Platform product and requires a separate Brain entitlement. A FIRM data API key cannot start Chat.",7  "instance": "req/example-request-id",8  "plan": "free",9  "required": "brain",10  "product": "platform_chat",11  "upgrade_url": "https://app.wealthnow.io"12}

The _parse_error helper in Quickstart: Production client already reads this shape as well as FIRM's, so one client handles both surfaces.

Endpoints#

Both support streaming with stream: true. Brain is stateless per request — there are no server-side sessions; you carry the conversation by sending the full messages[] history on every turn, exactly like OpenAI and Anthropic.

Using Brain#

OpenAI Python SDK#

Point the official SDK at Brain — only base_url and model change:

1import os2from openai import OpenAI3 4client = OpenAI(api_key=os.environ["TENGU_API_KEY"], base_url="https://brain.wealthnow.io/v1")5 6resp = client.chat.completions.create(7    model="brain",8    messages=[{"role": "user",9               "content": "What did Nancy Pelosi trade recently, and how did NVDA move around those dates?"}],10)11print(resp.choices[0].message.content)

Raw HTTP (curl)#

1curl https://brain.wealthnow.io/v1/chat/completions \2  -H "Authorization: Bearer $TENGU_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "model": "brain",6    "messages": [{"role": "user", "content": "Summarize unusual options flow in TSLA today and any related dark-pool prints."}]7  }'

Streaming#

1stream = client.chat.completions.create(2    model="brain",3    messages=[{"role": "user", "content": "Give me a bull vs bear case on PLTR with the latest 13F changes."}],4    stream=True,5)6for chunk in stream:7    delta = chunk.choices[0].delta.content8    if delta:9        print(delta, end="", flush=True)

Anthropic shape#

If your stack speaks the Anthropic Messages API, use /v1/messages unchanged:

1curl https://brain.wealthnow.io/v1/messages \2  -H "Authorization: Bearer $TENGU_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "model": "brain",6    "max_tokens": 1024,7    "messages": [{"role": "user", "content": "Which private AI companies raised the largest rounds this quarter?"}]8  }'

Limit output#

Both compatibility endpoints accept an optional max_tokens integer from 1 through 64,000. Invalid values return 400 INVALID_MAX_TOKENS before a provider request starts. Omitting the field preserves the model's defaults.

The limit applies to each provider response within the turn. It does not cap input tokens, the number of tool calls, total tokens across multiple provider responses, or dollar cost. Limits of 1,024 or lower disable thinking for that request so its thinking budget cannot exceed the output limit. A short answer can still require substantial input and tool context.

Billing#

Brain debits the same credit wallet as FIRM after a successful, usable response finishes writing. The completed turn's authoritative USD cost is converted at 2,500 credits per dollar, rounded up:

credits = ceil(final turn cost in USD × 2500)

A turn is one metered event. Internal FIRM tool calls do not each incur a separate FIRM per-call debit. The final turn cost can include auxiliary model work, so do not calculate the charge from the response's displayed token counts alone.

The response's usage describes the main query's provider messages. In the OpenAI shape, prompt_tokens includes uncached input, cache reads, and cache writes. prompt_tokens_details.cached_tokens and cache_write_tokens identify the cache portions; total_tokens adds completion tokens. In the Anthropic shape, input_tokens, cache_read_input_tokens, and cache_creation_input_tokens remain separate. Final counters aggregate the main query's messages, but can omit auxiliary work included in the final USD cost.

Failed, interrupted, and empty turns do not incur a Brain debit. Missing or invalid final cost returns TURN_USAGE_UNAVAILABLE instead of an estimated charge. A confirmed zero final cost incurs no charge.

When the wallet is exhausted, Brain returns 402 usage_exceeded (top up or upgrade in the dashboard). Errors never debit credits.

Statelessness & context#

Brain keeps no server-side conversation state. To continue a conversation, resend the full messages[] history each turn — the same contract as OpenAI/Anthropic. This makes Brain horizontally scalable and safe to call from stateless environments (serverless, agents, cron).

Next steps#

• Quickstart: the Brain agent API — the fastest path to a first Brain call.
• Chat parity — optional conventions to make Brain feel like Tengu Chat.
• Pricing & credits — how completed-turn cost draws from the shared wallet.