> 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 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./pages/tGlnNUppZSD65MAWJvD0
Run a what-if sweepSee how sensitive the winner is to one variable./pages/CH2L7bZyy11m0bzX2E7J
Simulate a scenarioThe single-simulation request behind every action./pages/xo3kyzyPZXFb0ETopz2h
--- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.