Knowledge Pack

Tip

  1. Need help? Please let us know in the SUEWS Community.

  2. Please report issues with the manual on GitHub Issues (or use Report Issue for This Page for page-specific feedback).

  3. Please cite SUEWS with proper information from our Zenodo page.

6.5. Knowledge Pack#

The SUEWS knowledge pack is a Git-bound source-evidence artefact for local agents. It is generated during package builds from the current repository checkout and installed inside the SuPy wheel. It is not hand-maintained source code, and it is not an MCP-specific data store.

6.5.1. Purpose#

The pack gives agents fast local evidence for implementation and model-design questions when an installed wheel no longer exposes the full source tree. In particular, the wheel contains compiled Fortran and Rust artefacts, but not the Fortran and Rust source files that determined their behaviour.

The pack therefore stores selected source text chunks with citations:

  • exact Git SHA

  • repository path

  • line span

  • chunk hash

  • GitHub permalink

The pack does not bundle the Sphinx documentation. Agents with network access should use the official documentation at https://docs.suews.io/stable/ or https://docs.suews.io/latest/ for tutorials, user-facing explanations, and broader documentation context.

6.5.2. Generation Policy#

The repository remains the source of truth. The generated pack is a build output, like a wheel or generated schema export.

The v1 build is deliberately deterministic and conservative:

  • use git ls-files where available, so untracked build artefacts, object files, caches, and target/ output are excluded;

  • include selected source roots rather than copying the full repository;

  • preserve source comments and code text rather than applying LLM summaries or irreversible cleaning;

  • split files into fixed windows with overlap, using line numbers only as citation coordinates.

6.5.3. Included Sources#

The installed v1 pack includes:

  • src/suews/src Fortran and C source files;

  • src/suews_bridge/src Rust source files;

  • Rust bridge build/provenance files such as Cargo.toml, build.rs, and bridge-manifest.json;

  • selected package-visible SuPy Python, schema, CLI, and metadata files.

The installed v1 pack excludes:

  • docs/source prose, images, publication pages, and large generated tables;

  • untracked build artefacts;

  • compiled objects and Rust target/ outputs;

  • binary package data.

6.5.4. CLI#

Inspect the installed pack:

suews knowledge manifest --format json

Query local evidence:

suews knowledge query "How is evaporation handled?" --format json

Build a pack from a checkout during development:

suews knowledge build --repo-root . --output /tmp/suews-knowledge --format json

6.5.5. MCP Integration#

The MCP layer should consume this artefact; it should not generate or own it. The planned MCP surface can expose the installed manifest and query results as resources/tools while preserving the same citations and Git SHA.