Get a full snapshot of the user's portfolio: cash balances per currency, every holding with units / average cost / live price, and unrealized P&L per position and in total.

Use when the user asks "show my portfolio", "how is my P&L", or before proposing any trade. Read-only; fetches live quotes, so values change between calls.

Returns: Object with cash (currency → amount), holdings (list of positions with symbol, units, avg_cost, live price, market value, pnl_pct), and portfolio-level totals.

Get the user's investment strategy: target stock/cash allocation, the list of tracked assets (per-asset investment cap, purchase channel, fee settings), and long-term insights distilled by the nightly Dreaming memory-consolidation job.

Use when deciding whether a proposed trade fits the user's plan, or when the user asks "what is my strategy / what am I tracking". Read-only.

Returns: Object with target_allocation (stock/cash ratios), target_assets (tracked symbols with constraints), and insights (distilled lessons from past decisions).

Get the most recent trade records and committee verdict history.

Use when the user asks "what did I buy recently" or "what did the committee decide lately". Read-only.

Args: n: Maximum number of recent trades to return (default 10).

Returns: Object with trades (each with symbol, direction, units, price, timestamp, status) and recent committee verdict records.

Fetch a one-shot market backdrop: spot gold (USD/oz and CNY/gram), USDCNY and AUDCNY FX rates, the NDQ.AX ETF price, the VIX volatility index, and the 10-year US Treasury yield (TNX).

Use for quick market context before analysis or when the user asks "how is the market / what's the gold price". Read-only; single batch, no arguments.

Returns: Object keyed by instrument (GC_F_usd_per_oz, gold_cny_per_gram_spot, USDCNY, AUDCNY, NDQ_AX, VIX, TNX) plus as_of ISO timestamp. A field is null when its upstream quote is unavailable.

Simulate portfolio P&L for a hypothetical price move: "what happens to my portfolio if moves ±pct% / reaches ". Pure arithmetic over current holdings — no LLM call, instant, free.

Use when the user asks scenario questions like "if the Nasdaq drops 10%, how much do I lose". Provide exactly one of pct or price.

Args: symbol: yfinance ticker held or tracked by the user (e.g. "NDQ.AX", "GC=F", "510300.SS"). pct: Hypothetical percent change, e.g. -10 for a 10% drop. price: Hypothetical absolute target price (alternative to pct).

Returns: Object with the position's simulated value change and the resulting portfolio-level P&L delta.

Get the committee's discipline ledger: how often it chose inaction (HOLD ratio), how many impulsive user trades its rules intercepted, and the counterfactual money saved/lost by those interventions (ADR-023: the system's proven value is discipline and transparency, not alpha).

Use when the user asks "what has the committee blocked" or "is this tool actually helping". Read-only.

Returns: Object with summary (structured stats) and markdown (the same ledger pre-rendered for direct display to the user).

Get the unified decision ledger: every committee verdict joined with rule interventions, the user's actual executions or refusals (with reasons), and post-hoc outcome data — plus an adoption-rate summary.

Answers "how often did I follow the advice", "which recommendations did I skip", and "what did the safety rules rewrite". Read-only.

Args: days: Look-back window in days (default 90).

Returns: Object with count, summary (adoption rate and aggregates), and decisions (list; each entry has decision_id, verdict, confidence, intervention, executed flag, matched trades, and outcome).

Get the full reasoning behind one committee verdict: the complete 4-role debate transcript with the CIO memo, plus the path-probability snapshot the CIO saw at decision time.

Use when the user asks "why was today's verdict HOLD" or wants to audit a past decision. Read-only.

Args: decision_id: "/", e.g. "2026-07-03/GC=F" — exactly as returned in the decisions tool output.

Returns: Object with verdict, confidence, alloc_cny, transcript_markdown (render this to the user), and path_snapshot (may be null).

Record whether the user executed or declined a committee verdict, with their reason. Appends to the execution ledger; idempotent — replaying the same record is a no-op, so retries are safe.

Call when the user says "I bought it / I didn't buy / I disagree". When they decline, ask one short question for the reason first — this closes the adoption-rate loop that decisions reports on.

Args: decision_id: "/" from the decisions output. executed: True if the user acted on the verdict, False if declined. reason: The user's stated reason (especially when declined). trade_ids: Optional trade record IDs to link explicitly.

Returns: The stored execution record, or {"status": "error", "error": ...}.

Feed a finance news item you (the host agent) found into the event ledger. The backend LLM normalizes it, grades severity, maps affected symbols, and stores it for committee RAG recall.

You have far better search reach than the self-hosted crawler (including Chinese-language sources) — proactively feed news relevant to the user's holdings, especially A-share/regional coverage the crawler misses. Idempotent: re-sending the same url or claim does not double-insert. Requires a backend LLM key.

Args: title: Headline of the news item. url: Canonical source URL (also the dedup key). snippet: Short excerpt or summary of the article body. source: Publisher name (e.g. "Reuters") — the news outlet. published_at: ISO 8601 publication time, if known. ingested_by: Your own agent identity (e.g. "hermes") for provenance; distinct in meaning from source.

