io.github.Kromatic-Innovation/fermi

Buys Fermi credits by charging the card saved on your account, and returns the new balance. Use this when the user explicitly asks to buy or top up Fermi credits. Returns credits_purchased, new_balance and payment_status. If no card is saved yet, nothing is charged: it returns a checkout_url for the user to save a card in a browser, then call this again. Credits pay for estimates on an account (see estimate_quantity_or_probability for tier costs). To see the balance first, use check_account_and_credits. To get an account, call POST https://fermi.kromatic.com/api/v1/accounts (it returns an api_key once; a new account starts with 3 credits), or sign in through your connector. If you cannot make HTTP requests, ask the user to do one of these. Cost: real money -- charges the saved card $0.50 per credit. Needs an account.

Reports who you are to Fermi and what you can spend: whether you are using Fermi without an account or with one, your credit balance or free estimates left today, and what each tier costs. Use this before a paid estimate to check the price or balance, after one to see what is left, or when the user asks about credits, free estimates or pricing. Returns billing (principal "anonymous" or "account", how you authenticated, credit_balance, anonymous_estimates_remaining_today and anonymous_quota_resets_at), tiers (credit_cost, delivery "sync" or "async" and whether it is available without an account, per tier), price_per_credit_usd, and recent_transactions (the account's last 10 credit movements; null without an account). Cost: free. Checking never spends credits and never uses up a free estimate.

Estimates an uncertain number, or the probability that an event happens by a date, from a question in plain language, and returns a calibrated range and probability distribution. Use this when the user asks how much, how many, how big or how long something is or will be (market size, cost, count, price, duration), or asks a yes/no question about the future: "will X happen by <date>?", "what are the odds / chances / likelihood of X?". For a yes/no question, set unit to "probability (0-1)": point_estimate is then Fermi's best probability that the event happens (0.15 means 15%), and estimation_interval is how far that probability could plausibly be off (e.g. 0.05 to 0.35); the beta distribution describes the same uncertainty. There is no separate yes/no verdict. Returns point_estimate, estimation_interval (low/high: the range that should contain the true value, or for a yes/no question the true probability, with probability coverage_probability, default 90%), the fitted distribution (distribution_family and distribution_parameters), reasoning_summary, assumptions, estimate_id, and next_steps.simulate. To combine several estimates into a model with a time axis and get percentiles, NPV or payback out, feed them into neumann (https://neumann.kromatic.com) as simulation root nodes -- every successful estimate carries a next_steps.simulate block with the arguments already prepared. (neumann is Kromatic's companion Monte Carlo simulation server; fermi itself does not simulate.) The neumann URLs above are production. A non-production fermi still emits next_steps.simulate against its own configured neumann base URL, so read that block rather than these links whenever you are not on the production host. Tiers: 1 = fast, answers in the same call, no web search, and the only tier available without an account. 2 = grounded, answers in the same call, searches the web. 3 = deep research, runs in the background: the call returns status "pending" and an estimate_id; read the result later with get_estimate_result. Tier 1 does not know today's date or recent news: for any question about the future, put today's date and relevant recent facts in context, and give an absolute date in target_horizon. Not for: running a simulation or combining estimates (use neumann); reading prediction-market prices or placing bets; financial, medical or legal advice. To get an account, call POST https://fermi.kromatic.com/api/v1/accounts (it returns an api_key once; a new account starts with 3 credits), or sign in through your connector. If you cannot make HTTP requests, ask the user to do one of these. Cost: without an account, 3 free tier-1 estimates per UTC day; once they are used up, calls are refused with a sign-in requirement until 00:00 UTC. With an account, tier 1/2/3 costs 1/3/10 credits ($0.50/$1.50/$5.00 at $0.50 per credit). Tiers 1 and 2 charge only if the estimate succeeds, and a failed call does not use up a free estimate; tier 3 charges when it starts and refunds if it fails. Every call is a new estimate and is charged again, even for the same question. `credits_charged` and `billing` in the result report what was spent.

Reads one estimate you already requested, by its estimate_id. Use this when a tier-3 (deep research) estimate came back with status "pending" and you want to know whether it is finished, or to show an earlier estimate again. Tier-3 results are only delivered this way (or to a callback_url, which chat clients usually cannot receive). Returns status: "pending" (with retry_after_seconds: how long to wait before asking again), "completed" (with the same fields a finished estimate returns), or "failed" (with error_detail; any credits taken are refunded). You can only read estimates made with the same credentials. Without an account you are recognised by IP address and browser or client, so a different network or client may not find the estimate. To find an id you lost, use list_my_estimates. Not for: making a new estimate. Cost: free. Reading a result never spends anything.

Lists the past estimates on your account, newest first. Use this when the user wants to find an earlier estimate ("what did I estimate last week?") or has lost an estimate_id. Returns estimates, each with estimate_id, created_at, question, unit, target_horizon, point_estimate, estimation_interval, distribution_family and status; and next_offset, the offset of the next page, or null on the last page. For an estimate's full detail, pass its estimate_id to get_estimate_result. Estimates made without an account cannot be listed. To get an account, call POST https://fermi.kromatic.com/api/v1/accounts (it returns an api_key once; a new account starts with 3 credits), or sign in through your connector. If you cannot make HTTP requests, ask the user to do one of these. Cost: free, but account only: without an account the call is refused with a sign-in requirement.

Sends a short report about Fermi to the team that builds it. They read every report and use it to fix problems and decide what to build, so honest feedback, good or bad, is useful. Use this when: - a Fermi tool returned an error (send it right away), behaved unexpectedly or gave an estimate that looks wrong; - the user needs something no Fermi tool can do, or an option that is missing; - a description, output or error message was confusing; - a session in which you used Fermi is ending: send one short report even if everything worked. Knowing which tools did the job for which kind of question is useful data, not noise. Do not send one after a routine successful call mid-session. Put several points in one report. Only message is required. Fill in the other fields that apply so the team can act without guessing. Write in your own words. Never include personal data (names, email addresses, company names), the user's own numbers or private context, secrets or keys, or the conversation transcript; describe the question and any wrong result in general terms instead. Tell the user you are sending it. Add sender_email only if the user wants a reply; no copy is sent to it. If you are signed in, your account id is included. Returns status "sent". Cost: free. Works without an account.