Metadata-Version: 2.4
Name: augur-cli
Version: 0.3.0
Summary: A zero-dependency terminal tool to log forecasts, resolve them, and train your calibration.
Author: augur contributors
License: MIT License
        
        Copyright (c) 2026 augur contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/jarvismoney/augur
Project-URL: Source, https://github.com/jarvismoney/augur
Project-URL: Issues, https://github.com/jarvismoney/augur/issues
Project-URL: Changelog, https://github.com/jarvismoney/augur/blob/main/CHANGELOG.md
Keywords: forecasting,calibration,brier-score,decision-journal,superforecasting,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# augur

**Log your forecasts. Resolve them. Find out how good your probabilities actually are.**

`augur` is a small terminal tool for keeping a *calibrated forecasting journal*
and for *training* your calibration. You write down predictions with a
probability ("70% chance this ships by Friday"), resolve them when the outcome
is known, and `augur` scores you with the same proper scoring rules that
professional forecasters use — Brier score, log score, and a reliability
diagram that shows, of all the times you said "70%", how often it actually
happened.

Calibration is a trainable skill (Tetlock's *Superforecasting*; Hubbard's *How
to Measure Anything*; the Good Judgment Project), and being well-calibrated
makes you measurably better at decisions. Most tools for this are web services.
`augur` is the opposite: **local, private, and dependency-free.**

- **Zero dependencies.** Pure Python standard library. Nothing to `pip install`
  but the tool itself. It runs anywhere Python 3.9+ runs.
- **Local & private.** Your journal is a single SQLite file that you own. No
  account, no network, no telemetry.
- **Two things in one.** A *journal* for real-life predictions, and a *practice
  range* with built-in drills so you can train calibration on demand.

```
$ augur score

Calibration report
  You lean overconfident — surer than the outcomes justify.
  · On average you felt 81% sure and were right 62% of the time.
  · Weakest area: your 70-80% forecasts — you said about 75% but they happened 30% of the time.

  forecasts scored : 60
  brier score      : 0.156   (0 perfect · 0.25 = always 50%)
  brier skill      : +0.369   (vs. always guessing the base rate)
  log score        : 0.491 nats (0.708 bits)
  base rate        : 55% of statements came true
  reliability      : 0.0353  (calibration error, lower better)
  resolution       : 0.1243  (discrimination, higher better)
  confidence       : you felt 75.7% sure, were right 80.8% of the time — underconfident by 5.2%

100% │             ●
     │                 · ·
 80% │           ●   · ● ●
     │             ·
 60% │           ·
 40% │       · ●
     │   ●
 20% │   · ·
  0% │ ●   ●
     └────────────────────
      0   20  40  60  80
       forecast probability →  (● you, · ideal)
```

Every report **leads with plain English** — a one-line verdict and one or two
specific, honest takeaways — so you get the point without reading a wall of
statistics. The call-outs only fire when they're statistically significant
(Wilson intervals), so `augur` won't scold you over three lucky guesses. The
detailed metrics and the reliability diagram sit below for when you want them.

On the diagram, points on the dotted diagonal mean you're perfectly calibrated.
Points *below* it mean the thing happened less often than you predicted
(overconfident); *above* means it happened more often (underconfident).

## Install

