ask-physics：完全本地运行的物理问答工具，自研 Fermi 模型加 Noether 数学引擎

100% free, forever. That's why it's the best way to go.

Ask any physics question, from a textbook problem to "how many rubber ducks would it take to stop a freight train?", and get an answer you can check: the equations it used (with ids and sources), every assumption spelled out, units verified end to end, and an honest confidence score. Both halves are built here, run on your machine, and call no external APIs:

The Fermi models, our own language models trained from scratch: fermi-tellus-1 (~3M params), fermi-solem-1 (~30M), and fermi-celeste-1 (~120M). They read the question, pick the right equations, copy the values, and write the explanation. They never do math.
Noether, our math engine (named for Emmy Noether), built on SymPy and Pint, which solves the equations and checks every unit.

Meet the Fermi models

The artwork is rendered, not drawn: make brand runs scripts/brand.py, which ray-traces the black hole through Schwarzschild geodesics and lights the Moon, Earth, and Sun with numpy. Earth imagery: NASA Blue Marble Next Generation and NOAA ETOPO1 (public domain). Moon map: Solar System Scope, from NASA LRO data (CC BY 4.0). More in docs/MODELS.md.

Screenshots

Every screenshot is real CLI output, regenerated with make screenshots.

Install

macOS and Linux

curl -LsSf https://askphysics.vercel.app/installers/install.sh | sh

Windows (PowerShell)

irm https://askphysics.vercel.app/installers/install.ps1 | iex

Homebrew (macOS and Linux)

brew install shankar-sachin/tap/askphysics

The scripts install askphysics into its own isolated environment with uv, installing uv first if needed; they never touch your system Python. Pin a version with ASKPHYSICS_REF=v0.3.0. Uninstall with uv tool uninstall askphysics (or brew uninstall askphysics). The installer URLs serve the scripts in this repo's main branch (install.sh, install.ps1); read them first if you like. No API keys, no accounts: everything runs on your machine.

How it works

                 "How fast does a falling object hit the ground if dropped from 20 m?"
                                              |
                                              v
  +-----------+   +-----------+   +--------+   +-----------+   +--------------+   +---------+
  | 1 classify|-->| 2 retrieve|-->| 3 plan |-->| 4 compute |-->| 5 sanity     |-->| 6 explain|
  |  (tellus) |   | equation  |   |(solem:|   | symbolic  |   |   check      |   |(solem:  |
  | standard/ |   | database  |   | ids +  |   | algebra   |   | units, order |   |  prose   |
  | fermi/    |   | search    |   | values |   | machine:  |   | of magnitude |   |  only)   |
  | nonsense  |   |           |   | only)  |   | SymPy+Pint|   |              |   |          |
  +-----------+   +-----------+   +--------+   +-----------+   +--------------+   +---------+
                                                                                        |
                        19.8057 m/s  [kin_v_squared]  confidence: high (0.85)  <--------+
                        assumptions: released from rest, no air resistance, standard g

The planner can only cite equations that retrieval actually found, and it copies numbers and units out of the question without computing anything. Constrained decoding makes anything else impossible, not just unlikely. If solem can't produce a valid plan, celeste gets one shot (ADR-010). The machine does the algebra, and Pint rejects any calculation whose units don't add up. Confidence comes from a documented formula, never from the LLM grading itself. Full details: docs/ARCHITECTURE.md.

Quickstart

Requires Python 3.11 or newer. No API keys, ever. askphysics model pull downloads the Fermi models once their weights are published (v0.4); until you pull or train one, the default language model is a deterministic fake.

git clone https://github.com/shankar-sachin/ask-physics.git
cd ask-physics
python -m venv .venv && source .venv/bin/activate
make install            # pip install -e ".[dev]"

make test               # pytest with coverage
make lint typecheck     # ruff + mypy --strict

askphysics version
askphysics validate-data
askphysics ask "How fast does a falling object hit the ground if it is dropped from 20 m?"
askphysics ask --json "A rock is dropped from 45 meters. How fast does it land?"
askphysics ask "How much does the color blue weigh?"     # refused, with a redirect

Train a Fermi model yourself (the tiny fermi-luna-1 takes a minute on CPU; fermi-solem-1 wants the GPU in an Apple Silicon Mac or similar):

askphysics model build-data --examples 20000 --workers 4
askphysics model train-tokenizer --vocab-size 512
askphysics model train --model fermi-luna-1 --steps 1000
askphysics model info

