Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,10 @@ jobs:
with:
enable-cache: true

- name: Install Python 3.14
run: uv python install 3.14
- name: Install the newest supported Python (managed by scripts/python_support.py)
run: |
uv python install 3.15
echo "UV_PYTHON=3.15" >> "$GITHUB_ENV"

- name: Build (strict - warnings are errors)
env:
Expand Down
56 changes: 56 additions & 0 deletions .github/workflows/python-versions.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 Evan Gress
#
# Monthly reminder to ratchet the supported Python versions.
#
# Runs scripts/python_support.py status, which compares pyproject.toml with
# CPython's published release and end-of-life dates. When a new Python is out,
# or the oldest one we support has reached end-of-life, it opens (or updates) a
# GitHub issue with the exact commands to run. Policy: docs/python-versions.md.

name: python-versions

on:
schedule:
- cron: "17 6 1 * *" # 06:17 UTC on the 1st of every month
workflow_dispatch:

permissions:
contents: read
issues: write # to open the reminder issue

jobs:
status:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Install uv
uses: astral-sh/setup-uv@v6

# The script exits 1 when action is needed; capture that instead of
# failing the job, and keep its report for the issue body.
- name: Compare with CPython's support schedule
id: status
run: |
set +e
uv run --no-project scripts/python_support.py status > report.txt
echo "code=$?" >> "$GITHUB_OUTPUT"
cat report.txt

- name: Open or update the reminder issue
if: steps.status.outputs.code == '1'
env:
GH_TOKEN: ${{ github.token }}
TITLE: "Update supported Python versions"
run: |
existing=$(gh issue list --state open --search "in:title \"$TITLE\"" --json number --jq '.[0].number')
if [ -n "$existing" ]; then
gh issue comment "$existing" --body-file report.txt
else
gh issue create --title "$TITLE" --body-file report.txt
fi

- name: Fail on unexpected errors
if: steps.status.outputs.code != '0' && steps.status.outputs.code != '1'
run: exit 1
98 changes: 98 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 Evan Gress
#
# Builds the package and uploads it to PyPI when a GitHub Release is published.
# A manual run (Actions -> release -> "Run workflow") uploads to TestPyPI
# instead, for a dry run. Step-by-step guide: docs/releasing.md.
#
# Uses PyPI "Trusted Publishing": PyPI trusts this specific workflow in this
# specific repository, so no API token or password is stored anywhere.
# One-time setup on pypi.org and test.pypi.org is described in the guide.

name: release

on:
release:
types: [published]
workflow_dispatch:

permissions:
contents: read

jobs:
build:
name: build and check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Install uv
uses: astral-sh/setup-uv@v6

- name: Install the newest supported Python (managed by scripts/python_support.py)
run: |
uv python install 3.15
echo "UV_PYTHON=3.15" >> "$GITHUB_ENV"

# Refuse to publish a tag that does not match pyproject.toml's version,
# the most common release mistake.
- name: Check tag matches version
if: github.event_name == 'release'
run: |
version=$(uv version --short)
tag="${GITHUB_REF_NAME#v}"
if [ "$version" != "$tag" ]; then
echo "Tag $GITHUB_REF_NAME does not match pyproject version $version"; exit 1
fi

- name: Run the test suite
run: |
uv sync --all-groups --all-extras
uv run pytest -q

- name: Build sdist and wheel
run: uv build