`augur` needs only Python 3.9+. The recommended install is
[pipx](https://pipx.pypa.io/), which gives you an isolated `augur` command:

```bash
pipx install augur-cli   # once released on PyPI
augur --help
```

Or straight from the repo:

```bash
# run without installing
python -m augur --help

# or install the console script (still zero runtime dependencies)
pip install -e .
augur --help
```

> **Name collision note:** the PyPI package is `augur-cli` because
> [Nextstrain's `augur`](https://github.com/nextstrain/augur) (bioinformatics)
> already owns the `augur` name on PyPI — and it also installs an `augur`
> command. If you use Nextstrain, install this tool in its own pipx/venv, or
> alias the one you use less.

## Quickstart

```bash
# record a forecast: probability can be 35, 35%, or 0.35
augur add "Bitcoin above \$150k by end of 2026" -p 35 --by 2026-12-31 --tags crypto macro

# see what's open
augur list

# something came true (or didn't)
augur resolve 1 no

# what needs resolving now?
augur due

# how am I doing?
augur score
augur score --tag crypto      # per-topic
augur trend                   # calibration over time

# warm up / train calibration any time
augur practice                    # 90% confidence-interval drill
augur practice --mode confidence  # true/false-with-confidence drill
```

Running `augur` with no arguments shows a small dashboard (counts, what's due,
your current Brier score).

## The two practice drills

Real forecasts take weeks or months to resolve, so `augur` ships with a
fact-checked trivia bank you can drill against immediately:

- **Interval drill** (`augur practice`) — for each question you give a range
  you're **90% sure** contains the answer. A well-calibrated person's 90%
  ranges contain the truth about 90% of the time. Almost everyone starts out
  far too narrow (overconfident); `augur` tells you your true hit rate.

- **Confidence drill** (`augur practice --mode confidence`) — for each
  statement you say true/false and how sure you are (50–100%). You get a full
  Brier score and calibration table for the session.

## What the numbers mean

| Metric | Meaning | Good value |
| --- | --- | --- |
| **Brier score** | Mean squared error of your probabilities | Low. `0` is perfect; `0.25` is what "always 50%" gets you |
| **Log score** | Surprise of the outcomes under your forecasts (nats/bits) | Low. Punishes confident mistakes harshly |
| **Brier skill** | Skill vs. always predicting the base rate | `> 0` means real skill; `1.0` is perfect |
| **Reliability** | Calibration error — do your 70%s happen 70% of the time? | Low |
| **Resolution** | Discrimination — do you push away from the base rate when you should? | High |
| **Overconfidence** | Mean confidence minus actual accuracy | Near `0` |

The Brier score decomposes exactly (Murphy 1973) into
`reliability − resolution + uncertainty`, so `augur` can tell you *why* your
score is what it is: bad calibration, or simply not discriminating between
likely and unlikely events.

## Commands

| Command | Does |
| --- | --- |
| `add "<statement>" -p <prob> [--by DATE] [--tags ...] [--note ...]` | Record a forecast |
| `list [--status ...] [--tag T] [--since DATE] [--due] [--json]` | List forecasts |
| `show <id> [--json]` | Show one forecast in detail |
| `resolve <id> yes\|no\|void [--at DATE] [--note ...]` | Resolve a forecast |
| `edit <id> [--prob ...] [--by ...] [--tags ...] [--note ...] [--statement ...]` | Edit a forecast (`--by ""` clears the deadline) |
| `rm <id> [-y]` | Delete a forecast |
| `due` | Open forecasts past their resolve-by date |
| `score [--tag T] [--since DATE] [--bins N] [--json]` | Calibration report + reliability diagram |
| `trend [--buckets N]` | Brier score over time |
| `practice [--mode interval\|confidence] [-n N] [--seed S]` | Calibration drills |
| `export [--format json\|csv] [-o FILE]` | Export your journal |
| `import <file.json>` | Import forecasts |
| `stats` | One-line summary |

Dates accept ISO (`2026-12-31`), keywords (`today`, `tomorrow`), and relative
offsets (`+7d`, `+2w`, `+3m`, `+1y`).

## Data & privacy

Your journal lives in a single SQLite file. By default that's
`$XDG_DATA_HOME/augur/augur.db` (usually `~/.local/share/augur/augur.db`).
Override it per-command with `--db /path/to.db` or globally with the `AUGUR_DB`
environment variable. Back it up, sync it, or `augur export` it — it's yours.

Colour output auto-detects a terminal and honours `NO_COLOR`; force it with
`--color` / `--no-color`.

## Development

```bash
python -m pytest        # 80 tests, no third-party deps required to run the tool
```

The scoring math is covered by tests that pin the Brier/log values and check
the Murphy decomposition identity exactly. The bundled trivia bank was
independently verified by a fan-out of web-searching fact-check agents before
shipping.

## License

MIT — see [LICENSE](LICENSE).
