{
    "$schema": "https://finmagine.com/developer/agent-recipes.schema.json",
    "version": "1.0.0",
    "generated_at": "2026-07-30T19:12:28+00:00",
    "note": "Every recipe here chains tools confirmed live in /openapi.json at generation time. See /developer/docs.php for auth, or /openapi.json for the full per-tool parameter/response contract referenced by \"tool\" names below. status:\"partial\" recipes have a documented gap (see their \"note\" field); status:\"prerequisite\" recipes set up something other recipes depend on rather than producing a research output themselves. Each step's external_call (\"none\"/\"finmagine_free_tier\"/\"byo_key\") states precisely which calls touch a provider; llm_required at the recipe level is the OR of all its steps' external_call. depends_on/input_map are machine-readable chaining hints (dot-path with optional [*] wildcard or [N] index) alongside the free-text input_from.",
    "recipes": [
        {
            "id": "india_screen_to_committee",
            "title": "India: Screen → Investment Committee",
            "description": "The flagship workflow: filter the full NSE universe by fundamental/technical criteria, free-scan the shortlist, then run a full multi-lens LLM committee analysis, risk audit, and position sizing on the survivors.",
            "market": "india",
            "required_tier": "api_max",
            "async": true,
            "status": "complete",
            "max_symbols": 10,
            "quota": "5 committee runs / 24h (shared across all committee-based recipes)",
            "estimated_runtime": "1-10 min for the committee run itself (varies by provider speed), plus polling overhead — screen_stocks and fast_scan_committee are near-instant.",
            "steps": [
                {
                    "id": "screen",
                    "tool": "screen_stocks",
                    "description": "Filter by ROCE/PE/market cap/RS rating/sector etc. Returns companies[] with symbol.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "fast_scan",
                    "tool": "fast_scan_committee",
                    "description": "Free, zero-LLM deterministic pre-screen across 3 lenses. Use to cut the shortlist before spending a committee run.",
                    "input_from": "$.companies[*].symbol — pick up to 10, e.g. top by rs_rating",
                    "depends_on": [
                        "screen"
                    ],
                    "input_map": {
                        "symbols": "screen.companies[*].symbol"
                    },
                    "max_items": 10,
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "start",
                    "tool": "start_committee",
                    "description": "Launch the full LLM committee run. Requires provider (call list_byo_keys first if unsure which to pass). NOTE: input_map below defaults to the raw screen shortlist — narrowing it using fast_scan.results[*].committee_signal is a human/agent judgment call the engine cannot auto-chain (fast_scan_committee returns an object keyed by symbol, not an array, and this recipe format has no filter/selection expression yet), not an automatic step. depends_on includes fast_scan purely to guarantee it has actually completed first, not to imply its output is auto-applied.",
                    "input_from": "defaults to screen.companies[*].symbol; to actually use the fast_scan pre-screen, manually pick symbols where fast_scan.results[symbol].committee_signal looks strongest before calling this step",
                    "depends_on": [
                        "screen",
                        "fast_scan"
                    ],
                    "input_map": {
                        "symbols": "screen.companies[*].symbol"
                    },
                    "max_items": 10,
                    "transport": "rest",
                    "external_call": "byo_key"
                },
                {
                    "id": "poll",
                    "tool": "check_committee_status",
                    "description": "Poll until status is completed/failed/cancelled.",
                    "input_from": "$.job_id or $.vps_run_id from start_committee",
                    "depends_on": [
                        "start"
                    ],
                    "input_map": {
                        "job_id": "start.job_id"
                    },
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "report",
                    "tool": "get_committee_report",
                    "description": "Full per-symbol signals, evidence, dissent, and verdicts. Waits on poll reaching a terminal state; job_id itself is sourced from start (poll only echoes it back).",
                    "input_from": "$.job_id",
                    "depends_on": [
                        "start",
                        "poll"
                    ],
                    "input_map": {
                        "job_id": "start.job_id"
                    },
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "risk_compute",
                    "tool": "compute_committee_risk",
                    "description": "Correlation, volatility, drawdown, beta, sector concentration for the same symbol set.",
                    "depends_on": [
                        "screen"
                    ],
                    "input_map": {
                        "symbols": "screen.companies[*].symbol"
                    },
                    "max_items": 10,
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "risk_allocate",
                    "tool": "allocate_committee_risk",
                    "description": "Turns committee stances + risk metrics into illustrative position weights. Requires the same symbol set again alongside committee/risk_metrics.",
                    "input_from": "symbols same as screen, committee from get_committee_report.report.committee, risk_metrics from compute_committee_risk.per_stock",
                    "depends_on": [
                        "screen",
                        "report",
                        "risk_compute"
                    ],
                    "input_map": {
                        "symbols": "screen.companies[*].symbol",
                        "committee": "report.report.committee",
                        "risk_metrics": "risk_compute.per_stock"
                    },
                    "max_items": 10,
                    "transport": "rest",
                    "external_call": "none"
                }
            ],
            "output_contract": "Final allocations {symbol: weight_pct}, plus the full committee report and risk metrics behind them for an audit trail.",
            "failure_fallback": "no_key → call GET /account/byo-keys or list_byo_keys, then save one. quota_exceeded (5 committee runs/24h) → wait, or use only the free fast_scan_committee results.",
            "guardrail": "Readiness/research workflow. Allocations are illustrative, not investment advice.",
            "llm_required": true
        },
        {
            "id": "india_trader_to_committee",
            "title": "India: Trader Scan → Investment Committee",
            "description": "Cheaper alternative to the screen-based flagship (no api_max needed) — start from technically-strong Trader Workflow candidates instead of a fundamental screen.",
            "market": "india",
            "required_tier": "api_pro",
            "async": true,
            "status": "complete",
            "max_symbols": 10,
            "quota": "5 committee runs / 24h (shared across all committee-based recipes)",
            "estimated_runtime": "1-10 min for the committee run itself, plus polling overhead — the scan and fast_scan_committee steps are near-instant.",
            "steps": [
                {
                    "id": "scan",
                    "tool": "market_trader_scan",
                    "description": "scan_type=allThree for the highest-confluence technical setups (Stage 2 + Near High + High Volume simultaneously).",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "fast_scan",
                    "tool": "fast_scan_committee",
                    "description": "Free fundamental pre-screen of the technical shortlist.",
                    "input_from": "$.stocks[*].symbol — up to 10",
                    "depends_on": [
                        "scan"
                    ],
                    "input_map": {
                        "symbols": "scan.stocks[*].symbol"
                    },
                    "max_items": 10,
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "start",
                    "tool": "start_committee",
                    "description": "Full LLM committee run + a provider. NOTE: input_map defaults to the raw scan shortlist — narrowing via fast_scan.results[symbol].committee_signal is a manual judgment call, not auto-chained (see india_screen_to_committee for the full explanation). depends_on includes fast_scan to guarantee it has completed first, not to imply its output is auto-applied.",
                    "input_from": "defaults to scan.stocks[*].symbol; to use the fast_scan pre-screen, manually pick symbols where fast_scan.results[symbol].committee_signal looks strongest",
                    "depends_on": [
                        "scan",
                        "fast_scan"
                    ],
                    "input_map": {
                        "symbols": "scan.stocks[*].symbol"
                    },
                    "max_items": 10,
                    "transport": "rest",
                    "external_call": "byo_key"
                },
                {
                    "id": "poll",
                    "tool": "check_committee_status",
                    "description": "Poll to terminal.",
                    "depends_on": [
                        "start"
                    ],
                    "input_map": {
                        "job_id": "start.job_id"
                    },
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "report",
                    "tool": "get_committee_report",
                    "description": "Full per-symbol analysis.",
                    "depends_on": [
                        "start",
                        "poll"
                    ],
                    "input_map": {
                        "job_id": "start.job_id"
                    },
                    "transport": "rest",
                    "external_call": "none"
                }
            ],
            "output_contract": "Committee signals + verdicts for technically-strong candidates.",
            "failure_fallback": "Same as india_screen_to_committee.",
            "guardrail": "Readiness/research workflow, not investment advice.",
            "llm_required": true
        },
        {
            "id": "us_trader_to_committee",
            "title": "US: Trader Scan → Investment Committee",
            "description": "US equivalent of india_trader_to_committee.",
            "market": "us",
            "required_tier": "api_pro",
            "async": true,
            "status": "complete",
            "max_symbols": 10,
            "quota": "5 committee runs / 24h (shared across all committee-based recipes)",
            "estimated_runtime": "1-10 min for the committee run itself, plus polling overhead — the scan and fast_scan_committee steps are near-instant.",
            "steps": [
                {
                    "id": "scan",
                    "tool": "us_market_trader_scan",
                    "description": "scan_type=stage2nh for Stage 2 + Near-High US setups.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "fast_scan",
                    "tool": "fast_scan_committee",
                    "description": "Pass market:\"us\" — free fundamental pre-screen.",
                    "input_from": "$.stocks[*].symbol — up to 10",
                    "depends_on": [
                        "scan"
                    ],
                    "input_map": {
                        "symbols": "scan.stocks[*].symbol"
                    },
                    "fixed_params": {
                        "market": "us"
                    },
                    "max_items": 10,
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "start",
                    "tool": "start_committee",
                    "description": "Pass market:\"us\" + provider. NOTE: input_map defaults to the raw scan shortlist — narrowing via fast_scan.results[symbol].committee_signal is a manual judgment call, not auto-chained (see india_screen_to_committee for the full explanation). depends_on includes fast_scan to guarantee it has completed first, not to imply its output is auto-applied.",
                    "input_from": "defaults to scan.stocks[*].symbol; to use the fast_scan pre-screen, manually pick symbols where fast_scan.results[symbol].committee_signal looks strongest",
                    "depends_on": [
                        "scan",
                        "fast_scan"
                    ],
                    "input_map": {
                        "symbols": "scan.stocks[*].symbol"
                    },
                    "fixed_params": {
                        "market": "us"
                    },
                    "max_items": 10,
                    "transport": "rest",
                    "external_call": "byo_key"
                },
                {
                    "id": "poll",
                    "tool": "check_committee_status",
                    "description": "Poll to terminal.",
                    "depends_on": [
                        "start"
                    ],
                    "input_map": {
                        "job_id": "start.job_id"
                    },
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "report",
                    "tool": "get_committee_report",
                    "description": "Full per-symbol analysis.",
                    "depends_on": [
                        "start",
                        "poll"
                    ],
                    "input_map": {
                        "job_id": "start.job_id"
                    },
                    "transport": "rest",
                    "external_call": "none"
                }
            ],
            "output_contract": "Committee signals + verdicts for technically-strong US candidates.",
            "failure_fallback": "Same as india_screen_to_committee.",
            "guardrail": "Readiness/research workflow, not investment advice.",
            "llm_required": true
        },
        {
            "id": "india_momentum_setup",
            "title": "India: Momentum Setup",
            "description": "Market regime → early RS improvement → current RS leaders → multi-preset conviction. All 4 steps are real, independent read endpoints — no chaining transformation needed, run in sequence and cross-reference the outputs.",
            "market": "india",
            "required_tier": "api_pro",
            "async": false,
            "status": "complete",
            "quota": null,
            "estimated_runtime": "under 1 min (4 synchronous read calls).",
            "steps": [
                {
                    "id": "breadth",
                    "tool": "get_market_breadth",
                    "description": "Overall market regime (% above key moving averages, advance/decline).",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "rs_changes",
                    "tool": "get_rs_changes",
                    "description": "Stocks whose RS rating improved most recently — early in an RS improvement cycle, often leads the next price move.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "momentum",
                    "tool": "get_market_momentum",
                    "description": "Current RS leaderboard (RS ≥ 90 = elite).",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "conviction",
                    "tool": "get_conviction_ranking",
                    "description": "Stocks appearing in multiple screener presets simultaneously — cross-reference against the RS lists above for highest-confluence names.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                }
            ],
            "output_contract": "Four independent lists to cross-reference by hand/agent-judgment — stocks appearing across get_rs_changes, get_market_momentum, AND get_conviction_ranking simultaneously are the highest-confluence candidates.",
            "failure_fallback": "None of these calls have external dependencies — a failure here is a genuine API/auth problem, not a data-availability issue.",
            "guardrail": "Signal-generation workflow, not investment advice.",
            "llm_required": false
        },
        {
            "id": "us_momentum_setup_partial",
            "title": "US: Momentum Setup (partial)",
            "description": "3 of India's 4 momentum-setup steps, US equivalents. Deliberately partial.",
            "market": "us",
            "required_tier": "api_pro",
            "async": false,
            "status": "partial",
            "quota": null,
            "estimated_runtime": "under 1 min (3 synchronous read calls).",
            "steps": [
                {
                    "id": "breadth",
                    "tool": "us_get_market_breadth",
                    "description": "US market regime.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "momentum",
                    "tool": "us_market_momentum",
                    "description": "Current RS leaderboard for US equities.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "conviction",
                    "tool": "us_get_conviction_ranking",
                    "description": "Multi-preset conviction for US stocks.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                }
            ],
            "output_contract": "Three lists to cross-reference — see india_momentum_setup for the pattern.",
            "failure_fallback": null,
            "guardrail": "Signal-generation workflow, not investment advice.",
            "note": "US has no equivalent of India's get_rs_changes (\"RS improving before price\") — blocked on a missing dated RS-rating history pipeline for US equities, not just a missing endpoint. Do not substitute a same-day cross-sectional RS comparison as a stand-in; it is a materially different signal from \"RS improved over time,\" and a prior review explicitly rejected shipping a fake substitute under this name. Deferred to a future pass once the pipeline exists.",
            "llm_required": false
        },
        {
            "id": "post_earnings_review",
            "title": "India: Post-Earnings Review",
            "description": "Earnings catalyst screening, then a deep dive on the top-ranked company: its historical PEAD track record, AI quarterly summary, and management commitment tracking. Deep dive on ONE company (the top ECS result), not a multi-company drift-candidate screen — for the current universe of active drift candidates instead, use get_pead_candidates.",
            "market": "india",
            "required_tier": "api_max",
            "async": false,
            "status": "complete",
            "quota": null,
            "estimated_runtime": "under 1 min (4 synchronous read calls against precomputed data).",
            "steps": [
                {
                    "id": "ecs",
                    "tool": "get_ecs_leaderboard",
                    "description": "Companies ranked by Earnings Catalyst Score.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "pead",
                    "tool": "get_company_pead",
                    "description": "This specific company's historical PEAD track record (not the active-candidate universe — that's get_pead_candidates).",
                    "input_from": "$.leaders[*].symbol from get_ecs_leaderboard",
                    "depends_on": [
                        "ecs"
                    ],
                    "input_map": {
                        "symbol": "ecs.results[0].symbol"
                    },
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "summary",
                    "tool": "get_ai_quarterly_summary",
                    "description": "AI-generated summary of the latest concall for a symbol.",
                    "input_from": "same symbol",
                    "depends_on": [
                        "ecs"
                    ],
                    "input_map": {
                        "symbol": "ecs.results[0].symbol"
                    },
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "decoder",
                    "tool": "get_concall_decoder",
                    "description": "Structured extraction of management commitments vs. delivery track record.",
                    "input_from": "same symbol",
                    "depends_on": [
                        "ecs"
                    ],
                    "input_map": {
                        "symbol": "ecs.results[0].symbol"
                    },
                    "transport": "rest",
                    "external_call": "none"
                }
            ],
            "output_contract": "Per-symbol: ECS score, PEAD signal, AI summary, and a management-credibility read (commitments made vs. kept).",
            "failure_fallback": "get_ai_quarterly_summary/get_concall_decoder return 404-equivalent for symbols without concall coverage — not every company has this yet.",
            "guardrail": "Research workflow, not investment advice.",
            "llm_required": false
        },
        {
            "id": "research_preset_deepdive",
            "title": "Research Preset Deep Dive",
            "description": "Pick one of Strategy Lab's 8 multi-agent analyst chains and run it. Genuinely separate system from Investment Committee — one preset, one goal, one report; not a multi-symbol committee vote.",
            "market": "both",
            "required_tier": "api_pro",
            "async": true,
            "status": "complete",
            "quota": "10 preset runs / 24h (separate from Committee's 5/24h)",
            "estimated_runtime": "15-40 min depending on chosen preset — see list_preset_catalog.runtime_minutes for the exact figure per preset — plus polling overhead.",
            "steps": [
                {
                    "id": "catalog",
                    "tool": "list_preset_catalog",
                    "description": "The 8 preset definitions — id, market, description, estimated runtime, agent count.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "keys",
                    "tool": "list_byo_keys",
                    "description": "Confirm which provider to pass to start_preset.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "start",
                    "tool": "start_preset",
                    "description": "Launch the chosen preset.",
                    "input_from": "preset id from list_preset_catalog, provider from list_byo_keys",
                    "depends_on": [
                        "catalog",
                        "keys"
                    ],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "byo_key"
                },
                {
                    "id": "poll",
                    "tool": "check_preset_status",
                    "description": "Poll until terminal; final_report is the deliverable.",
                    "input_from": "$.vibe_run_id from start_preset",
                    "depends_on": [
                        "start"
                    ],
                    "input_map": {
                        "vibe_run_id": "start.vibe_run_id"
                    },
                    "transport": "rest",
                    "external_call": "none"
                }
            ],
            "output_contract": "A single markdown-style final_report from the chosen analyst chain (15-40 min depending on preset).",
            "failure_fallback": "no_key → save one first. quota_exceeded (10 runs/24h, separate from Committee's 5/24h) → wait.",
            "guardrail": "Research output, not investment advice.",
            "llm_required": true
        },
        {
            "id": "byo_key_setup",
            "title": "BYO LLM Key Setup",
            "description": "Prerequisite flow for anything that needs an LLM (start_preset, start_committee) — save and verify a provider key once, then reference it by name in every subsequent workflow.",
            "market": null,
            "required_tier": "free",
            "async": false,
            "status": "prerequisite",
            "quota": "save_byo_key: 20/hour. test_byo_key: 10/hour. Both independent of normal API rate limits.",
            "estimated_runtime": "under 1 min.",
            "steps": [
                {
                    "id": "list",
                    "tool": "list_byo_keys",
                    "description": "Check what is already saved.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "save",
                    "tool": "save_byo_key",
                    "description": "Save a new key. WARNING (MCP only): this tool argument carries a real secret — see save_byo_key's own tool description before using it through an MCP client you don't fully control. Prefer the REST endpoint for saving.",
                    "input_from": null,
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "test",
                    "tool": "test_byo_key",
                    "description": "Verify the saved key works, without re-transmitting the secret (omit key/model to re-test what's already saved).",
                    "input_from": "provider from save_byo_key",
                    "depends_on": [
                        "save"
                    ],
                    "input_map": {
                        "provider": "save.provider"
                    },
                    "transport": "rest",
                    "external_call": "byo_key"
                }
            ],
            "output_contract": "A confirmed-working saved provider key, ready to reference by name in start_preset/start_committee.",
            "failure_fallback": "test_byo_key is rate-limited to 10/hour independently of normal API limits.",
            "guardrail": null,
            "llm_required": true
        },
        {
            "id": "india_zero_cost_demo",
            "title": "India: Zero-Cost Technical Demo (no LLM key needed)",
            "description": "Lowest-friction way to exercise Investment Committee infrastructure without an LLM key or spending any committee-run quota — pairs a live technical scan with fast_scan_committee's free, deterministic lens only (no start_committee call). Good first call before setting up BYO keys.",
            "market": "india",
            "required_tier": "api_pro",
            "async": false,
            "status": "complete",
            "quota": null,
            "estimated_runtime": "under 1 min (both calls synchronous, no LLM involved).",
            "steps": [
                {
                    "id": "scan",
                    "tool": "market_trader_scan",
                    "description": "scan_type=allThree for the highest-confluence technical setups.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "fast_scan",
                    "tool": "fast_scan_committee",
                    "description": "Free, zero-LLM deterministic 3-lens scan of the shortlist — does not consume committee-run quota.",
                    "input_from": "$.stocks[*].symbol — up to 10",
                    "depends_on": [
                        "scan"
                    ],
                    "input_map": {
                        "symbols": "scan.stocks[*].symbol"
                    },
                    "max_items": 10,
                    "transport": "rest",
                    "external_call": "none"
                }
            ],
            "output_contract": "Deterministic technical/fundamental/risk-flag signal for technically-strong candidates — zero LLM tokens spent, no committee-run quota consumed.",
            "failure_fallback": null,
            "guardrail": "Signal-generation demo, not investment advice.",
            "llm_required": false
        },
        {
            "id": "us_zero_cost_demo",
            "title": "US: Zero-Cost Technical Demo (no LLM key needed)",
            "description": "US equivalent of india_zero_cost_demo.",
            "market": "us",
            "required_tier": "api_pro",
            "async": false,
            "status": "complete",
            "quota": null,
            "estimated_runtime": "under 1 min (both calls synchronous, no LLM involved).",
            "steps": [
                {
                    "id": "scan",
                    "tool": "us_market_trader_scan",
                    "description": "scan_type=stage2nh for Stage 2 + Near-High US setups.",
                    "depends_on": [],
                    "input_map": {},
                    "transport": "rest",
                    "external_call": "none"
                },
                {
                    "id": "fast_scan",
                    "tool": "fast_scan_committee",
                    "description": "Pass market:\"us\". Free, zero-LLM deterministic scan — does not consume committee-run quota.",
                    "input_from": "$.stocks[*].symbol — up to 10",
                    "depends_on": [
                        "scan"
                    ],
                    "input_map": {
                        "symbols": "scan.stocks[*].symbol"
                    },
                    "fixed_params": {
                        "market": "us"
                    },
                    "max_items": 10,
                    "transport": "rest",
                    "external_call": "none"
                }
            ],
            "output_contract": "Deterministic technical/fundamental/risk-flag signal for technically-strong US candidates — zero LLM tokens spent, no committee-run quota consumed.",
            "failure_fallback": null,
            "guardrail": "Signal-generation demo, not investment advice.",
            "llm_required": false
        }
    ]
}