Skip to content

enrich — AgentTeamsModule

Default-value audit and context-aware enrichment for generated agent teams.

After build, scans agent files for unresolved {MANUAL:*} placeholders and underdeveloped template sections, exports an audit CSV, then attempts auto-enrichment using rule-based fills, project source scanning, and a built-in tool metadata catalog. An optional AI pass via the copilot CLI can fill anything that rule-based logic cannot resolve.

Placeholder policy note: - In default module runs, build_team.py may pre-resolve optional governance MANUAL placeholders (REFERENCE_DB_PATH, STYLE_REFERENCE_PATH) to explicit N/A values before enrichment executes. - In strict mode (--strict-manual-placeholders, default in --self), those placeholders remain unresolved and are handled by the enrichment/defaults-audit flow.

Source: agentteams/enrich/

Classes

DefaultFinding

Source: agentteams/enrich/_models.py

A single default-value (underdeveloped template) finding.

Attributes:

  • file (str) — Relative path to the agent file.
  • category (str) — 'MANUAL_PLACEHOLDER', 'GENERIC_SECTION', 'TOOL_METADATA', or 'MISSING_TOOL_REF'.
  • token (str) — The placeholder name or section label, e.g. COMPONENT_SPEC or STYLE_REFERENCE_PATH.
  • line_no (int) — 1-based line number of the finding in the agent file.
  • section (str) — Nearest ## section heading above the finding, or '' if in front matter.
  • context_snippet (str) — 1–2 lines of surrounding context.
  • status (str) — 'pending', 'auto_filled', or 'ai_filled' (set by auto_enrich or ai_enrich). Defaults to 'pending'.
  • auto_suggestion (str) — Suggested replacement value inferred from project context; empty string ("") when none was computed.

Functions

scan_defaults(file_map, manifest, project_path=None)

Source: agentteams/enrich/_audit.py

Scan generated agent files for unresolved default template elements.

Detects: {MANUAL:TOKEN} placeholders, tool reference files with incomplete metadata, underdeveloped sections (comment-only bodies, generic boilerplate), and packages imported in project source with no reference file.

Args:

  • file_map (dict[str, str]) — Rendered file content keyed by relative path.
  • manifest (dict[str, Any]) — Team manifest from analyze.build_manifest().
  • project_path (Path | None) — Project root; enables import scanning for coverage gaps.

Returns: list[DefaultFinding]

auto_enrich(findings, file_map, manifest, project_path=None)

Source: agentteams/enrich/_enrich.py

Apply all resolvable fills to file_map, returning an enriched copy.

Applies three fill strategies in order: rule-based fills for known token patterns, the built-in tool metadata catalog for TOOL_DOCS_URL, TOOL_API_SURFACE, and TOOL_COMMON_PATTERNS tokens, and notebook-header scanning for component specs.

Args:

  • findings (list[DefaultFinding]) — Findings from scan_defaults().
  • file_map (dict[str, str]) — Rendered file content keyed by relative path.
  • manifest (dict[str, Any]) — Team manifest from analyze.build_manifest().
  • project_path (Path | None) — Absolute path to the project repo root (enables notebook scanning).

Returns: tuple[dict[str, str], list[DefaultFinding]] — (enriched_file_map, updated_findings)

ai_enrich(findings, file_map, manifest, *, project_path=None, copilot_path=None)

Source: agentteams/enrich/_enrich.py

Fill remaining pending findings using the copilot CLI.

Called after auto_enrich to handle tokens that rule-based logic could not resolve. Invokes the standalone copilot CLI in non-interactive mode with the project context and list of pending findings. When copilot_path is None, the executable is auto-detected via shutil.which("copilot").

Args:

  • findings (list[DefaultFinding]) — Findings list (pending items will be targeted).
  • file_map (dict[str, str]) — Current rendered file map. Not mutated — a new enriched map is returned (the input copy is left unchanged; findings statuses, by contrast, are updated in place).
  • manifest (dict[str, Any]) — Team manifest.
  • project_path (Path | None, keyword-only) — Absolute path to the project repo root; passed to the CLI for additional context. Default: None.
  • copilot_path (str | None, keyword-only) — Absolute path to the copilot executable. When None, auto-detected via shutil.which. Default: None.

Returns: tuple[dict[str, str], list[DefaultFinding]] — (enriched_file_map, updated_findings)

generate_setup_required(findings, manifest)

Source: agentteams/enrich/_enrich.py

Generate SETUP-REQUIRED.md listing only genuinely pending findings.

Called after auto_enrich so that already-resolved tokens are excluded.

Args:

  • findings (list[DefaultFinding]) — Findings list with updated statuses after auto_enrich.
  • manifest (dict[str, Any]) — Team manifest.

Returns: str — Markdown string suitable for writing to SETUP-REQUIRED.md.

export_csv(findings, csv_path)

Source: agentteams/enrich/_enrich.py

Write findings to a CSV file.

Args:

  • findings (list[DefaultFinding]) — Findings to export.
  • csv_path (Path) — Destination path for the CSV file.

load_csv(csv_path)

Source: agentteams/enrich/_enrich.py

Load findings from a previously exported CSV file.

Args:

  • csv_path (Path) — Path to a CSV file written by export_csv().

Returns: list[DefaultFinding]

Source: agentteams/enrich/_enrich.py

Print a human-readable enrichment summary to stdout.

Args:

  • findings (list[DefaultFinding]) — Findings list after auto_enrich has set statuses.
  • verbose (bool, keyword-only) — If True, list all pending findings individually. Default: False.

scan_project_imports(project_path)

Source: agentteams/enrich/_tools.py

Scan Python source files in project_path for import statements and return a mapping of imported package names to their canonical PyPI names.

Args:

  • project_path (Path) — Root directory to scan (walks recursively).

Returns: dict[str, str] — {package_name: alias} — the canonical package name found in source, mapped to the import alias used.

build_tool_catalog(package_names, *, fetch_registries=True, fetch_pypi=None)

fetch_registries gates both the PyPI and npm lookups. fetch_pypi is a deprecated alias kept for back-compatibility: the npm tier was added under that flag without renaming it, so the name understated what it controlled — a caller passing fetch_pypi=False to avoid PyPI was also silently disabling npm. When given, the alias wins.

Source: agentteams/enrich/_tools.py

Build a metadata catalog for a list of packages, combining the built-in static catalog with optional live PyPI lookups.

Args:

  • package_names (list[str]) — PyPI package names to look up.
  • fetch_registries (bool, keyword-only) — Whether to fall back to a live registry lookup (PyPI, then npm) when the static catalog has no entry. Default: True.
  • fetch_pypi (bool | None, keyword-only) — Deprecated alias for fetch_registries (see note above). When given (not None), it wins over fetch_registries. Default: None.

Returns: dict[str, dict[str, str]] — Keyed by the package names exactly as supplied in packages (no normalization of the key); values contain docs_url, api_surface, and common_patterns.

See also

  • emit — produces the rendered file_map enrich scans and enriches, and writes the final SETUP-REQUIRED.md into the emitted team.
  • feature_audit — verifies documented features still function; the scheduled audit companion to enrich's default-value audit.