Returns every available line item (revenue, margins, cash flow, balance
sheet) with the concept, period and filing each value came from. Line
items a company does not report appear under `unavailable` rather than
causing an error.

Args:
    ticker: Stock symbol, e.g. "AAPL".
    period: "annual" or "quarterly".

Use this for growth rates and trends. Each point states its own fiscal
year and source filing, so a restated figure is visible as such.

Args:
    ticker: Stock symbol, e.g. "NVDA".
    line_item: One of the supported keys, e.g. "revenue", "net_income".
    period: "annual" or "quarterly".
    limit: Maximum number of periods to return.

Computed from SEC filings rather than estimated. Covers gross/operating/net
margin, R&D intensity, free cash flow and FCF margin, cash conversion,
debt/equity, net debt, ROE and ROA (on average balances where available),
and YoY plus CAGR growth for revenue, net income and operating cash flow.

Each metric lists the line items it was computed from and the period it
covers. Prefer this over deriving ratios yourself from `get_financials`.

Args:
    ticker: Stock symbol, e.g. "AAPL".
    history_years: Periods to span when computing growth rates.

Computed from daily bars on the consolidated SIP tape, so volume is the
full market rather than a single venue. Returns moving-average structure,
RSI, ATR (with stop-distance guidance), relative strength versus a
benchmark, drawdown from the one-year high, and clustered support and
resistance annotated with what each level does at the current price.

Anything that could not be computed from the available history is null and
explained under `limitations` rather than approximated.

Args:
    ticker: Stock symbol, e.g. "NVDA".
    benchmark: Symbol for relative strength, default "SPY".
    lookback_days: Calendar days of history to pull. 500 gives a 200-day
        moving average enough trading sessions.

Args:
    ticker: Stock symbol.
    forms: Optional filter, e.g. ["10-K", "8-K"]. Omit for all forms.
    limit: Maximum filings to return.

Args:
    ticker: Stock symbol.
    limit: Maximum Form 4 filings to return.

Use this when the numbers raise a question they cannot answer — a margin
that moved, a quarter that beat and sold off anyway, a net income figure
that outran operating income. `get_filings` gives you the date; this gives
you what the company actually said.

Large filings are returned in windows. `truncated` and `next_offset` tell
you whether there is more; a silently cut filing reads like a complete one.
Prefer `search_filing_text` when you know what you are looking for.

Args:
    ticker: Stock symbol.
    accession: Specific filing accession number. Takes precedence.
    form: Read the newest filing of this form instead, e.g. "10-Q".
    offset: Character offset to start from, for paging.
    max_chars: Characters to return, capped at 100,000.

Far cheaper than paging a 10-K to find the one paragraph that explains a
tax benefit or a goodwill charge. No match means the term is absent from
this document, not that the fact is absent from the company's filings.

Args:
    ticker: Stock symbol.
    query: Term to find, e.g. "stock-based compensation".
    accession: Specific filing accession number. Takes precedence.
    form: Search the newest filing of this form instead, e.g. "10-K".
    context: Characters of surrounding text per hit.
    max_hits: Maximum passages to return.

Every reading carries its FRED series id, observation date and 1-, 3- and
12-month changes, computed against the last real print rather than a
calendar date. Series that fail are listed under `unavailable` rather than
taking the whole snapshot down.

Rates and inflation recalled from memory are wrong by whole percentage
points. Always read them here.

Args:
    series: Optional subset, e.g. ["treasury_10y", "curve_10y_2y"]. Omit
        for all of them.

Args:
    key: Series key, e.g. "treasury_10y", "core_cpi", "vix". Call
        `get_macro_snapshot` to see them all.

A starting list, not a signal — most large single-day moves are news the
market has already priced.

Args:
    top: How many of each to return, capped at 50.

Args:
    by: "volume" or "trades".
    top: How many to return, capped at 50.

Turns a raw list into a shortlist worth spending the research agents on.
Returns trend structure, distance from the 50-day, RSI, ATR as a percentage
of price and drawdown from the one-year high for each name. Symbols whose
history could not be retrieved appear under `unavailable` rather than
quietly dropping out.