Returns: Ingestion result with the normalized event id(s) and dedup status.

List the news feed sources the crawler pulls from: the built-in default feeds plus user-added extra feeds. Extra feeds can be added/removed with add_news_source / remove_news_source; defaults are fixed.

Use when someone asks "what news sources do you follow" or before adding/removing a source.

Add an RSS/Atom feed to the crawler's source list. The URL is live-probed before saving — a URL that doesn't parse as a feed is rejected. Idempotent: re-adding an existing URL returns the existing entry. Capped so the list can't grow unbounded.

Use when someone says "follow 's news" / "加个新闻源".

Remove a user-added news feed by name or URL. Built-in default feeds cannot be removed.

Record a buy in the local ledger: adds to an existing position with weighted-average cost, or opens a new position for an unseen symbol. This bookkeeps a trade the user already placed with their broker — openInvest never places real orders.

Confirm symbol, units, and price with the user before calling; this moves ledger cash.

Args: symbol: yfinance ticker (e.g. "AAPL", "510300.SS", "GC=F"). units: Quantity bought; must be > 0. price: Execution price per unit, in currency. currency: Currency of price (default "CNY"). kind: Asset kind tag, e.g. "equity", "etf", "commodity". unit_label: Human display label for units (default "股", i.e. shares).

Returns: Updated position summary, or {"status": "error", "error": ...}.

Record a sell in the local ledger: reduces the position's units (average cost unchanged) and credits cash in the holding's cost currency. Bookkeeps a trade already executed at the user's broker — openInvest never places real orders.

Confirm symbol, units, and price with the user before calling; this moves ledger cash.

Args: symbol: yfinance ticker of an existing holding. units: Quantity sold; must be > 0. price: Execution price per unit, in the holding's cost currency.

Returns: Updated position summary, or {"status": "error", "error": ...}.

Record a cash deposit into the ledger, in any currency. Bookkeeping only — no real payment system is connected.

Args: currency: ISO-style currency code, e.g. "CNY", "USD", "AUD". amount: Amount to add; must be > 0.

Returns: Updated cash balances, or {"status": "error", "error": ...}.

Record a cash withdrawal from the ledger, in any currency. Fails if the balance is insufficient. Bookkeeping only — no real payment system is connected.

Args: currency: ISO-style currency code, e.g. "CNY", "USD", "AUD". amount: Amount to remove; must be > 0.

Returns: Updated cash balances, or {"status": "error", "error": ...}.

Update the strategy's target stock/cash allocation ratio. The two values must sum to ≈1.0; schema validation rejects and rolls back any write that would corrupt the strategy file.

Use when the user says e.g. "set my target to 70% stock / 30% cash".

Args: target_allocation_stock: Stock weight in [0, 1], e.g. 0.7. target_allocation_cash: Cash weight in [0, 1], e.g. 0.3.

Returns: The updated allocation, or {"status": "error", "error": ...}.

Add a symbol to the tracked-asset list, or update an existing entry (idempotent upsert: only the fields you pass are changed). The tracked list decides which symbols the committee and DCA jobs cover.

Use when the user says "track AAPL" or wants to change a tracked asset's cap/channel/fees.

Args: symbol: yfinance ticker to track (e.g. "AAPL", "0700.HK", "BTC-USD"). max_single_invest_cny: Per-decision investment cap in CNY. Required when creating a new entry; optional on update. display_name: Human-friendly name shown in reports. channel: Where the user actually buys it (broker/app name). price_offset_pct: Systematic offset between the quote and the user's actual fill price, in percent (e.g. bank gold spread). sell_fee_pct: Sell-side fee in percent, used by fee-aware math.

Returns: The stored asset entry, or {"status": "error", "error": ...}.

Remove a symbol from the tracked-asset list — the committee and DCA jobs stop covering it. Holdings and trade history are untouched; schema validation guarantees at least one tracked asset remains.

Args: symbol: yfinance ticker currently in the tracked list.

Returns: The updated tracked list, or {"status": "error", "error": ...}.

Run the 4-role LLM investment committee on a symbol (Direct path): Macro Strategist, Quant Analyst, and Risk Officer debate from isolated evidence, then a CIO synthesizes one calibrated BUY/HOLD/SELL-style verdict with a written memo.

Requires a backend LLM key (e.g. DEEPSEEK_API_KEY) and takes 30-90s on a cache miss. If the symbol was already analyzed today, the cached verdict is returned instantly unless force is set. Decision support only — the human always executes.

Args: symbol: Any yfinance ticker (US / HK / A-share / ETF / crypto / commodities), e.g. "AAPL", "GC=F", "510300.SS". force: Re-run even if a verdict already exists for today. max_rounds: Cross-challenge debate rounds (default 1).

Returns: Object with decision_id, cached flag, and verdict (verdict, confidence, suggested allocation, CIO memo).