- name: Check the package metadata renders on PyPI
run: uvx twine check --strict dist/*

- uses: actions/upload-artifact@v4
with:
name: dist
path: dist/

publish-testpypi:
name: upload to TestPyPI
if: github.event_name == 'workflow_dispatch'
needs: build
runs-on: ubuntu-latest
environment:
name: testpypi
url: https://test.pypi.org/p/first-principles-code
permissions:
id-token: write # lets the job prove its identity to (Test)PyPI
steps:
- uses: actions/download-artifact@v4
with:
name: dist
path: dist/
- uses: pypa/gh-action-pypi-publish@release/v1
with:
repository-url: https://test.pypi.org/legacy/

publish-pypi:
name: upload to PyPI
if: github.event_name == 'release'
needs: build
runs-on: ubuntu-latest
environment:
name: pypi
url: https://pypi.org/p/first-principles-code
permissions:
id-token: write
steps:
- uses: actions/download-artifact@v4
with:
name: dist
path: dist/
- uses: pypa/gh-action-pypi-publish@release/v1
48 changes: 38 additions & 10 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 Evan Gress
#
# Runs lint, format check, type check, and the pytest suite on every push to
# main and on every pull request.
# Runs lint, format check and type check once, then the pytest suite on every
# supported Python version, on every push to main and every pull request.
# Uses uv (the same tool the project develops with) so CI matches local dev.
#
# The version list below is managed by scripts/python_support.py (which also
# checks it agrees with pyproject.toml). Don't edit it by hand; run
# uv run scripts/python_support.py set --oldest X.Y --newest X.Y

name: tests

Expand All @@ -14,8 +18,8 @@ on:
branches: [main]

jobs:
pytest:
name: checks + pytest (Python 3.14)
checks:
name: lint + types + version policy
runs-on: ubuntu-latest
steps:
- name: Check out the repository
Expand All @@ -24,24 +28,48 @@ jobs:
- name: Install uv
uses: astral-sh/setup-uv@v6
with:
# Cache uv's package downloads between runs to speed up CI.
enable-cache: true

- name: Install Python 3.14
run: uv python install 3.14

- name: Sync dependencies (incl. dev group)
run: uv sync --all-groups
- name: Sync dependencies (all groups + the mcp extra)
run: uv sync --all-groups --all-extras

- name: Lint (ruff)
run: uv run ruff check .

- name: Check formatting (ruff format)
run: uv run ruff format --check .

# mypy checks against the *oldest* supported Python (pyproject.toml),
# so it flags standard-library features that version lacks.
- name: Type check (mypy)
run: uv run mypy

- name: Supported Python versions declared consistently
run: uv run scripts/python_support.py check

pytest:
name: pytest (Python ${{ matrix.python-version }})
runs-on: ubuntu-latest
strategy:
# Run every version even if one fails, so one PR shows the whole picture.
fail-fast: false
matrix:
python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
steps:
- name: Check out the repository
uses: actions/checkout@v4

- name: Install uv
uses: astral-sh/setup-uv@v6
with:
enable-cache: true
python-version: ${{ matrix.python-version }}

# setup-uv's python-version sets UV_PYTHON, so every uv command below
# (sync, run) uses this matrix entry's Python.
- name: Sync dependencies (all groups + the mcp extra)
run: uv sync --all-groups --all-extras

# --all-groups above installed the notebook tools, so this also
# executes every notebook and runs every example script.
- name: Run pytest
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@
[Ll]ib64
[Ll]ocal
[Ss]cripts
# ...but the project's own scripts/ folder (python_support.py) is source code.
!/scripts/
pyvenv.cfg
.venv
pip-selfcheck.json
Expand Down
39 changes: 39 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<!-- SPDX-License-Identifier: Apache-2.0 -->
<!-- Copyright 2026 Evan Gress -->

# AGENTS.md

Guidance for AI coding agents (Claude Code, Cursor, Aider, Codex, Continue, ...)
that write code **using** or **contributing to** this library.

## Using the library

- Import the domain classes from `fpc` and call methods on an instance:
`from fpc import Fluids; Fluids().reynolds_number(density=998, velocity=2, length=0.05, viscosity=1e-3)`.
- **Every argument is keyword-only.** Positional calls raise `TypeError`.
- **Units:** plain floats in SI unless the docstring's `[unit]` tag says
otherwise (e.g. `[degC]`, `[mm]`, `[mGy]`). Convert inputs before calling.
Pint quantities (`fpc.Q_`) are used only by `fpc.Beam`; see `docs/units.md`.
- **Find the right method** without reading every file:
- `llms.txt`: one line per method with parameter units;
- `uv run fpc search "keywords"` and `uv run fpc describe Domain.method`;
- `from fpc import registry; registry.search("...")` in Python.
- **Reference data** (water properties, materials, steel W-shapes) lives in
`fpc/data/*.csv` and is read with `fpc.Properties`; do not hard-code values
that are already in a table.
- Prefer calling an existing method over re-deriving a formula. If one is
missing, say so (and consider adding it; see below).

## Contributing to the library

Read `CLAUDE.md`, `CONTRIBUTOR.md` and `ROADMAP.md` first. House rules:

- Keyword-only arguments (`def method(self, *, ...)`), full type hints, and a
docstring with `:param name: description [unit]` for every parameter
(`[-]` for dimensionless) and a `:returns:` line with its unit.
`tests/test_registry.py` fails if a numeric parameter lacks a unit tag.
- Comment the *why*: this is a teaching codebase.
- After adding or renaming a public method, regenerate the index:
`uv run fpc llms-txt > llms.txt`.
- Checks before you finish: `uv run ruff check .`, `uv run ruff format .`,
`uv run mypy`, `uv run pytest`.
31 changes: 31 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<!-- SPDX-License-Identifier: Apache-2.0 -->
<!-- Copyright 2026 Evan Gress -->

# Changelog

All notable changes to this project are listed here. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
[Semantic Versioning](https://semver.org/) (while the version is `0.x`, minor
releases may still change the API).

## [Unreleased]

## [0.1.0] - first PyPI release

### Added

- Domain classes for dynamics, statics, modal analysis, thermodynamics,
fluids, materials, gears, electrical, mechatronics, controls, design
(root finding and optimization), reference-data properties, and radiology
(radiation, radiography, CT, MRI, ultrasound, DICOM).
- `fpc.registry`: a machine-readable catalogue of every calculation, built
from type hints and docstring unit tags.
- `fpc search`, `fpc describe`, `fpc run` and `fpc llms-txt` commands.
- `fpc-mcp`: an MCP server so local and hosted AI models can call the
library (install with the `mcp` extra).
- Type hints on every public method, and a `[unit]` tag on every numeric
parameter.
- `llms.txt` and `AGENTS.md` for AI coding assistants.
- Supports Python 3.11 to 3.15 (every CPython version not past end-of-life),
tested on each in CI. `scripts/python_support.py` keeps the range
consistent and a monthly job opens an issue when it is time to move it.
12 changes: 9 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,24 +15,29 @@ The original design lives in [SPEC.md](SPEC.md); the improvement backlog lives i

- `main.py` — displacement demo (closed form, `scipy` integration, library call) that prints results and saves a plot.
- `fpc/` — the installable package (import name `fpc`, distribution name `first-principles-code`). One class per engineering domain (Dynamics, Statics, Modal, Thermo, Fluids, Material, Gear, Electrical, Mechatronics, Controls, Utility, Design, Properties, plus the radiology set Radiation, Radiography, CT, MRI, Ultrasound, Dicom), the shared Pint registry in `fpc/units.py`, and the unit-aware `Beam` dataclass.
- `fpc/registry.py` — introspects every domain method (type hints + `[unit]` docstring tags) into a catalogue with JSON Schemas; drives `fpc search/describe/run`, the MCP server (`fpc/mcp_server.py`, command `fpc-mcp`, optional `mcp` extra) and the generated `llms.txt`. See `docs/ai.md`.
- `gui.py` — tkinter MATLAB-style console; the `Session` class is GUI-free and tested.
- `tests/` — pytest suite, run in CI (`.github/workflows/tests.yml`).
- `examples/` — one self-contained worked problem per script; `templates/` — copy-and-adapt starting scripts; `notebooks/` — Jupyter notebooks; `fpc/data/` — cited reference tables (CSV); `docs/` — mkdocs site sources and guides.
- `PACKAGES.md` — curated package list by engineering field.

## Tooling & commands

Python **3.14+**, managed with **uv**.
Python **3.11–3.15** (every CPython version not past end-of-life; see `docs/python-versions.md`), managed with **uv**. Write code that runs on the oldest supported version; ruff and mypy target it. Change the range only with `uv run scripts/python_support.py set --oldest X.Y --newest X.Y`.

```bash
uv sync --all-groups # install runtime + dev + notebook deps
uv sync --all-groups --all-extras # install runtime + dev + notebook deps + mcp extra
uv run main.py # run the main demo
uv run pytest # run tests (single test: uv run pytest path::test_name)
uv run ruff check . # lint
uv run ruff format . # format
uv run mypy fpc # type-check the package
uv run mkdocs serve # preview the API docs site
uv run pre-commit install # enable git hooks (ruff + pytest)
uv run fpc llms-txt > llms.txt # regenerate after changing public methods (a test checks it)
uv build # build sdist + wheel; releasing steps are in docs/releasing.md
uv run scripts/python_support.py check # supported Python versions consistent everywhere
uv run -p 3.11 pytest # run the tests on a specific Python (CI runs every supported one)
```

## Library architecture
Expand All @@ -46,5 +51,6 @@ Units: plain floats in SI units for quick formulas; Pint quantities (`fpc.units.
These exist to make the code itself a teaching tool — follow them in all new code:

- Use keyword-only arguments (`def method(self, *, ...)`) to demonstrate verbose, explicit variable passing.
- Every class and method gets a docstring with parameter units — they double as documentation examples.
- Every class and method gets a docstring with parameter units — they double as documentation examples. Write units as a `[unit]` tag on each `:param`/`:returns:` line (`[-]` for dimensionless); the registry parses them and a test enforces them.
- Type-hint every public method (`float`, `int`, `str`, `Literal[...]`, and `ArrayLike` / `FloatArray` from `fpc.hints` for arrays); the registry turns hints into JSON Schema.
- Comment significant code sections explaining the *why*, not just the *what*.
Loading
Loading