docs/agent/usage.md

---
title: Agent Usage
summary: How to use TerraFin's agent-facing surfaces from Python, CLI, HTTP, and the hosted assistant widget.
read_when:
  - Using TerraFin as an agent tool
  - Choosing between stateless and hosted agent surfaces
  - Interpreting processing metadata
  - Finding the right transport for a workflow
---

# Agent Usage

TerraFin is most useful to agents when it stays on the same path as the product.

That means:

- market and macro responses use the same progressive-history rules as the chart stack
- indicator math matches the chart indicators
- chart-opening uses the same session semantics as the browser UI
- every research response includes `processing`

If you are maintaining the runtime itself, read [hosted-runtime.md](./hosted-runtime.md)
and [architecture.md](./architecture.md). This document is the usage guide.

## If you want to do X, use this tool

Scan this table **first** before reaching for `requests` / `urllib` /
`yfinance` / pandas-html / regex parsers. Every row below is already shipped
with rate-limit, retry, cache, and progressive-history handling.

| If you want to...                                          | Use this tool                                                       |
| ---------------------------------------------------------- | ------------------------------------------------------------------- |
| Resolve a ticker/name into a TerraFin route                | `resolve(query)`                                                    |
| Get a chart-ready OHLC series                              | `market_data(name, depth, view)`                                    |
| Get a one-asset snapshot (price action + indicators)       | `market_snapshot(name, depth, view, force_refresh=False)` — response `asof` is the ISO date of the last bar served; pass `force_refresh=True` only for time-sensitive snapshots (mid-session, freshly-closed bar) to bypass the 24h `yfinance.full` cache |
| Get company profile / valuation fields                     | `company_info(ticker)`                                              |
| Get earnings history (estimate / reported / surprise)      | `earnings(ticker)`                                                  |
| Get income / balance / cashflow statement                  | `financials(ticker, statement, period)`                             |
| List a ticker's recent 10-K / 10-Q / 8-K filings           | `sec_filings(ticker)`                                               |
| Get a single filing's TOC (no full body)                   | `sec_filing_document(ticker, accession, primaryDocument, form)`     |
| Pull one filing section's markdown body                    | `sec_filing_section(..., sectionSlug, form)`                        |
| Run DCF / reverse DCF / Graham / relative valuation        | `valuation(ticker, ...)` (see SKILL.md for turnaround inputs)       |
| Inspect FCF base candidates (3yr_avg / annual / TTM)       | `fcf_history(ticker, years)`                                        |
| Get S&P 500 index-level DCF                                | `sp500_dcf()`                                                       |
| Get 5y monthly beta vs mapped benchmark                    | `beta_estimate(ticker)`                                             |
| Get statistical risk profile (tail risk, drawdown, regime) | `risk_profile(name)`                                                |
| Run a fundamental quality / moat screen                    | `fundamental_screen(ticker)`                                        |
| Get guru portfolio holdings (Buffett / Marks / Druck.)     | `portfolio(guru)`                                                   |
| Get FRED-backed economic indicator series                  | `economic(indicators)`                                              |
| Get macro summary + chart-ready series                     | `macro_focus(name, depth, view)`                                    |
| Scan calendar events for a month                           | `calendar_events(year, month, categories, limit)`                   |
| Detect bubble (super-exp growth + log-periodic osc.)       | `lppl_analysis(name, depth, view)`                                  |
| Find chart-shape-similar historical episodes               | `similarity_search(ticker, universe, period, top_n)`                |
| Get market temperature signals                             | `fear_greed()`, `market_regime()`, `market_breadth()`, `trailing_forward_pe()` |
| Get top companies by market cap                            | `top_companies()`                                                   |
| Read the user's watchlist                                  | `watchlist()`                                                       |
| Get chart-matching technical indicators                    | `indicators(name, indicators, depth, view)`                         |
| Get named pattern signals matching the latest bar          | `patterns(name, depth, view)`                                       |
| Read which panel/form the user is currently looking at     | `current_view_context()` (hosted runtime only)                      |
| Open a chart artifact bound to the session                 | `open_chart(name)` (hosted runtime only)                            |
| List / authenticate / switch hosted models                 | `terrafin-agent models ...` (see [models.md](./models.md))          |
| Discover capability schemas programmatically               | `GET /openapi.json` — filter `paths` to `/agent/api/*`              |