This orders candidates; it does not judge them.

Args:
    symbols: Up to 40 symbols. Each costs a separate history request.
    benchmark: Symbol for relative strength, default "SPY".
    lookback_days: Calendar days of history per symbol.

Returns the share count, the capital genuinely at risk, current portfolio
heat from open journalled theses, and every limit checked with its observed
value and threshold. The `verdict` is one of `approved`,
`approved_with_warnings` or `vetoed`; a veto is a refusal, not a preference.

Never work a share count out yourself — this is where a correct thesis
loses money. Anything that could not be checked, such as a missing ATR or
target, appears under `limitations` rather than being assumed to pass.

Args:
    ticker: Stock symbol, e.g. "NVDA".
    direction: "long" or "short".
    entry: Intended entry price.
    stop: Stop price. Must sit below entry for a long, above for a short.
    account_equity: Total account equity the risk budget is drawn from.
    target: Intended exit. Omit only if the chartist gave none.
    atr: ATR(14) from `get_technicals`, to check the stop against noise.
    risk_pct: Requested % of equity at risk. Clamped to the policy maximum.

Write this at the moment the call is made. Evidence and falsifiers cannot
be reconstructed honestly once the outcome is known, which is the whole
reason the journal exists.

Record `direction="watch"` when the conclusion was to take no position —
a watch call that would have worked is as informative as a trade that did.

Args:
    ticker: Stock symbol.
    thesis: The call, in plain language. What this is and what to do.
    falsifiers: Observations that would prove the thesis wrong — price
        levels, a filing, a metric crossing a threshold. Required.
    direction: "long", "short" or "watch".
    horizon: "swing", "positional" or "long_term".
    conviction: Free text, e.g. "low", "medium", "high".
    entry: Entry price. Required for a long or short.
    stop: Stop price. Required for a long or short.
    target: Target price.
    reward_risk: Reward:risk, as reported by `size_position`.
    shares: Share count, as sized by `size_position`.
    dollar_risk: Capital at risk, as sized by `size_position`.
    risk_verdict: The `verdict` returned by `size_position`.
    evidence: Supporting figures, each ideally {"claim", "source",
        "period"}, so the thesis can be audited against the filings.
    gaps: Data that was unavailable, stale or unresolved at the time.

Args:
    ticker: Optional symbol filter.
    status: Optional "open" or "closed" filter.
    limit: Maximum theses to return.

Args:
    thesis_id: Identifier returned by `journal_thesis`.

Realised R is computed from the recorded entry and stop, so the result is
comparable across positions of different sizes.

Args:
    thesis_id: Identifier returned by `journal_thesis`.
    outcome: One of "target_hit", "stopped_out", "closed_manual",
        "expired", "invalidated".
    exit_price: Fill price, where there was one.
    note: What actually happened, especially if the thesis was right for
        the wrong reason.

Refuses to return anything for an account it cannot prove is a paper
account. Use the `equity` here as the input to `size_position` rather than
assuming a figure.

Takes a thesis id and nothing else, by design. Symbol, share count, entry,
stop and target all come from the journal entry, which exists only because
the risk officer approved it. There is no way to place an order this desk
did not size.

Refuses when: the thesis is closed, is a watch call, carries a vetoed risk
verdict, was sized at zero shares, lacks an entry or stop, or already has
an order attached. Orders go out as brackets, so the stop is submitted with
the entry rather than left to a later call.

A submitted order is not a filled one. Check `get_broker_orders`.

Args:
    thesis_id: Identifier returned by `journal_thesis`.

Args:
    status: "open", "closed" or "all".
    limit: Maximum orders to return.

Does not close a filled position — if the entry already filled, the
position remains open and must be closed explicitly.

Args:
    broker_order_id: Order id returned by `place_order`.

Closing at the broker does not close the thesis. Follow this with
`close_thesis` and the fill price so realised R is recorded.

Args:
    symbol: Stock symbol of the position to close.

Portfolio heat is computed from the journal, so a position held without a
thesis is exposure the risk checks cannot see. This reports both kinds of
mismatch: untracked positions, and theses whose entry never filled.