> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/guides/recommend-and-score.md). # Recommend, score & compare Compare named actions and get a ranked recommendation, score a single scenario with custom weights, run many simulations at once, and compare scenarios side by side. Once you can simulate one scenario, these four endpoints turn simulations into a decision. `POST /v1/recommend` runs several named actions and returns the best one with a rationale. `POST /v1/score` scores a single scenario with weights you choose. `POST /v1/batch` runs many simulations in one request. `POST /v1/compare` puts scenarios side by side with deltas versus the winner. Every action or item is a normal [simulation request](/guides/simulate.md) (auto or expert), and all of them run in parallel on the engine. ## Before you start You need: * An API key sent as `Authorization: Bearer $ALGENTA_API_KEY` on a verified account. * One or more simulation requests. The examples use auto mode (`low`/`high` bounds); expert mode works everywhere a request is accepted. {% hint style="info" %} The Python and TypeScript pattern is identical for all four endpoints: `POST` the JSON body shown in each section to the endpoint path with the `Authorization` header. The Recommend section below shows all three languages; the others show the request and response. {% endhint %} ## Recommend an action Submit 2–10 named actions. The engine ranks them by expected value and returns the top one as `recommended_action`, with a structured `decision_plan` that is the best entry point for dashboards and LLMs. {% tabs %} {% tab title="cURL" %} ```bash curl -sS -X POST "https://api.algenta.ai/v1/recommend" \ -H "Authorization: Bearer $ALGENTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "actions": [ {"name": "launch_now", "request": {"mode": "auto", "scenario": { "variables": {"revenue": {"low": 80000, "high": 200000}, "cost": {"low": 40000, "high": 90000}}, "objective": "maximize_net_value"}}}, {"name": "wait_a_quarter", "request": {"mode": "auto", "scenario": { "variables": {"revenue": {"low": 60000, "high": 240000}, "cost": {"low": 35000, "high": 70000}}, "objective": "maximize_net_value"}}} ], "runs": 10000 }' ``` {% endtab %} {% tab title="Python" %} ```python import os import requests BASE = os.environ.get("ALGENTA_API_URL", "https://api.algenta.ai") resp = requests.post( f"{BASE}/v1/recommend", headers={"Authorization": f"Bearer {os.environ['ALGENTA_API_KEY']}"}, json={ "actions": [ {"name": "launch_now", "request": {"mode": "auto", "scenario": { "variables": {"revenue": {"low": 80000, "high": 200000}, "cost": {"low": 40000, "high": 90000}}, "objective": "maximize_net_value"}}}, {"name": "wait_a_quarter", "request": {"mode": "auto", "scenario": { "variables": {"revenue": {"low": 60000, "high": 240000}, "cost": {"low": 35000, "high": 70000}}, "objective": "maximize_net_value"}}}, ], "runs": 10000, }, ) resp.raise_for_status() result = resp.json() print(result["recommended_action"], result["confidence"], result["rationale"]) ``` {% endtab %} {% tab title="TypeScript" %} ```typescript const base = process.env.ALGENTA_API_URL ?? "https://api.algenta.ai"; const res = await fetch(`${base}/v1/recommend`, { method: "POST", headers: { Authorization: `Bearer ${process.env.ALGENTA_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ actions: [ { name: "launch_now", request: { mode: "auto", scenario: { variables: { revenue: { low: 80000, high: 200000 }, cost: { low: 40000, high: 90000 } }, objective: "maximize_net_value" } } }, { name: "wait_a_quarter", request: { mode: "auto", scenario: { variables: { revenue: { low: 60000, high: 240000 }, cost: { low: 35000, high: 70000 } }, objective: "maximize_net_value" } } }, ], runs: 10000, }), }); if (!res.ok) throw new Error(`recommend failed: ${res.status}`); const result = await res.json(); console.log(result.recommended_action, result.confidence); ``` {% endtab %} {% endtabs %} The `200` `RecommendResponse` ranks every action and names the winner: ```json { "recommended_action": "launch_now", "confidence": 0.71, "rationale": "'launch_now' ranked #1 with expected value 74213.5 and 82% probability of positive outcome.", "action_results": [ {"name": "launch_now", "rank": 1, "expected_value": 74213.5, "probability_of_loss": 0.18, "score": 0.71, "envelope": { "…": "full DecisionEnvelope" }}, {"name": "wait_a_quarter", "rank": 2, "expected_value": 61044.2, "probability_of_loss": 0.24, "score": 0.64, "envelope": { "…": "full DecisionEnvelope" }} ], "total_actions": 2, "decision_plan": { "recommended_action": "launch_now", "confidence": 0.71, "expected_value": 74213.5, "options": ["…ranked options…"] } } ``` Each `ActionResult` includes the full `DecisionEnvelope`, its `rank`, `expected_value`, `probability_of_loss`, and a composite `score` (0–1). `decision_plan` folds all of that into one structured summary with per-option risk (p5/p95/probability of loss) and integrity hashes. ## Score a single scenario `/v1/score` runs one simulation and scores it with a weighted blend of expected value and downside risk. Omit `scoring_weights` to use the default `{"expected_value": 0.6, "downside_risk": 0.4}` (weights should sum to `1.0`). ```bash curl -sS -X POST "https://api.algenta.ai/v1/score" \ -H "Authorization: Bearer $ALGENTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "request": {"mode": "auto", "scenario": { "variables": {"revenue": {"low": 80000, "high": 200000}, "cost": {"low": 40000, "high": 90000}}, "objective": "maximize_net_value"}}, "scoring_weights": {"expected_value": 0.7, "downside_risk": 0.3} }' ``` ```json { "envelope": { "…": "full DecisionEnvelope" }, "score": 0.68, "score_breakdown": { "expected_value_component": 0.42, "downside_risk_component": 0.26, "expected_value_weight": 0.7, "downside_risk_weight": 0.3 } } ``` ## Compare scenarios side by side `/v1/compare` runs 2–10 named scenarios and returns each one with its delta versus the winning scenario, so you can build a comparison table directly from the response. ```bash curl -sS -X POST "https://api.algenta.ai/v1/compare" \ -H "Authorization: Bearer $ALGENTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "scenarios": [ {"name": "conservative", "request": {"mode": "auto", "scenario": { "variables": {"revenue": {"low": 70000, "high": 120000}}, "objective": "maximize_revenue"}}}, {"name": "aggressive", "request": {"mode": "auto", "scenario": { "variables": {"revenue": {"low": 50000, "high": 220000}}, "objective": "maximize_revenue"}}} ] }' ``` ```json { "winner": "aggressive", "margin": {"expected_value_delta": 12500.0, "probability_of_loss_delta": -0.04, "score_delta": 0.0}, "scenarios": [ {"name": "conservative", "envelope": { "…": "…" }, "delta_vs_best": {"expected_value_delta": -12500.0, "probability_of_loss_delta": 0.04, "score_delta": 0.0}}, {"name": "aggressive", "envelope": { "…": "…" }, "delta_vs_best": {"expected_value_delta": 0.0, "probability_of_loss_delta": 0.0, "score_delta": 0.0}} ] } ``` ## Run a batch `/v1/batch` runs 1–100 simulation requests in one call. Partial failures are allowed — a failed item carries `success: false` and an `error` string instead of an envelope. ```bash curl -sS -X POST "https://api.algenta.ai/v1/batch" \ -H "Authorization: Bearer $ALGENTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "items": [ {"mode": "auto", "scenario": {"variables": {"revenue": {"low": 80000, "high": 200000}}, "objective": "maximize_revenue"}}, {"mode": "expert", "simulation": {"variables": [{"name": "x", "distribution": "normal", "params": {"mean": 100, "std": 10}}], "objective_function": "x"}, "runs": 20000} ] }' ``` ```json { "total": 2, "succeeded": 2, "failed": 0, "results": [ {"index": 0, "success": true, "envelope": { "…": "…" }, "error": null}, {"index": 1, "success": true, "envelope": { "…": "…" }, "error": null} ] } ``` {% hint style="success" %} **Expected result** — `/v1/recommend` returns a `recommended_action` with a rationale and every action ranked; `/v1/score` returns a `score` in `0`–`1` with a `score_breakdown`; `/v1/compare` names a `winner` with per-scenario deltas; `/v1/batch` returns `succeeded + failed == total`. {% endhint %} ## Next steps
Log the decisionRecord the recommendation and its later outcome.Log decisions & record outcomes
Run a what-if sweepSee how sensitive the winner is to one variable.Run a what-if sweep
Simulate a scenarioThe single-simulation request behind every action.Simulate a scenario
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.algenta.ai/guides/recommend-and-score.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.