Development ¶

Development ¶

Basic Setup ¶

This is a uv workspace with two packages — corral (generic Frictionless engine) and netstead (GMNS toolkit on top). Install both packages with all extras, editable, in a single command from the repo root:

uv sync --all-packages --all-extras

That’s what CI runs. It creates .venv/ at the workspace root with both packages installed editable, plus every optional extra (polars, pandas, s3, gcs, azure, keyring, mcp, clean, server, notebook) so the full test suite + --doctest-modules sweep can collect every file.

Run things via uv run:

uv run netstead --help
uv run corral --help
uv run pytest packages -n auto    ## fast tier; see "Running tests" below

zsh users: [ and ] are glob characters on zsh (the default shell on macOS). If you want to install just one extra ad-hoc, quote the brackets: uv add 'netstead[clean]' (not uv add netstead[clean], which gives zsh: no matches found). The workspace-level uv sync --all-packages --all-extras doesn’t hit this — no brackets in the command.

One package at a time (rare) ¶

If you want to install only one of the two packages (e.g. to mimic what a downstream user sees):

uv pip install -e 'packages/corral[polars,s3]'    ## quoted for zsh
uv pip install -e 'packages/netstead[clean,server]'    ## transitively gets corral

Older / non-uv setup (not recommended) ¶

pip install -r dev-requirements.txt
pip install -e packages/corral
pip install -e packages/netstead

General Process ¶

1. Create an issue
2. Discuss approach
3. Complete contribution in a fork or branch.
4. Submit a pull-request
5. Respond to reviews

Periodically the develop branch will be merged with master and a tagged release will be made and distributed to PyPI.

By making any contribution to the projects, contributors self-certify to the Contributor Agreement.

Issues ¶

• Search existing issues to see if your issue has already been brought up.
• Create new issues to start discussion on a new topic, feature requests, and bugs; linking to any other relevant issues.
• Fill out issue template to the best of your ability.
• Indiciate urgency and if you are willing to work on it either using tags or in issue text.

Issues which do not have a clear user story may not be addressed

Consensus ¶

If issue is not super obvious/straightforward, please discuss approach with the maintainers/owner and reach a consensus.

Contributions which do not have consensus with the owner may not be approved

Coding ¶

Get assigned. If you are working on issue, please tag yourself as the assignee (or ask to be tagged if you do not have privledges).

Generally:

