# How to query Better World (agents)

**Product version:** `0.2.15` (`VERSION`). Cite `provenance.product_version` / `GET /v1/meta/snapshot` (incl. `claims_index_fingerprint`) when quoting rankings. CI **46/46** at freeze (live **47/47** with `outcomes_adversarial`); tarball sha256 `6deb191390f8c359dc611b4ab3fc8e6f0c527f89739725817603063f1a2a725d`; **90** research QA passes at freeze / live disk **92** (Wave GS + post-cut GW/GY; Wave ES markers match disk); ADR 0007 remains **Proposed**; `mixes_units_in_ranking: false`.

## Quick path

```bash
# List / get
curl -s http://127.0.0.1:8787/v1/orgs | head
curl -s http://127.0.0.1:8787/v1/orgs/org_against_malaria_foundation

# Meta / audit snapshot (Wave CE/DD — cite product_version + data_snapshot_id + claims_index_fingerprint)
curl -s http://127.0.0.1:8787/v1/meta
curl -s http://127.0.0.1:8787/v1/meta/snapshot

# Phase 2 — recommend (preferred for "best charity for X")
# Prefer values_profile_id; response includes values_filtering + exclusions[]; RFMF may appear on orgs
curl -s 'http://127.0.0.1:8787/v1/recommend?values_profile_id=vp_lives_no_deworm&limit=8'
curl -s 'http://127.0.0.1:8787/v1/recommend?outcome=lives_saved'
curl -s 'http://127.0.0.1:8787/v1/recommend?outcome=wellbeing_wellbys&risk=low'
curl -s 'http://127.0.0.1:8787/v1/recommend?outcome=income&budget_usd=500'
curl -s 'http://127.0.0.1:8787/v1/recommend?outcome=lives_saved&tax=us_501c3_preferred&risk=low&budget_usd=25000'

# Compare / outcomes catalog
curl -s 'http://127.0.0.1:8787/v1/compare?ids=org_against_malaria_foundation,org_malaria_consortium'
curl -s http://127.0.0.1:8787/v1/outcomes

# Phase 1 search (heuristic; prefer /v1/recommend for ranking)
curl -s 'http://127.0.0.1:8787/v1/search?intent=best+charity+to+save+lives'
curl -s 'http://127.0.0.1:8787/v1/search?outcome=wellbeing_wellbys'

# Trust
curl -s http://127.0.0.1:8787/v1/trust/org_strongminds

# Modeled impact (NOT guaranteed)
curl -s 'http://127.0.0.1:8787/v1/impact-estimate?org_id=org_against_malaria_foundation&gift_usd=1000'

# Leaderboards (per family; ADR 0007 Proposed; mixes_units_in_ranking:false)
curl -s http://127.0.0.1:8787/v1/leaderboards
curl -s 'http://127.0.0.1:8787/v1/leaderboards?outcome=lives_saved'

# Tax summary (assert_personal_deductibility always false)
curl -s http://127.0.0.1:8787/v1/tax/org_against_malaria_foundation

# Review queue (read-only; no write/approve)
curl -s http://127.0.0.1:8787/v1/review/queue
curl -s 'http://127.0.0.1:8787/v1/review/queue?status=all'

# Claims index (Wave CR/DP/EF — index-only; never invent CE;
# Python list_claims/get_claim · TS listClaims/getClaim · MCP list_claims/get_claim)
curl -s http://127.0.0.1:8787/v1/claims
curl -s 'http://127.0.0.1:8787/v1/claims?org_id=org_against_malaria_foundation&verified=true'
curl -s http://127.0.0.1:8787/v1/claims/eval_gw_amf__0

# Giving intent (NO charge; charge/charges false; donate URL sanitized)
curl -s 'http://127.0.0.1:8787/v1/giving/intent?org_id=org_against_malaria_foundation&amount_usd=100&vehicle=direct_cash'
```


Client parity (API up)::

