nota

# Nota

An AI trading opinion you can audit. A council of specialised agents debates live RYO market
evidence and records the practice trade it would make as a **replayable decision receipt**:
`nota replay <id>` rebuilds it from the stored evidence and prints `identical: true`, every cited
number is read back out of the evidence rather than retyped by the model, and independent sources
audit RYO's own price and indicators before anything is sized. Built for the RYO-CHAN Hackathon 2026.

Tracks entered: **1 Autonomous Agents** (council, receipts, `watch` loop), **2 Dashboards**
(diff-first receipt dashboard), **3 New Skills** (`narrative_convergence`, `news_verify`,
`price_crosscheck`, `technicals_crosscheck`, all in RYO's envelope).

![Dashboard: thirty-second summary, what changed ranked by impact, open positions, skills panel](docs/img/dashboard.png)

<details><summary>More screenshots (replay verification, receipt card, phone layout)</summary>

![Verify replay from the page](docs/img/verify-replay.png)
![Receipt card used for link previews](docs/img/card.png)
![Phone layout](docs/img/mobile.png)

</details>

Screenshots are generated from the shipped demo ledger by `scripts/screenshots.py`.

**Watch it instead:** [nota-ryo.vercel.app/demo](https://nota-ryo.vercel.app/demo) — a narrated
1:47 walkthrough with a clickable transcript, or the bare file at `/demo.mp4`.

## How a decision is made

```
gather ──────────► council ──► judge ──► risk (pure ATR math) ──► receipt ──► ledger ──► notify
 5 RYO tools        macro       weighs      entry / stop / target      id = hash(evidence,   Telegram
 + own skills       technician  opinions    or Blocked when price       model, prompts)      Discord
 (price_check,      narrative   by Brier    or ATR is missing
  voices, news)                 weights
```

- **Evidence pack**: `market_overview`, `monitor_market_sentiment_shift`, `deep_analysis`,
  `analyze_token`, `compare_tokens` (the token against BTC/ETH peers). `scan_market` drives
  `nota scan`, RYO's recommended funnel. A failed tool becomes a section with status `error`;
  the pack still exists. Own skills are added as further sections (`price_check` by default,
  `narrative_signal` with `--voices`, `news_check` with `--news`).
- **Council**: three agents (macro, technician, narrative) each return a stance, a
  probability, and **citations as dotted paths into the evidence**. Citations that point at
  a missing or null value are dropped in code (after normalising `x[0].y` to `x.0.y`) and the
  opinion is downgraded.
- **Judge**: weighs opinions by each agent's historical Brier score and decides
  long / short / no_trade.
- **RYO's own plan is evidence, not an instruction**: `deep_analysis.data.trade_plan` carries RYO's
  ATR preview (entry, stop, targets, multiplier, method). Nota sizes independently and then reports
  the gap on the receipt: on the shipped ETH call, RYO stops at 2357.83 on a 1.5× ATR while this
  sizing uses 2.0×, so the stop sits 1.8% of entry lower and the first target 5.4% further, both in
  the same direction.
- **Risk**: a pure function. Stop = 2×ATR(14), target = 3×ATR, size from 1% account risk,
  capped at 20% of the account. No price or no ATR means **Blocked**, never a guessed number,
  and so does an ATR big enough to put the stop or target at or below zero: on an instrument that
  volatile the fixed-multiple rule does not apply, and a receipt must not print a negative price.
- **Replay**: LLM outputs are cached by `(evidence hash, role, prompt version, model)`.
  `nota replay <id>` reproduces the receipt exactly; `--fresh` re-asks the model and prints
  the drift honestly. The dashboard's "Verify replay" button does the cached check only.
- **Calibration**: `nota resolve --all` scores every decision whose seven-day horizon has
  passed (Brier per agent) against a fresh RYO price read, falling back to the exchange median
  from `price_crosscheck` when RYO cannot give a price; the outcome records which source was used.
- **Autonomy**: `nota watch SOL,BTC --every 3600 --notify` decides on a schedule, resolves
  matured decisions, and posts each new receipt to Telegram / Discord. `--scan-top 3` lets the
  loop pick its own candidates from `scan_market` every cycle.
- **Simulated data never trades**: when RYO marks the primary evidence `data_mode: simulated`,
  sizing is blocked and the receipt says so.
- **Transport**: REST (`/tools/{tool}/call`) by default, or MCP JSON-RPC (`tools/list`,
  `tools/call` on the same base URL) with `RYO_TRANSPORT=mcp`; `nota health` lists the live
  tool catalog over MCP when a key is set.

## The public surface is treated as public

`/api/skills/<name>/invoke` and `POST /mcp` are unauthenticated on purpose, so they are written for
strangers:

- A voice id goes into an outbound URL, so it is validated first. `../../evil` used to resolve to
  `https://t.me/evil`, which handed a caller the path on the target host; with redirects followed
  that is a step towards making this server fetch somewhere of their choosing. Handles are letters,
  digits, underscore, dot and hyphen, up to 64 characters, and anything else is refused before a
  request is built.
- `tools/call` over MCP is metered per address exactly like the REST route, 60 an hour, because it
  reaches third-party APIs. `initialize`, `tools/list` and `resources/*` stay free: they touch
  nothing outside the process.
- A JSON-RPC batch is capped at 25 messages, and `Origin` is validated on every MCP request as the
  transport spec's security section requires.
- Backing is capped at 30 an hour per address, and on the read-only deployment it answers 503 with
  an explanation rather than pretending to have written.

## Honesty rules this code enforces

- Every number in a receipt carries its source path, RYO `as_of`, `data_mode` and trace id.
- `null` / `unavailable` is never converted to 0 (`Envelope.get`, `first_present`, risk,
  every skill).
- Recorded fixtures keep RYO's original `as_of` and `data_mode` and are labelled
  `source: recorded`. Synthetic test fixtures live only under `tests/fixtures/` and are
  labelled `source: fixture`; receipts print the label. There is no fake-LLM mode in the CLI.
- The RYO surface is read-only; practice trades exist only in `nota.db`.
- A receipt says what it cost: model calls, cache hits, prompt and completion tokens, the provider's
  own billed figure, and wall time. Every one of those is what the provider reported, never derived
  from a price table this repository would have to keep correct - a figure that was not reported
  reads "not reported", and one silent call makes the whole total unknown rather than smaller.
  `spend` is deliberately outside the replay comparison: a cached rebuild spends nothing, so the
  field is a measurement, not a reproducibility claim.
- External sources say what they cannot do: Venice web search carries no dates, the X mirror
  is unofficial, RSS feeds that fail are listed, exchange prices never replace RYO's value.

## Run

```bash
uv sync
cp .env.example .env            # RYO_MCP_KEY + an LLM key (Anthropic, or NOTA_LLM=openai for Venice/OpenRouter)
uv run nota health             # MCP health (no key) + whoami/quota (with key)
uv run nota decide SOL         # live evidence + price cross-check, council, receipt
uv run nota decide SOL --voices tg:WatcherGuru,bs:decrypt.co,bs:unusualwhales.bsky.social --news --notify
uv run nota scan --top-n 5 --decide-top 2      # scan_market -> analyze_token -> council
uv run nota watch SOL,BTC --every 3600 --notify
uv run nota replay <id>        # identical: True
uv run nota replay <id> --fresh
uv run nota resolve --all      # after 7 days: Brier scores per agent
uv run nota scores
uv run nota record SOL         # capture all six live tools into fixtures/recorded
uv run nota decide SOL --source recorded   # replay those recordings without a key (after `record`)
uv run nota positions                      # open practice positions vs the latest independent price
uv run nota serve                          # http://127.0.0.1:8000 overview, /app dashboard, /mcp
uv run nota skill spec                     # Track 3 definitions
uv run nota skill run price_crosscheck '{"symbol":"SOL","reference_price":150}'
uv run pytest -q
```

## Skills (Track 3)

All four return RYO's public envelope field for field (`docs/skills/SKILL-SPEC.md`) and are
served on RYO's own skill paths, so plugging them into RYO is a route registration, not a port:
`GET /api/skills/` (SkillDefinition list), `GET /api/skills/{name}`, and
`POST /api/skills/{name}/invoke` taking `SkillCallRequest {name, args, conversation_id}` and
returning `SkillCallResponse {name, status: success|error, result, latency_ms, xp, guard_decision}`.
The dashboard's "Run a skill" panel builds its form from those definitions and shows the envelope.

- `narrative_convergence`: up to 20 voices (`tg:` public Telegram previews, `bs:` Bluesky public
  API, `x:` through X's own public syndication endpoint, the one that serves embedded timelines,
  with a Tavily fallback), VADER sentiment plus a crypto lexicon, conviction, urgency, and
  convergence detection. Silence is `null`, not 0. Nitter, which `x:` used to go through, was served
  cease-and-desist letters in August 2026 and its public mirrors went dark, so that reader was
  advertising a source that could not answer; syndication is keyless, dated and still open, and
  every failure is reported as `unavailable` rather than guessed. One measured limit worth knowing
  before you try it: syndication throttles hard, and it has tightened. It hit data-centre addresses
  first, so `x:` came back `unavailable` from the hosted demo while reading fine from an ordinary
  connection; as of 2026-09-10 an ordinary connection gets `syndication HTTP 429` too. Treat `x:` as
  best effort and `tg:` / `bs:` as the dependable readers - those two answer from both. Setting
  `TAVILY_API_KEY` turns the throttle into a search-backed fall