• Support Python 3.11+.
• DuckDB (via ibis) is the only compute engine; pandas / polars / Arrow are I/O formats at the edges. No raw SQL outside corral.engines.ibis_engine (scripts/lint_no_sql.py).
• Lint and format with ruff (uv run ruff check, uv run ruff format); pre-commit runs both.
• Use Google-style docstrings for public classes and functions
• Use logging
• All code should have an associated test
• Documentation lives in each package’s docs/ folder (packages/*/docs) and is built with mkdocs
• Public API is documented from docstrings in each package’s docs/reference/api.md
• Architecture lives in packages/corral/docs/architecture.md. Decisions, PRDs, designs and implementation plans go in docs/design/ — see its README for the conventions and the index of every record.
• Right now, this repo prioritizes Legibility/Simplicity >> Efficiency. That might change later.

Contributions which do not meet these requirements may not be approved

Running tests ¶

Tests live in packages/corral/tests and packages/netstead/tests and use pytest. Run them through uv run --all-extras from the repo root.

While iterating, run your domain. Before committing a cross-cutting change, run the default. Run the full suite before merge.

* Measured on an 8-core Apple-silicon laptop.

• Default skips tests marked slow (end-to-end runs, like executing every documented Python block or running the bench pipeline) and perf (performance-regression bounds). pyproject.toml sets this with -m "not slow and not perf" in addopts.
• Full adds -m "", which overrides that filter. Use -m slow or -m perf to run only one of those groups.
• -n auto runs tests in parallel with pytest-xdist (a dev dependency). It’s opt-in. Leave it off when you use --pdb or a single test. addopts pins --dist=loadfile so each test file stays on one worker.
• Naming a slow file is not enough. pytest packages/netstead/tests/test_cli_bench.py deselects everything in it unless you add -m "".
• live_llm tests call real provider APIs and skip unless you opt in. See the docstring of packages/netstead/tests/test_llm_live.py.

Per-domain commands ¶

Paths are relative to the repo root. T=packages/netstead/tests, D=packages/corral/tests.

A domain run skips the doctests in the source modules. The default run includes them.

Checking NL selection accuracy after prompt changes ¶

The tests check the parser’s plumbing, not how well a real model reads requests. After you change the selection prompt, the tool schema, or the assistant guide (netstead/llm/context), run the eval script by hand against a local model:

uv run --all-extras python scripts/eval_nl_selection.py --provider ollama --model qwen2.5:7b --runs 3

It parses each utterance in scripts/data/nl_eval_set.toml --runs times and prints per-utterance and total accuracy: correct (every field right), first-try (right without a repair) and resolves (right, or only a street name and route number swapped, which the resolver’s fallback recovers). Options you leave out follow your llm.quality settings. Compare against the numbers from before your change, and try --no-guide and --temperature default (Ollama’s own temperature), where small models make most of their mistakes. Add an utterance to the data file when you find a phrasing that a model gets wrong.

It never runs in CI. It calls whichever provider you name, so --provider anthropic, openai or gemini spends real tokens; the script says so before it starts.

CI ¶

.github/workflows/tests.yml always runs the full suite (-m "" -n auto), including slow and perf, on every push and PR across the Python matrix, plus the per-package coverage gates. bench.yml also runs the perf tests on their own, serially, on PRs that touch performance-critical paths.

Documentation ¶

Documentation uses mkdocs: one small umbrella site at the repo root plus a site per package.

1. Install the documentation dependency group

uv sync --all-packages --all-extras --group docs

1. Serve a site locally (umbrella, or a package’s own site)

uv run mkdocs serve                                  ## umbrella landing page
uv run mkdocs serve -f packages/netstead/mkdocs.yml  ## netstead docs
uv run mkdocs serve -f packages/corral/mkdocs.yml    ## corral docs

General settings for documentation can be found in mkdocs.yml

Each package site’s mkdocs-macros hooks (spec tables, live nav) are in packages/<pkg>/main.py

.github/workflows/documentation.yml builds the umbrella and both package sites and deploys them to GitHub Pages.

Pull Requests ¶

Use the following guidance in creating and responding to pull requests

• Submit PRs to main (the trunk). Branch as <type>/<slug>, e.g. feat/scope-zones.
• Keep pull requests small and focused. One issue is best.
• Link Pull Requests to Issues as appropriate.
• Complete the pull request template as best you can.
• PRs which don’t pass the automatic checks should either address issues causing them to fail or comment as to why they aren’t.
• Tag an available reviewer to review your PR.

Pull Requests which do not meet these requirements may not be approved

Review and Approval Process ¶

• PRs which don’t pass the automatic checks should either address issues causing them to fail or comment as to why they aren’t.
• Tag an available reviewer to review your PR.
• Respond to conversation and requests

Pull Requests which do not respond to reviews may not be approved

Contributor Agreement ¶

By making any contribution to the projects, contributors self-certify to the following Contributor Agreement:

By making a contribution to this project, I certify that:

a. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

b. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

c. The contribution was provided directly to me by some other person who certified (a), (b) or © and I have not modified it.

d. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

Attribution: This Contributor Agreement is adapted from the node.js project available here: https://github.com/nodejs/node/blob/main/CONTRIBUTING.md.

Contributor Covenant Code of Conduct ¶

tl;dr

give respect; get respect; or else.

Our Pledge ¶

We as Netstead Owners, Maintainers, and Contributors pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards ¶

Examples of behavior that contributes to a positive environment for our community include:

• Demonstrating empathy and kindness toward other people
• Being respectful of differing opinions, viewpoints, and experiences
• Giving and gracefully accepting constructive feedback
• Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
• Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

• The use of sexualized language or imagery, and sexual attention or advances of any kind
• Trolling, insulting or derogatory comments, and personal or political attacks
• Public or private harassment
• Publishing others’ private information, such as a physical or email address, without their explicit permission
• Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities ¶

The community leaders for this effort include project Owner and Maintainers as described in the Contributing documentation.

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope ¶

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.

Enforcement ¶

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to @e-lo or other package maintainers.

All complaints will be reviewed and investigated promptly and fairly.

Enforcement Guidelines ¶

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction ¶

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning ¶

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban ¶

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban ¶

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution ¶

This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla’s code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Contributors ¶

Elizabeth Sall - Owner Pedro Carmago - Maintainer Ian Berg - Contributors