Capability signatures with full parameter ranges and worked examples live in
[`skills/terrafin/SKILL.md`](https://github.com/KiUngSong/TerraFin/blob/main/skills/terrafin/SKILL.md).
The route summary further down this page is auto-generated and lists every
HTTP route.

## Don't roll your own

Reach for the TerraFin helper before hand-rolling any of the patterns below.
Each one has been a real source of breakage (rate-limit, cache miss,
parser inconsistency, hidden-API drift).

### SEC EDGAR — don't roll your own scrape

If you find yourself reaching for `urllib.request.urlopen("https://www.sec.gov/...")`,
regex-parsing the accession folder index, or stripping `<html>` tags by hand —
stop. The same content is one tool call away through the parsed + cached path:

| Manual approach (DON'T)                                              | TerraFin tool (DO)                                                                          |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `urlopen("https://www.sec.gov/Archives/edgar/data/<cik>/<acc>/")` to list exhibits | `sec_filing_document(ticker, accession, primaryDocument, form="8-K")` → `toc` carries `exhibit-991-press-release` / `exhibit-992-supplemental-material` slugs |
| `urlopen("https://www.sec.gov/.../q1fy27pr.htm")` to grab the earnings PR | `sec_filing_section(..., sectionSlug="exhibit-991-press-release", form="8-K")` → returns parsed markdown body |
| Strip `<p>` / `<table>` / `&nbsp;` with regex                        | already done — `sec_filing_section` returns clean markdown                                  |
| Strip the `/ix?doc=` viewer wrapper off `documentUrl`                | use `sec_filing_document` / `sec_filing_section` instead of dereferencing the URL yourself |

Why this matters:
- SEC rate-limits aggressively (~10 req/s per IP). The TerraFin helpers
  share a single `SECClient` with rate-limit + retry; raw `urllib` does not.
- Parsed markdown is cached 30 days under `sec.parsed`; raw fetches re-pull
  every newsletter run.
- Bypassing the cache risks SEC IP-banning the host.

The `form` arg is required for 8-K exhibit content — service defaults to
`"10-Q"`, and 8-Ks called without `form="8-K"` produce only the 4 KB cover
sheet stub (no exhibits appended). Pull `form` from
`sec_filings(...)["latestByForm"][...]["form"]` (or from any flat-list entry)
and pass it through every call.

### 8-K exhibits — don't bypass `fetch_and_parse_filing`

If you're tempted to call `download_filing(...)` then `parse_sec_filing(...)`
yourself for an 8-K, you'll get the 4 KB cover sheet with **no exhibits
appended**. The exhibit-appending logic lives only in
`fetch_and_parse_filing(cik, accession, doc, "8-K", include_images)`.

| Manual approach (DON'T)                                                                | TerraFin tool (DO)                                                                  |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `parse_sec_filing(download_filing(cik, acc, doc), "8-K")`                              | `fetch_and_parse_filing(cik, acc, doc, "8-K", include_images=False)` — appends every `EX-99.x` exhibit |
| Manually loop `list_filing_files()` → `download_exhibit()` → `parse_sec_filing()`      | `fetch_and_parse_filing(...)` — already does this with per-exhibit error markers    |
| Call `sec_filing_section` without `form="8-K"`                                         | always pass `form="8-K"` — service defaults to `"10-Q"`                             |

The agent-facing path (`sec_filing_section`) wraps `fetch_and_parse_filing`
under the cache; only fall through to `fetch_and_parse_filing` directly when
writing non-agent data-layer code (route handlers, batch ingestion).

### Model catalog — don't reach into `_PROVIDER_CATALOG`

The provider catalog is a public function, not a private dict.

| Manual approach (DON'T)                                                   | TerraFin tool (DO)                                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `from TerraFin.agent.models.management import _PROVIDER_CATALOG`          | `from TerraFin.agent.models.management import list_provider_catalog`     |
| `_PROVIDER_CATALOG["openai"].featured_model_refs`                         | `get_provider_catalog("openai").featured_model_refs`                     |
| Iterate the private dict to discover providers                            | `for entry in list_provider_catalog(): ...`                              |

The private `_PROVIDER_CATALOG` mapping may be renamed or reshaped without
notice; `list_provider_catalog()` / `get_provider_catalog(provider_id)` are
the stable surface.

## Choose a surface

There are two agent-facing HTTP families:

- `GET/POST /agent/api/*`
  Stateless capability access, best when another agent already owns the model loop
- `GET/POST /agent/api/runtime/*`
  Stateful hosted runtime access, best when TerraFin should own the conversation and tool loop

In the browser, the hosted runtime is exposed through the floating **TerraFin Agent**
widget available on main interface pages such as `/terminal`, `/chart`, and `/stock/<ticker>`.

That panel is always the public surface. There is no guru picker in the default
product flow.

If the deployment does not have a usable hosted model configured, the widget
stays in an info-only state:

- it shows the local setup warning
- it does not create a runtime session
- it does not accept chat input until the hosted model credentials are valid

Hosted runtime chat history is local transcript history:

- each session is stored as an append-only JSONL transcript
- history list and previews are derived from the transcript index
- deleting a session archives the transcript and removes it from active history
- raw tool JSON stays in the transcript for replay, but is hidden from user-facing previews

TerraFin Agent may also route some research questions through hidden investor
roles before replying. Today those roles include Warren Buffett, Howard Marks,
and Stanley Druckenmiller.

Important product rules:

- users still talk only to `TerraFin Agent`
- `TerraFin Agent` is the **orchestrator**; hidden persona roles are
  reached by its own LLM via `consult_warren_buffett`,
  `consult_howard_marks`, and `consult_stanley_druckenmiller` tool
  calls (no pre-intercept router — see the architecture diagrams in
  [architecture.md](./architecture.md#orchestrator-persona-subagents))
- the hidden guru path is research-only in v1
- hidden guru sessions are not shown in normal session history
- hidden guru roles cannot be created through the normal public runtime API
- hidden guru session ids are not valid public session/task/approval resources
- internal guru handoff uses a structured memo contract before the main assistant synthesizes a reply

## Disclosure

The hosted TerraFin Agent produces **research-oriented analysis, not personalized
investment advice**. A few properties follow from that framing and should be
called out to downstream product surfaces, integrators, and end users:

- the agent cannot place trades, hold funds, or take fiduciary responsibility
- outputs are grounded in tool results and what the user says in the same
  session; the agent should not invent numbers it has not seen in a tool result
- persona consults (Buffett, Marks, Druckenmiller) are framed as research
  voices, not registered advisor recommendations
- a `confidence` score ≥ 80 returned by a persona consult carries at least one
  citation — the `GuruResearchMemo` validator clamps unsupported high-confidence
  memos to 60 before returning them to the orchestrator (see
  [guru/memo.py](https://github.com/KiUngSong/TerraFin/blob/main/src/TerraFin/agent/guru/memo.py))

The orchestrator's system prompt carries a matching `DISCLOSURE` paragraph so the
model stays inside this framing. Product surfaces that embed the widget or call
the runtime HTTP API are responsible for any **user-facing** disclosure copy
their jurisdiction requires — the agent itself does not render one.

## Choose a transport

| Transport | Use it when... |
|-----------|----------------|
| Python client | TerraFin is importable locally and low latency matters |
| HTTP API | TerraFin is already running as a service |
| CLI | Shell composition is the simplest fit |
| Skill artifact | Another agent environment needs portable instructions |

`TerraFinAgentClient(transport="auto")` follows the normal rule:

1. Python when no `base_url` is set
2. HTTP when a `base_url` is set

## Default request policy

For market and macro requests:

- start with `depth="auto"`
- inspect the returned `processing`
- rerun with `depth="full"` only when the task genuinely needs long-range context

For company info, earnings, financials, portfolio, and calendar data:

- the payload should already be complete
- `processing.isComplete` is expected to be `true`

Charts are optional. Open them when the chart itself materially helps the task.

## Processing metadata

Every structured research response includes a top-level `processing` object.

```json
{
  "processing": {
    "requestedDepth": "auto",
    "resolvedDepth": "recent",
    "loadedStart": "2023-04-04",
    "loadedEnd": "2026-04-04",
    "isComplete": false,
    "hasOlder": true,
    "sourceVersion": "yfinance-v2",
    "view": "weekly"
  }
}
```

| Field | Meaning |
|-------|---------|
| `requestedDepth` | What the caller asked for |
| `resolvedDepth` | What TerraFin actually returned |
| `loadedStart` / `loadedEnd` | Loaded time span for time-series tasks |
| `isComplete` | Whether older data still exists outside the response |
| `hasOlder` | Whether the request can be deepened |
| `sourceVersion` | Provider/cache version hint |
| `view` | Effective timeframe transform |

## Common tasks

Multi-step task recipes. For a one-row "what tool do I need" lookup, scan the
[tool-index table at the top](#if-you-want-to-do-x-use-this-tool) instead.

Rows marked **(helper)** are composed module-level functions exported from
`from TerraFin.agent import …` — not registered capabilities. They wrap
one or more capabilities (e.g. `compare_assets` calls `resolve` + `market_snapshot`
under the hood). They're not in the 30-row capability table because they
don't appear in the agent capability registry.

| Task | Recommended entrypoint |
|------|------------------------|
| Ticker brief | `resolve(...)` then `market_snapshot(...)` |
| Market snapshot | `market_snapshot(name, depth="auto", view="daily")` |
| Compare assets | `compare_assets([...], depth="auto", view="daily")` **(helper)** |
| Macro context | `macro_context(name, depth="auto", view="daily")` **(helper)** |
| Portfolio context | `portfolio_context(guru)` **(helper)** |
| Stock fundamentals | `stock_fundamentals(ticker, statement="income", period="annual")` **(helper)** |
| Stock DCF | `valuation(ticker, projection_years=..., fcf_base_source=..., breakeven_year=..., breakeven_cash_flow_per_share=..., post_breakeven_growth_pct=...)` |
| FCF history candidates | `fcf_history(ticker, years=10)` |
| SEC filings | `sec_filings(ticker)` → `sec_filing_document(..., form=...)` → `sec_filing_section(..., sectionSlug=..., form=...)`. **Pass the actual `form` string** ("10-K" / "10-Q" / "8-K" / "8-K/A") on every call — service defaults to "10-Q". For 8-K, the TOC includes `exhibit-991-press-release` / `exhibit-992-supplemental-material` slugs holding the earnings PR + CFO commentary bodies. |
| Sentiment / breadth | `fear_greed()`, `market_regime()`, `market_breadth()`, `trailing_forward_pe()` |
| Calendar scan | `calendar_events(year=..., month=..., categories=..., limit=...)` |
| Bubble analysis | `lppl_analysis(name, depth="auto", view="daily")` |
| Chart similarity search | `similarity_search(ticker, universe="sp500+nasdaq100+kospi200", period="1y", top_n=20)` |
| Open chart | `open_chart(...)` when the chart is explicitly useful |

> See [Don't roll your own → SEC EDGAR](#sec-edgar--dont-roll-your-own-scrape)
> for the anti-pattern table and why the helper exists. The summary: pass
> `form="8-K"` explicitly (service defaults to `"10-Q"`), pull it from
> `sec_filings(...)["latestByForm"][...]["form"]`.

> The full per-capability call signature, parameter ranges, and worked
> examples (including DCF turnaround mode) live in
> [`skills/terrafin/SKILL.md`](https://github.com/KiUngSong/TerraFin/blob/main/skills/terrafin/SKILL.md) —
> the skill is the authoritative capability reference for both this doc and
> external agents.

## Minimal examples

### Python client

```python
from TerraFin.agent import TerraFinAgentClient

client = TerraFinAgentClient()
snapshot = client.market_snapshot("AAPL", depth="auto", view="daily")
```

### Hosted runtime helper

```python
from TerraFin.agent import create_runtime_session

session = create_runtime_session("terrafin-assistant")
session.send("Compare the S&P 500 and Nasdaq.")
session.display_notebook()
```

### CLI

```bash
terrafin-agent snapshot AAPL
terrafin-agent runtime-create-session terrafin-assistant
terrafin-agent models list --all
```

### HTTP

```bash
curl "http://127.0.0.1:8001/agent/api/market-snapshot?ticker=AAPL&depth=auto&view=daily"

curl -X POST "http://127.0.0.1:8001/agent/api/runtime/sessions" \
  -H "Content-Type: application/json" \
  -d '{"agentName":"terrafin-assistant"}'
```

### Browser UI

```text
http://127.0.0.1:8001/terminal
Use the TerraFin Agent button in the lower-right corner.
```

## Route summary

Stateless capability routes (every hosted-runtime tool also has a parity HTTP
route under `/agent/api/*` — see `skills/terrafin/SKILL.md` for the full
30-capability table with Python / CLI signatures).

<!-- The route table below is auto-generated from
     src/TerraFin/agent/runtime/capability.py by
     `python scripts/generate-agent-artefacts.py`. Edit the registry, not
     this section. Hand-edits will be overwritten. -->

<!-- generated:route-summary:begin -->

Data + chart:

- `GET /agent/api/calendar` — TerraFin calendar events for a month.
- `GET /agent/api/company` — Company profile and valuation fields for a ticker.
- `GET /agent/api/earnings` — Earnings history (estimate / reported / surprise) for a ticker.
- `GET /agent/api/economic` — Economic indicator series (FRED-backed).
- `GET /agent/api/financials` — Financial statement table (income / balance / cashflow) for a ticker.
- `GET /agent/api/indicators` — Chart-matching technical indicators for one asset.
- `GET /agent/api/lppl` — LPPL bubble analysis (super-exponential growth + log-periodic oscillation detection).
- `GET /agent/api/macro-focus` — Macro summary plus chart-ready series for one instrument.
- `GET /agent/api/market-data` — Chart-ready OHLC time series for one asset.
- `GET /agent/api/market-snapshot` — Compact market snapshot for one asset.
- `GET /agent/api/portfolio` — Guru portfolio holdings and summary metadata.
- `GET /agent/api/resolve` — Resolve a free-form query into a TerraFin route.

Valuation + fundamentals:

- `GET /agent/api/beta-estimate` — 5-year monthly beta with adjusted beta, R², benchmark.
- `GET /agent/api/fundamental-screen` — Fundamental quality and moat screen for a ticker.
- `GET /agent/api/risk-profile` — Statistical risk profile (tail risk, convexity, vol regime, drawdown).
- `GET /agent/api/sp500-dcf` — Full S&P 500 DCF valuation (scenarios, sensitivity, methods).
- `GET /agent/api/valuation` — DCF (incl. turnaround mode), reverse DCF, relative valuation, Graham number.

SEC filings:

- `GET /agent/api/sec-filing-document` — Filing table-of-contents (sections + char counts) without full body.
- `GET /agent/api/sec-filing-section` — Verbatim markdown body of one filing section by slug.
- `GET /agent/api/sec-filings` — List recent 10-K / 10-Q / 8-K filings for a ticker with EDGAR URLs.

Sentiment / breadth / market state:

- `GET /agent/api/fear-greed` — CNN Fear & Greed index — score, rating, history.
- `GET /agent/api/market-breadth` — Standalone market-breadth metrics (% advancing, new highs, etc.).
- `GET /agent/api/market-regime` — Market regime classification with confidence and signals.
- `GET /agent/api/top-companies` — Top companies by market cap (private API or yfinance fallback).
- `GET /agent/api/trailing-forward-pe` — S&P 500 trailing vs forward P/E spread (history + summary).
- `GET /agent/api/watchlist` — The user's current watchlist (read-only).

Other:

- `GET /agent/api/fcf-history` — FCF history + 3yr-avg / latest-annual / TTM candidates.
- `GET /agent/api/patterns` — Named market patterns matching the latest bar for one asset.
- `GET /agent/api/similarity-search` — Chart-pattern similarity search across a stock universe.

<!-- generated:route-summary:end -->

> **View context is read-only.** The hosted runtime exposes a
> `current_view_context()` tool that returns the panel and form state the
> user is currently looking at — including the DCF input form's
> `projectionYears` / `fcfBaseSource` / `turnaroundMode` selections, the FCF
> history candidates already loaded, and the auto-selected DCF base source.
> The agent **cannot currently write back to the user's frontend form** (no
> `apply_dcf_inputs` / `set_form_state` tool exists). If the agent suggests
> input values, the user applies them manually. This gap is tracked.

Hosted runtime routes:

- `GET /agent/api/runtime/agents`
- `POST /agent/api/runtime/sessions`
- `GET /agent/api/runtime/sessions`
- `GET /agent/api/runtime/sessions/{session_id}`
- `DELETE /agent/api/runtime/sessions/{session_id}`
- `POST /agent/api/runtime/sessions/{session_id}/messages`
- `GET /agent/api/runtime/sessions/{session_id}/approvals`
- `GET /agent/api/runtime/tasks/{task_id}`
- `POST /agent/api/runtime/tasks/{task_id}/cancel`
- `GET /agent/api/runtime/approvals/{approval_id}`
- `POST /agent/api/runtime/approvals/{approval_id}/approve`
- `POST /agent/api/runtime/approvals/{approval_id}/deny`

OpenAPI is available at `/openapi.json`.

## Managing hosted models

The hosted runtime now has a small built-in model manager. Use it when you want
OpenAI, Gemini, or GitHub Copilot without hand-editing env vars every time.

This command family was inspired by OpenClaw's provider/model UX, but TerraFin
implements and persists it through its own runtime and CLI layers. See
[models.md](./models.md) for the explicit attribution and boundary.

```bash
terrafin-agent models list --all
terrafin-agent models current
terrafin-agent models use github-copilot/gpt-4o
terrafin-agent models auth login-github-copilot --set-default
```

`login-github-copilot` now runs a full GitHub device-login flow by default. For
non-interactive shells, pass `--token` instead.

For the full model-management guide, read [models.md](./models.md).

## Read next

- [hosted-runtime.md](./hosted-runtime.md)
- [models.md](./models.md)
- [architecture.md](./architecture.md)
- [../interface.md](../interface.md)
- [TerraFin skill on GitHub](https://github.com/KiUngSong/TerraFin/blob/main/skills/terrafin/SKILL.md)