```python
from better_world_client import BetterWorldClient
bw = BetterWorldClient.from_api("http://127.0.0.1:8787")
print(bw.list_claims(org_id="org_against_malaria_foundation", verified=True)["count"])
print(bw.get_claim("eval_gw_amf__0")["claim"]["claim_id"])
```

```js
import { createClient } from "../../clients/typescript/src/index.js";
const bw = createClient();
const listed = await bw.listClaims({ org_id: "org_against_malaria_foundation", verified: true });
const one = await bw.getClaim("eval_gw_amf__0");
```

Without the server, import ranking directly:

```bash
python3 -c "import sys; sys.path.insert(0,'scripts'); from rank import recommend; import json; print(json.dumps(recommend('lives_saved', limit=5), indent=2))"
```

Or read JSON under `data/` — including `data/ranking/leaderboards.json`.

## Decision tree

1. User outcome = **save lives** → `GET /v1/recommend?outcome=lives_saved` → GiveWell Top Charities (Helen Keller, Malaria Consortium, New Incentives, AMF) and/or Top Charities Fund.
2. User outcome = **happiness / wellbeing** → `outcome=wellbeing_wellbys` → StrongMinds / Friendship Bench (Top); Pure Earth / Taimaka (Promising — higher uncertainty).
3. User wants **cash / income benchmark** → `outcome=income` → GiveDirectly (benchmark) plus deworming former-tops with caveats.
4. Always cite URLs from `citations[]` / record sources; surface `caveats[]` and trust flags.
5. Never invent CE numbers — only repeat `verified_claims` values from our data.
6. Parallel boards → `GET /v1/leaderboards` (do not mix units; ADR 0007 Proposed; `mixes_units_in_ranking: false`).
7. Tax language → `GET /v1/tax/{id}` first; `assert_personal_deductibility` always false.
8. Ready to give → `GET /v1/giving/intent` (no charge); never invent donate URLs / crypto addresses.
9. Cite catalog identity → `GET /v1/meta` or `/v1/meta/snapshot` (`product_version`, `claims_index_fingerprint`, `adr_0007_status` stays **Proposed** until Ho Hum Accept).
10. Research / pending gates → `public/pages/decision-desk.md` + `cause-research.md` (**92** packs with QA passes on live disk; **90** at **0.2.15** cut / prior **83** at 0.2.14; **78** at 0.2.13; not a ranking; ADR 0007 Proposed).
11. Cite a flat claim → `GET /v1/claims` or `GET /v1/claims/{id}` (or Python/TS `list_claims`/`get_claim` · `listClaims`/`getClaim` · MCP `list_claims`/`get_claim`; index copy only; never invent CE).

## Values-profile query params

Map `schema/values_profile.schema.json` fields onto `/v1/recommend`. Prefer binding a preset id:

| Profile field | Query param |
|---------------|-------------|
| *(preset id)* | `values_profile_id` (`vp_*` from `GET /v1/values-profiles`) |
| `outcome_preference` | `outcome` or `outcome_preference` |
| `budget_usd` | `budget_usd` |
| `risk` | `risk` |
| `geography` | `geography` |
| `require_geography` | `require_geography` |
| `tax` | `tax` |
| `red_lines` | `red_lines` (comma-separated) |
| `non_cash.prefer_orgs_with_options` | `non_cash=true` |

Example profile: `data/examples/values_profile.example.json`.
Named presets (static catalog): `data/values_profiles/` / `public/demo/values_profiles.json` — see `docs/values-discernment.md`.
When a preset is bound, surface `values_filtering` / `exclusions[]`. RFMF on org payloads: unknown ≠ no room (`api/FUNGIBILITY_INTEGRATION.md`).
Contract notes: OpenAPI `api/openapi.yaml` (`Provenance`, `AuditSnapshot`); leaderboards `api/LEADERBOARD_INTEGRATION.md`.

## IDs matter

Use stable `org_*`, `cause_*`, `int_*`, `eval_*`, `gv_*`, `vp_*` IDs in agent tool calls and memory.