noether-physics 0.1.0__tar.gz

noether_physics-0.1.0/.gitattributes

@@ -0,0 +1,10 @@
+# Normalise line endings so the repo is identical on every platform.
+# Without this, a Windows checkout rewrites every file to CRLF and the next
+# contributor on Linux sees the whole tree as modified.
+* text=auto eol=lf
+
+# Binary assets git must not touch.
+*.png binary
+*.pdf binary
+*.tar.gz binary
+*.parquet binary

noether_physics-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+
+# Local data root, if the user points it inside the repo
+.noether/
+*.sqlite
+*.sqlite-*
+*.duckdb
+
+# Bulk artefacts stay outside the repo, referenced by manifest + checksum
+research/**/*.parquet
+research/**/*.pdf
+research/**/*.tar.gz
+!research/**/.gitkeep
+
+# Small tabular artefacts ARE tracked (see research/README.md size policy)
+!research/labels/*.json
+!research/results/*.json
+!research/benchmarks/*.yaml

noether_physics-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ranshiv Kumar
+
+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.

noether_physics-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: noether-physics
+Version: 0.1.0
+Summary: Physics research assistant: explains concepts with checked equations and live simulations, and verifies claims against real arXiv papers.
+Project-URL: Homepage, https://github.com/Ranshiv/noether-physics
+Project-URL: Repository, https://github.com/Ranshiv/noether-physics
+Project-URL: Issues, https://github.com/Ranshiv/noether-physics/issues
+Project-URL: Honest status, https://github.com/Ranshiv/noether-physics/blob/main/docs/DEFERRED.md
+Author-email: Ranshiv Kumar <ranshiv369@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arxiv,citations,latex,mcp,physics,quantum,qutip,research,simulation,sympy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: numpy>=1.26
+Requires-Dist: pint>=0.24
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: pylatexenc>=2.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: scipy>=1.13
+Requires-Dist: sympy>=1.13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: quantum
+Requires-Dist: qiskit>=1.2; extra == 'quantum'
+Requires-Dist: qutip>=5.0; extra == 'quantum'
+Description-Content-Type: text/markdown
+
+# NOETHER
+
+<!-- mcp-name: io.github.ranshiv/noether-physics -->
+
+**A physics research assistant that shows its work.**
+
+Explains physics concepts with everyday analogies, dimension-checked equations, worked examples it
+recomputes, and simulations it actually runs. Answers questions from real arXiv papers with every
+sentence anchored to a verbatim span. Audits your own draft's bibliography for references that don't
+exist.
+
+```bash
+pip install noether-physics
+noether explain decoherence
+```
+
+---
+
+## Read this before you trust it
+
+This is a research-integrity tool, so its limits matter more than its features.
+
+**The verification gate checks that a quote is real. It does not check that the quote supports the
+claim.** A claim can contradict its own citation and still pass. Demonstrated during development: a
+claim asserting *"the experiment detected a nonzero neutron EDM at five sigma"* was accepted while
+citing a passage reporting **d_n = 0.0 ± 1.1 × 10⁻²⁶ e·cm** — a null result. The quote was genuine,
+so the gate let it through. Closing that gap needs entailment checking, which needs a language
+model, and keeping the model outside the verifier is what makes the other guarantees meaningful. So
+every answer this tool emits ends by saying so, and **you should read the quotes.**
+
+**The reference resolver's false-positive rate is unmeasured.** It finds 86.5% of real references.
+Nobody knows how often it would confidently match a *fabricated* one. For a tool whose first
+promise concerns hallucinated citations, that is the most important number that does not yet exist.
+
+**It is small.** 58 papers in the test corpus, 8 concepts in the explanation library, quantum
+coverage limited to two-level systems and one cavity mode. No PDF fallback, so roughly 9% of
+quant-ph papers (measured: 5 of 55) cannot be ingested at all.
+
+[`docs/DEFERRED.md`](docs/DEFERRED.md) is the full account — every gap, with the measurement behind
+it. It is the honest document; this README is the summary.
+
+---
+
+## Why it exists
+
+2026 audits found a **17% phantom-citation rate** in AI-assisted survey papers — references
+resolving to no digital object — and roughly **146,900 AI-generated fake citations** across 2.5M
+papers in 2025. arXiv now bans authors who submit hallucinated references.
+
+Physics has a structural advantage nobody exploits: **arXiv distributes the actual LaTeX source.**
+Equations arrive with their `\label`s, citations with their `\cite` keys, sections with their real
+structure — read, not guessed. Tools in other fields OCR PDFs because their domains have no source.
+Physics does.
+
+## What it does
+
+**Explains.** Curated prose, not generated — then machine-checked. Every equation is parsed and
+dimension-checked; every worked example is *recomputed* and compared against its stored answer, so a
+typo in the library fails CI rather than teaching you a wrong number.
+
+```bash
+noether explain decoherence          # analogy, maths, worked example, live simulation
+noether concepts                     # what the library covers
+```
+
+**Simulates.** Six models — pendulum, damped/driven oscillator, projectile with drag (SciPy); Rabi,
+decoherence, Jaynes-Cummings (QuTiP). Every run halves the step size and reports the drift, and
+where a closed form exists the numerics are compared against it automatically.
+
+```bash
+noether simulate rabi --params "detuning=6.28" --bloch
+noether models
+```
+
+**Checks equations.** Undeclared symbols return `unknown`, never a guess — `h` is Planck's constant
+*or* a height, `T` a period *or* a temperature. `unknown` is not a pass.
+
+```bash
+noether eq 'T = 2 \pi \sqrt{\frac{L}{g}}' --units 'T=second,L=meter,g=meter/second**2' --vary 'L=0.1..2' --at 'g=9.81'
+```
+
+**Reads papers.** Ingests LaTeX source, so "equation 14" means the equation *the authors* numbered 14.
+
+```bash
+noether ingest 2001.11966
+noether equations arXiv:2001.11966
+noether find "vacuum Rabi oscillations"
+```
+
+**Audits your draft.** Resolves every `\bibitem` against arXiv, Crossref, OpenAlex and INSPIRE.
+Exits non-zero on unresolvable references or cite keys with no bibliography entry, so it works as a
+pre-commit hook.
+
+```bash
+noether audit path/to/your-paper.tex
+```
+
+## Measured results
+
+Run `noether bench status` yourself. As of the last run:
+
+| gate | result | threshold | verdict |
+|---|---|---|---|
+| equations | 100% (31/31) | 90% | pass |
+| retrieval | 83.3% (10/12) **at top-3 of 58 papers** | 80% | pass |
+| citations | 86.5% (32/37) | 85% | pass |
+
+Read these with their scope attached. "Right paper in the top 3" over 58 papers is a real task; over
+8 it was nearly free, and an earlier run reported a meaningless 100% because `top_k` exceeded the
+corpus size. The citation threshold is 85% rather than 100% because books, theses and pre-digital
+articles are genuinely not in any index — the residual failures on the nEDM letter are a 1954 Danish
+journal, a 1955 Pauli chapter and a 1982 Oxford book.
+
+## Use it from Claude
+
+```bash
+pip install "noether-physics[mcp]"
+claude mcp add --scope user noether -- python -m noether.mcp_server
+```
+
+14 tools. Claude reasons and writes; NOETHER retrieves, checks and records. There is deliberately no
+`write_answer` tool — the component that can hallucinate is not the component that decides what
+ships.
+
+## Install
+
+```bash
+pip install noether-physics              # core
+pip install "noether-physics[quantum]"   # + QuTiP simulations
+pip install "noether-physics[mcp]"       # + MCP server
+```
+
+Python 3.12+. From source: `uv venv && uv pip install -e ".[dev,quantum,mcp]"`, then `uv run pytest`
+(285 tests, no network — cassettes default to replay and a miss is an error, not a live fallback).
+
+## Terms
+
+arXiv forbids bulk crawling. This fetches one paper at a time behind a 3-second interval and caches
+permanently, so a given paper is downloaded exactly once. Every source, its rate limit and its terms
+are declared in `research/sources/source_registry.yaml`; a source not in that file is not called.
+
+**No AI-generated imagery.** Every figure is extracted from a real paper or rendered
+deterministically from code and data, and is tagged with which.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).
+
+The name honours Emmy Noether. The PyPI distribution is `noether-physics` because `noether` belongs
+to an unrelated [physical-units library](https://github.com/yunruse/noether); the command is
+`noether` either way.

noether_physics-0.1.0/README.md

@@ -0,0 +1,151 @@
+# NOETHER
+
+<!-- mcp-name: io.github.ranshiv/noether-physics -->
+
+**A physics research assistant that shows its work.**
+
+Explains physics concepts with everyday analogies, dimension-checked equations, worked examples it
+recomputes, and simulations it actually runs. Answers questions from real arXiv papers with every
+sentence anchored to a verbatim span. Audits your own draft's bibliography for references that don't
+exist.
+
+```bash
+pip install noether-physics
+noether explain decoherence
+```
+
+---
+
+## Read this before you trust it
+
+This is a research-integrity tool, so its limits matter more than its features.
+
+**The verification gate checks that a quote is real. It does not check that the quote supports the
+claim.** A claim can contradict its own citation and still pass. Demonstrated during development: a
+claim asserting *"the experiment detected a nonzero neutron EDM at five sigma"* was accepted while
+citing a passage reporting **d_n = 0.0 ± 1.1 × 10⁻²⁶ e·cm** — a null result. The quote was genuine,
+so the gate let it through. Closing that gap needs entailment checking, which needs a language
+model, and keeping the model outside the verifier is what makes the other guarantees meaningful. So
+every answer this tool emits ends by saying so, and **you should read the quotes.**
+
+**The reference resolver's false-positive rate is unmeasured.** It finds 86.5% of real references.
+Nobody knows how often it would confidently match a *fabricated* one. For a tool whose first
+promise concerns hallucinated citations, that is the most important number that does not yet exist.
+
+**It is small.** 58 papers in the test corpus, 8 concepts in the explanation library, quantum
+coverage limited to two-level systems and one cavity mode. No PDF fallback, so roughly 9% of
+quant-ph papers (measured: 5 of 55) cannot be ingested at all.
+
+[`docs/DEFERRED.md`](docs/DEFERRED.md) is the full account — every gap, with the measurement behind
+it. It is the honest document; this README is the summary.
+
+---
+
+## Why it exists
+
+2026 audits found a **17% phantom-citation rate** in AI-assisted survey papers — references
+resolving to no digital object — and roughly **146,900 AI-generated fake citations** across 2.5M
+papers in 2025. arXiv now bans authors who submit hallucinated references.
+
+Physics has a structural advantage nobody exploits: **arXiv distributes the actual LaTeX source.**
+Equations arrive with their `\label`s, citations with their `\cite` keys, sections with their real
+structure — read, not guessed. Tools in other fields OCR PDFs because their domains have no source.
+Physics does.
+
+## What it does
+
+**Explains.** Curated prose, not generated — then machine-checked. Every equation is parsed and
+dimension-checked; every worked example is *recomputed* and compared against its stored answer, so a
+typo in the library fails CI rather than teaching you a wrong number.
+
+```bash
+noether explain decoherence          # analogy, maths, worked example, live simulation
+noether concepts                     # what the library covers
+```
+
+**Simulates.** Six models — pendulum, damped/driven oscillator, projectile with drag (SciPy); Rabi,
+decoherence, Jaynes-Cummings (QuTiP). Every run halves the step size and reports the drift, and
+where a closed form exists the numerics are compared against it automatically.
+
+```bash
+noether simulate rabi --params "detuning=6.28" --bloch
+noether models
+```
+
+**Checks equations.** Undeclared symbols return `unknown`, never a guess — `h` is Planck's constant
+*or* a height, `T` a period *or* a temperature. `unknown` is not a pass.
+
+```bash
+noether eq 'T = 2 \pi \sqrt{\frac{L}{g}}' --units 'T=second,L=meter,g=meter/second**2' --vary 'L=0.1..2' --at 'g=9.81'
+```
+
+**Reads papers.** Ingests LaTeX source, so "equation 14" means the equation *the authors* numbered 14.
+
+```bash
+noether ingest 2001.11966
+noether equations arXiv:2001.11966
+noether find "vacuum Rabi oscillations"
+```
+
+**Audits your draft.** Resolves every `\bibitem` against arXiv, Crossref, OpenAlex and INSPIRE.
+Exits non-zero on unresolvable references or cite keys with no bibliography entry, so it works as a
+pre-commit hook.
+
+```bash
+noether audit path/to/your-paper.tex
+```
+
+## Measured results
+
+Run `noether bench status` yourself. As of the last run:
+
+| gate | result | threshold | verdict |
+|---|---|---|---|
+| equations | 100% (31/31) | 90% | pass |
+| retrieval | 83.3% (10/12) **at top-3 of 58 papers** | 80% | pass |
+| citations | 86.5% (32/37) | 85% | pass |
+
+Read these with their scope attached. "Right paper in the top 3" over 58 papers is a real task; over
+8 it was nearly free, and an earlier run reported a meaningless 100% because `top_k` exceeded the
+corpus size. The citation threshold is 85% rather than 100% because books, theses and pre-digital
+articles are genuinely not in any index — the residual failures on the nEDM letter are a 1954 Danish
+journal, a 1955 Pauli chapter and a 1982 Oxford book.
+
+## Use it from Claude
+
+```bash
+pip install "noether-physics[mcp]"
+claude mcp add --scope user noether -- python -m noether.mcp_server
+```
+
+14 tools. Claude reasons and writes; NOETHER retrieves, checks and records. There is deliberately no
+`write_answer` tool — the component that can hallucinate is not the component that decides what
+ships.
+
+## Install
+
+```bash
+pip install noether-physics              # core
+pip install "noether-physics[quantum]"   # + QuTiP simulations
+pip install "noether-physics[mcp]"       # + MCP server
+```
+
+Python 3.12+. From source: `uv venv && uv pip install -e ".[dev,quantum,mcp]"`, then `uv run pytest`
+(285 tests, no network — cassettes default to replay and a miss is an error, not a live fallback).
+
+## Terms
+
+arXiv forbids bulk crawling. This fetches one paper at a time behind a 3-second interval and caches
+permanently, so a given paper is downloaded exactly once. Every source, its rate limit and its terms
+are declared in `research/sources/source_registry.yaml`; a source not in that file is not called.
+
+**No AI-generated imagery.** Every figure is extracted from a real paper or rendered
+deterministically from code and data, and is tagged with which.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).
+
+The name honours Emmy Noether. The PyPI distribution is `noether-physics` because `noether` belongs
+to an unrelated [physical-units library](https://github.com/yunruse/noether); the command is
+`noether` either way.