Once a model is trained, askphysics ask uses it automatically: tellus classifies, solem plans and explains, a failed plan is retried up to 5 times, and celeste gets one more try (ADR-010). The answer card says which model did what. --model fermi-tellus-1 forces one model for everything, and --llm fake goes back to the fake client.

With no models installed, ask uses FakeLLMClient, which only has a canned plan for "dropped from a height" questions, on purpose. Ask it anything else and the pipeline tells you exactly which stage it couldn't complete, instead of making something up.

Project status: v0.3 released, v0.4 next

Area	Status
Six-stage pipeline with graceful degradation	Works
Noether: single-equation solve with units (SymPy + Pint)	Works
Dimensional consistency and order-of-magnitude sanity checks	Works
Keyword retrieval over the equation database	Works
Seed data with full validation: 110 equations, 20 worked examples (each re-solved by a test), 11 constants, 8 Fermi assumptions	Works
CLI: `ask`, `version`, `validate-data`, `model build-data / train-tokenizer / train / info`	Works
Confidence scoring (crude, documented formula)	Works
Eval set (8 questions) with a validating loader	Works
Fermi models: tokenizer, transformer, constrained decoding, data factory, training	Works
Fermi models answering in the CLI (router: tellus, solem, celeste)	Works with locally trained weights
`askphysics model pull`: checksum-pinned downloads, installers fetch the models	Works; weights publish with v0.4
Multi-equation chaining, Celsius and Fahrenheit	Works
Eval scoring and runner	Stub until v0.5
Vector and hybrid retrieval	Stub until v0.6
Fermi range propagation	Stub until v0.7
Limit-case checks	Stub until v0.8

Every stub raises NotImplementedError with a TODO describing the intended implementation.

Roadmap

v0.2 Fermi model foundations, v0.3 Fermi models wired in, v0.4 solem, shipped weights, solver expansion, and the docs, v0.5 eval harness, v0.6 retrieval and data expansion, v0.7 Fermi engine, v0.8 self-verification, v0.9 hardening, v1.0 release. After v1.0 comes the hosted API. The CLI is the main interface, and askphysics.vercel.app runs the same package in your browser (ADR-013). Details, deliverables, and exit criteria are in docs/ROADMAP.md; the near-term backlog is TODO.md.

Documentation

Ask Physics Docs: guides, FAQ, and a page for every equation
PLAN.md: vision, pipeline, Fermi and refusal policies, confidence model
docs/MODELS.md: the Fermi model family, its architecture, data, training, and routing
docs/ARCHITECTURE.md: modules, interfaces, one question traced through every stage
docs/DATA_SCHEMA.md and docs/DATA_SOURCING.md: what data looks like and where it comes from
docs/EVALS.md: how answers are graded
docs/DECISIONS.md, docs/RISKS.md, docs/OPEN_QUESTIONS.md
docs/RELEASING.md: how a release is tagged and the Homebrew tap bumped
docs/TRAINING.md: the runbook for training the Fermi models

Contributing

Read CONTRIBUTING.md first. The short version: the LLM never does arithmetic, every number has units, every equation has a source and a license, and data never enters the database without passing askphysics validate-data. Security reports go through SECURITY.md. Participation is covered by the CODE_OF_CONDUCT.md.

Limitations

Being straight about what this is right now:

It answers almost nothing yet. With the fake LLM, only "dropped from a height" questions get a number. That is the point of a skeleton.
The equation database is tiny. Twelve equations cover a slice of intro mechanics, E&M, and thermodynamics. Anything else hits a retrieval miss.
Keyword retrieval is brittle. Phrasing that shares no words with an equation's tags won't find it. Vector search arrives in v0.6.
Short chains only. Two-step problems work when the models recognize them; longer chains are rarer in the training data.
The Fermi models will be small. Trained from scratch at 3M to 120M parameters, they'll understand phrasings close to their training data and stumble on weird ones. When they stumble, the answer degrades. It never makes shit up.
Scalars only. No vectors and no numerical-only solutions yet (see docs/OPEN_QUESTIONS.md).
The confidence weights are invented. They get fit to eval data in v0.8.
Not for research-level physics, now or at v1.0.

License

MIT. Third-party software, fonts, and imagery keep their own licenses: see THIRD_PARTY_LICENSES.md. Data entries carry their own source and license fields; see docs/DATA_SOURCING.md.