feat: opt-in published Terraform modules from approved sources (iteration 8)

Infrastructure code is plain resources by default. An Execution may opt in
with terraform_modules; the deployment default is TERRAFORM_MODULES, off.

- A module is accepted only from the registry namespaces the provider bundle
  lists (terraform-google-modules), at one exact version. Any other source is
  refused before Terraform runs; until now nothing stopped generated code
  naming any source for terraform init to download.
- terraform_module looks up a module's inputs, outputs and submodules from
  the registry and says when it cannot be used with the pinned provider.
- skills/google-cloud-iac-modules: when a module fits, and four modules with
  examples a test validates against hashicorp/google 8.6.0.
- Opted in, the IaC author and validator get the Skill and the lookup. Not
  opted in, they get neither and a module block is refused in code.
- A Change request follows its Baseline. execution.json records the choice.
- case-07 runs case 03's request with modules opted into.

Azure (aztfm) and AWS (terraform-aws-modules) sources are recorded in the
plan for when those Cloud providers are added. No case has run with this.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-09 22:09:29 +01:00
parent a8ed21b89d
commit ef37f59bad
35 changed files with 1482 additions and 7 deletions

View File

@@ -108,6 +108,7 @@ class SolutionArchitectExecutor(AgentExecutor):
customer_case=options.get("customer_case"),
baseline=options.get("baseline"),
overlay_skills=options.get("overlay_skills") or (),
terraform_modules=options.get("terraform_modules"),
execution_id=task_id,
pre_approved=bool(options.get("pre_approved", False)),
allow_cloud_read=options.get("allow_cloud_read"),

View File

@@ -13,6 +13,7 @@ from pathlib import Path
from app.adk.runtime import RoleSpec
from app.providers import ProviderBundle
from app.skills.agent_skills import SkillFormatError, split_frontmatter
from app.tools.modules import MODULE_TOOL
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
ORCHESTRATOR = "orchestrator"
@@ -83,6 +84,12 @@ def load_roles(
f"'models.first_attempt' names {name!r}, which is not a role"
)
roles[name] = dataclasses.replace(roles[name], first_attempt_model=model)
if bundle.terraform_modules_skill:
for name, role in roles.items():
if MODULE_TOOL in role.tools:
roles[name] = dataclasses.replace(
role, modules_skill=bundle.terraform_modules_skill
)
unexpected = sorted(set(roles) - required - optional)
if unexpected:
raise RoleConfigError(

View File

@@ -37,6 +37,9 @@ class RoleSpec:
# A lighter model for the first attempt at a Deliverable, when the bundle
# names one and model tiers are on (iteration 5 step 6).
first_attempt_model: str | None = None
# The Skill on published Terraform modules, for a role that may call them. It
# is added to the role's Skills only in an Execution that opted into modules.
modules_skill: str | None = None
@dataclass(frozen=True)

View File

@@ -103,6 +103,8 @@ class ExecutionEngine:
skill_references: Mapping[str, Mapping[str, Mapping[str, str]]] | None = None,
skill_threshold: float = 1.25,
assess_at_end: bool = False,
modules_available: bool = False,
default_modules: bool = False,
) -> None:
required = {
ORCHESTRATOR,
@@ -112,6 +114,10 @@ class ExecutionEngine:
if missing:
raise ValueError(f"Missing roles: {', '.join(missing)}")
self._max_revisions = max_revisions
# Whether the Cloud provider approves any module sources, and whether an
# Execution uses them when its caller does not say.
self._modules_available = modules_available
self._default_modules = default_modules and modules_available
self._output_root = output_root
# Overlay Skills an Execution may name, with the version of each (ADR-0004).
self._overlays = dict(overlays or {})
@@ -153,6 +159,7 @@ class ExecutionEngine:
scripted_answers: Sequence[Sequence[str]] = (),
baseline: str | None = None,
overlay_skills: Sequence[str] = (),
terraform_modules: bool | None = None,
) -> Interaction:
"""Start an Execution. `scripted_answers` are (regex, answer[, asker]) entries a
pre-approved Execution uses to answer questions, for evaluation runs.
@@ -166,6 +173,12 @@ class ExecutionEngine:
this engagement's constraints. Each must be one the deployment has
configured; an unknown name refuses the start. Every Specialist loads them
with the ones the deployment loads by default.
`terraform_modules` opts the Execution into published Terraform modules
from the sources the Cloud provider approves. Left unset, a Change request
does as its Baseline did and any other Execution takes the deployment's
default, which is plain resources. Opting in is refused when the provider
approves no sources.
"""
customer_case = check_customer_case(customer_case)
execution_id = execution_id or str(uuid.uuid4())
@@ -187,6 +200,19 @@ class ExecutionEngine:
if baseline
else None
)
if terraform_modules is None:
terraform_modules = (
bool(loaded.get("terraform_modules"))
if loaded
else self._default_modules
)
if not isinstance(terraform_modules, bool):
# A ValueError is what callers turn into a refused start.
raise ValueError("terraform_modules must be true or false") # noqa: TRY004
if terraform_modules and not self._modules_available:
raise ValueError(
"terraform_modules: this Cloud provider has no approved module sources"
)
if pre_approved and allow_cloud_read is None:
allow_cloud_read = False
session_id = session_id or str(uuid.uuid4())
@@ -208,6 +234,7 @@ class ExecutionEngine:
"baseline": loaded,
# Overlay Skills this Execution loads, each with the version it had.
"overlay_skills": {name: self._overlays[name] for name in chosen},
"terraform_modules": terraform_modules,
"risks": [],
"pre_approved": pre_approved,
"allow_cloud_read": allow_cloud_read,
@@ -404,6 +431,7 @@ async def open_assembly(
timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS,
plugin_cache_dir=settings.terraform_plugin_cache(),
providers=bundle.terraform_providers,
module_namespaces=bundle.terraform_module_namespaces,
)
offered = [name for names in bundle.tools.values() for name in names]
# One cap for Specialists and the pillar advisors they fan out to.
@@ -482,6 +510,8 @@ async def open_assembly(
else None,
skill_threshold=settings.JEV_SKILL_THRESHOLD,
assess_at_end=settings.JEV_ASSESS_EXECUTIONS,
modules_available=bool(bundle.terraform_module_namespaces),
default_modules=settings.TERRAFORM_MODULES,
overlays={
name: skill_version(meta.path) for name, meta in overlays.items()
},

View File

@@ -101,6 +101,8 @@ def load_baseline(
"customer_case": customer_case,
"workflow_request": manifest.get("workflow_request", ""),
"baseline": manifest.get("baseline"), # what it was itself changed from
# Whether its code was allowed published modules; a Change request follows.
"terraform_modules": bool(manifest.get("terraform_modules")),
"deliverables": deliverables,
# Working material worth starting from again, such as pillar advice.
"working": working,

View File

@@ -61,6 +61,11 @@ class Settings(BaseSettings):
# Overlay Skills every Execution loads, comma-separated.
DEFAULT_OVERLAY_SKILLS: str = ""
# Whether an Execution may use published Terraform modules when its caller does
# not say. Off: infrastructure code is plain resources, and a caller opts in
# per Execution with `terraform_modules`. The sources are the provider bundle's.
TERRAFORM_MODULES: bool = False
# Give Specialists the lessons Skill. Off runs without anything learned, which
# is how the evaluation shows whether a lesson helps.
LESSONS_ENABLED: bool = True

View File

@@ -71,6 +71,7 @@ def create_app(
customer_case=body.get("customer_case"),
baseline=body.get("baseline"),
overlay_skills=body.get("overlay_skills") or (),
terraform_modules=body.get("terraform_modules"),
pre_approved=True,
allow_cloud_read=bool(body.get("allow_cloud_read", False)),
)

View File

@@ -53,6 +53,7 @@ from app.tools.assessment import assess
from app.tools.execution import ORCHESTRATOR, OrchestratorToolbox, specialist_tools
from app.tools.guardrail import EXECUTION_SCOPE, instructs_agent
from app.tools.meaning import settle_meaning
from app.tools.modules import MODULE_TOOL, MODULES_OPTED_IN
from app.tools.pillars import ADVICE_KEY, KEPT_FOR_CHANGES, pillars_touched
from app.tools.skill_routing import read_first
from app.workflows.chain import (
@@ -458,6 +459,15 @@ def make_execution_nodes(
role = dataclasses.replace(
role, skills=(*role.skills, *(n for n in named if n not in role.skills))
)
opted_in = bool(task_input.get("terraform_modules"))
MODULES_OPTED_IN.set(opted_in)
if opted_in and role.modules_skill:
role = dataclasses.replace(role, skills=(*role.skills, role.modules_skill))
elif MODULE_TOOL in role.tools:
# Plain resources: no modules Skill and no module lookup.
role = dataclasses.replace(
role, tools=tuple(tool for tool in role.tools if tool != MODULE_TOOL)
)
if role.first_attempt_model and task_input.get("first_attempt"):
logger.info(
"[%s] %s takes %s for a first attempt",
@@ -874,6 +884,8 @@ def _specialist_input(
"first_attempt": not ledger.feedback(kind)
and (attempt == 1 or kind.value in deliverables),
"allow_cloud_read": state.get("allow_cloud_read"),
# Whether this Execution opted into published Terraform modules.
"terraform_modules": bool(state.get("terraform_modules")),
"working": dict(state.get("working", {}).get(kind.value, {})),
# Whether the user has been shown a draft of this Deliverable. Answering some
# other question about it, such as what to do after it stopped, is not that.
@@ -903,6 +915,9 @@ def _specialist_input(
# Skills carrying the organisation's standards or this engagement's
# constraints. Where one disagrees with general guidance, it wins.
"overlay_skills": sorted(state.get("overlay_skills") or {}),
# False: infrastructure code is plain resources. True: a published
# module may be used where the modules Skill says one fits.
"terraform_modules": bool(state.get("terraform_modules")),
# The pillars a change touches, when that could be judged: the design
# advisor consults those and keeps its earlier advice for the rest.
"pillars_to_consult": (hints or {}).get(kind.value),
@@ -1267,6 +1282,8 @@ def _write_outputs(
"baseline": (state.get("baseline") or {}).get("execution_id"),
# The overlay Skills it loaded, with the version of each.
"overlay_skills": dict(state.get("overlay_skills") or {}),
# Whether its infrastructure code was allowed published modules.
"terraform_modules": bool(state.get("terraform_modules")),
"status": status,
"warnings": list(state.get("warnings", [])),
# Flags a person should look at; nothing was done about them.

View File

@@ -72,6 +72,12 @@ class ProviderBundle:
# The Terraform providers generated code is written for, pinned so the schema
# lookup, the patterns and validation agree: {name: {source, version}}.
terraform_providers: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
# Registry namespaces generated code may take a Terraform module from. Empty
# means no module is accepted.
terraform_module_namespaces: tuple[str, ...] = ()
# The Skill that says which modules to use and when. It reaches a Specialist
# only in an Execution that opted into modules.
terraform_modules_skill: str | None = None
# The Skill approved lessons are published in (ADR-0004); None when the provider
# has none. A Specialist is given it once it holds lessons for its Deliverable.
lessons_skill: str | None = None
@@ -155,6 +161,21 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
"version": pin["version"],
}
module_namespaces = ((config.get("terraform") or {}).get("modules") or {}).get(
"namespaces"
) or []
if not isinstance(module_namespaces, list) or not all(
isinstance(item, str) and item for item in module_namespaces
):
raise fail("'terraform.modules.namespaces' must be a list of names")
modules_skill = ((config.get("terraform") or {}).get("modules") or {}).get(
"skill"
) or None
if modules_skill is not None and modules_skill not in skills:
raise fail(
f"'terraform.modules.skill' references unknown skill {modules_skill!r}"
)
tools = {}
for tier, tool_names in (config.get("tools") or {}).items():
if tier not in TIERS:
@@ -221,5 +242,7 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
role_skills=role_skills,
pillar_skills=pillar_skills,
terraform_providers=terraform_providers,
terraform_module_namespaces=tuple(module_namespaces),
terraform_modules_skill=modules_skill,
lessons_skill=lessons_skill,
)

View File

@@ -58,6 +58,7 @@ class ExecutionState(TypedDict, total=False):
workflow_request: str
risks: list[dict[str, Any]] # flags on what the user wrote, for a person to see
overlay_skills: dict[str, str] # overlay Skills this Execution loads -> version
terraform_modules: bool # opted into published Terraform modules
baseline: dict[str, Any] | None # a Change request's Baseline, read from its files
pre_approved: bool
allow_cloud_read: bool | None

View File

@@ -30,6 +30,7 @@ from pathlib import Path, PurePosixPath
from typing import Any
from app.adk.runtime import FILES_SCHEMA, ToolResult, ToolSpec, files_from_argument
from app.tools.modules import ModuleLookup, allowed_namespaces, check_module_sources
_MAX_OUTPUT = 8_000
_MAX_OUTLINE = 4_000 # one resource type, when several are looked up together
@@ -98,6 +99,10 @@ class TerraformRunner:
# The providers the schema lookup answers for, as the provider bundle pins them:
# {local name: {"source": ..., "version": ...}}.
providers: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
# Registry namespaces a `module` may come from, as the provider bundle lists
# them. `terraform init` downloads and evaluates whatever a source names, so
# with none listed every module call is refused.
module_namespaces: tuple[str, ...] = ()
# Terraform's plugin cache is not safe for concurrent installs.
_init_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
_schema_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
@@ -138,7 +143,9 @@ class TerraformRunner:
)
async def validate(self, files: Mapping[str, str]) -> ToolResult:
refusal = _check_files(files)
refusal = _check_files(files) or check_module_sources(
files, allowed_namespaces(self.module_namespaces)
)
if refusal:
return refusal
with tempfile.TemporaryDirectory(prefix="tf-validate-") as tmp:
@@ -153,7 +160,9 @@ class TerraformRunner:
async def plan(
self, files: Mapping[str, str], variables: Mapping[str, str] | None = None
) -> ToolResult:
refusal = _check_files(files)
refusal = _check_files(files) or check_module_sources(
files, allowed_namespaces(self.module_namespaces)
)
if refusal:
return refusal
variables = dict(variables or {})
@@ -582,6 +591,16 @@ LOCAL_TOOLS: dict[str, tuple[str, str]] = {
"cloud_read",
"Preview Terraform against the live cloud environment with a plan. Never applies.",
),
"terraform_module": (
"general",
(
"Look up a published Terraform module: its inputs, outputs and "
"submodules, and whether it works with the pinned provider. Give "
"`source` as <namespace>/<name>/<provider>, with //modules/<name> for "
"a submodule. `version` is optional and defaults to the latest. `find` "
"narrows the inputs to those matching the words given."
),
),
"terraform_schema": (
"general",
(
@@ -651,6 +670,32 @@ def local_tools(
"terraform_plan": lambda: checks(
"terraform_plan", _with_files(runner.plan, working_copy)
),
"terraform_module": lambda: ToolSpec(
"terraform_module",
LOCAL_TOOLS["terraform_module"][1],
{
"type": "object",
"properties": {
"source": {
"type": "string",
"description": (
"For example terraform-google-modules/network/google"
),
},
"version": {"type": "string", "description": "Such as 18.3.1"},
"find": {
"type": "string",
"description": "Words to look for in input names, comma-separated",
},
},
"required": ["source"],
},
ModuleLookup(
namespaces=runner.module_namespaces,
pinned={name: pin["version"] for name, pin in runner.providers.items()},
).describe,
tier="general",
),
"terraform_schema": lambda: ToolSpec(
"terraform_schema",
LOCAL_TOOLS["terraform_schema"][1],

300
app/tools/modules.py Normal file
View File

@@ -0,0 +1,300 @@
"""Terraform modules from a public registry (iteration 8).
Generated code may call a published module where one replaces several resources that
must be wired together. Two things keep that safe and checkable, and neither names a
Cloud provider: the provider bundle does.
- **Which modules.** `terraform init` downloads whatever a `source` names and
Terraform then evaluates it. So a module is accepted only from a registry
namespace the bundle lists, at one exact version. Anything else, a Git URL, a
local path or a version range, is refused before Terraform runs.
- **What a module accepts.** A module hides the resources a Check is about. The
lookup returns a module's inputs, outputs and submodules from the registry, and
says whether its provider requirements admit the version the bundle pins.
"""
from __future__ import annotations
import contextvars
import json
import logging
import re
from collections.abc import Mapping, Sequence
from dataclasses import dataclass, field
from typing import Any
import httpx
from app.adk.runtime import ToolResult
logger = logging.getLogger(__name__)
REGISTRY = "https://registry.terraform.io/v1/modules"
MODULE_TOOL = "terraform_module"
# Whether the Execution a Specialist is running in opted into modules. Set when a
# Specialist starts. Unset, outside an Execution, the runner's own list applies.
MODULES_OPTED_IN: contextvars.ContextVar[bool | None] = contextvars.ContextVar(
"terraform_modules_opted_in", default=None
)
NOT_OPTED_IN = (
"Refused: this Execution writes plain resources. Published modules are used "
"only when the Execution opts into them. Write the resources directly."
)
def allowed_namespaces(configured: Sequence[str]) -> tuple[str, ...]:
"""The namespaces a module may come from, here and now: none when the Execution
did not opt in."""
return () if MODULES_OPTED_IN.get() is False else tuple(configured)
_MODULE = re.compile(r'^\s*module\s+"([^"]+)"\s*\{', re.MULTILINE)
_SOURCE = re.compile(r'^\s*source\s*=\s*"([^"]*)"', re.MULTILINE)
_VERSION = re.compile(r'^\s*version\s*=\s*"([^"]*)"', re.MULTILINE)
_EXACT = re.compile(r"^\d+\.\d+\.\d+$")
# namespace/name/provider, with an optional //path/to/submodule
_REGISTRY_SOURCE = re.compile(
r"^([A-Za-z0-9_-]+)/([A-Za-z0-9_-]+)/([a-z0-9]+)(?://([\w./-]+))?$"
)
_MAX_INPUTS = 80
_DESCRIPTION = 140
@dataclass(frozen=True)
class ModuleCall:
name: str
source: str
version: str
def module_calls(files: Mapping[str, str]) -> list[ModuleCall]:
"""Every `module` block in the files, with the source and version it names."""
calls = []
for text in files.values():
for match in _MODULE.finditer(text):
body = _block(text, match.end())
source = _SOURCE.search(body)
version = _VERSION.search(body)
calls.append(
ModuleCall(
match.group(1),
source.group(1) if source else "",
version.group(1) if version else "",
)
)
return calls
def _block(text: str, start: int) -> str:
"""The text of a block whose opening brace ends at `start`, nested blocks
removed, so only its own arguments are read."""
depth, own, index = 1, [], start
while index < len(text) and depth:
char = text[index]
if char == "{":
depth += 1
elif char == "}":
depth -= 1
elif depth == 1:
own.append(char)
index += 1
return "".join(own)
def check_module_sources(
files: Mapping[str, str], namespaces: Sequence[str]
) -> ToolResult | None:
"""Refuse a module that is not from an allowed registry namespace at one exact
version. None when every module call is acceptable, or there are none."""
if any(
name.endswith(".tf.json") and '"module"' in text for name, text in files.items()
):
return ToolResult("Refused: write module calls in .tf files, not .tf.json.")
calls = module_calls(files)
if calls and MODULES_OPTED_IN.get() is False:
return ToolResult(NOT_OPTED_IN)
problems = []
for call in calls:
parsed = _REGISTRY_SOURCE.match(call.source)
if not parsed or parsed.group(1) not in namespaces:
allowed = ", ".join(namespaces) or "none are configured"
problems.append(
f'module "{call.name}": source "{call.source}" is not allowed. A '
"module comes only from these registry namespaces, as "
f"<namespace>/<name>/<provider>: {allowed}"
)
elif not _EXACT.match(call.version):
problems.append(
f'module "{call.name}": set `version` to one exact version, such '
f'as "1.2.3"; got "{call.version}"'
)
if problems:
return ToolResult("Refused: " + "; ".join(problems) + ".")
return None
# --- what a module accepts --------------------------------------------------------------
def admits(constraint: str, version: str) -> bool:
"""Whether a Terraform version constraint, such as ">= 6.2, < 8", admits an
exact version. An unreadable term is taken to admit it."""
wanted = _numbers(version)
for term in constraint.split(","):
match = re.match(r"^\s*(>=|<=|>|<|=|!=|~>)?\s*v?([\d.]+)", term)
if not match:
continue
operator, bound = match.group(1) or "=", _numbers(match.group(2))
if operator == "~>":
# ~> 3.0 admits 3.x; ~> 3.1.2 admits 3.1.x from 3.1.2.
upper = [*bound[:-1]]
if upper:
upper[-1] += 1
ok = wanted >= bound and (not upper or wanted < upper)
else:
ok = {
">=": wanted >= bound,
"<=": wanted <= bound,
">": wanted > bound,
"<": wanted < bound,
"=": wanted[: len(bound)] == bound,
"!=": wanted[: len(bound)] != bound,
}[operator]
if not ok:
return False
return True
def _numbers(version: str) -> list[int]:
return [int(part) for part in version.split(".") if part.isdigit()]
@dataclass
class ModuleLookup:
"""Reads a module's inputs and outputs from the registry."""
namespaces: tuple[str, ...] = ()
# The provider versions generated code is pinned to: {local name: version}.
pinned: Mapping[str, str] = field(default_factory=dict)
timeout_seconds: float = 20
_cache: dict[str, dict[str, Any]] = field(default_factory=dict, repr=False)
async def describe(
self, source: str = "", version: str = "", find: str = ""
) -> ToolResult:
parsed = _REGISTRY_SOURCE.match(source.strip())
if not parsed or parsed.group(1) not in self.namespaces:
allowed = ", ".join(self.namespaces) or "none are configured"
return ToolResult(
f'Refused: "{source}" is not a module from an allowed registry '
f"namespace. Give <namespace>/<name>/<provider>, optionally with "
f"//modules/<submodule>. Allowed namespaces: {allowed}."
)
namespace, name, provider, path = parsed.groups()
if version and not _EXACT.match(version):
return ToolResult(
'Refused: `version` is one exact version, such as "1.2.3".'
)
data = await self._fetch(f"{namespace}/{name}/{provider}", version)
if isinstance(data, ToolResult):
return data
part = data.get("root") or {}
if path:
wanted = path.strip("/")
part = next(
(
item
for item in data.get("submodules") or []
if item.get("path", "").strip("/") == wanted
),
None,
)
if part is None:
listed = ", ".join(
item.get("path", "") for item in data.get("submodules") or []
)
return ToolResult(
f"{namespace}/{name}/{provider} {data.get('version')} has no "
f"submodule at {path}. Its submodules: {listed or 'none'}."
)
return ToolResult(self._render(data, part, source, find))
async def _fetch(self, module: str, version: str) -> dict[str, Any] | ToolResult:
key = f"{module}/{version}" if version else module
if key in self._cache:
return self._cache[key]
try:
async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
response = await client.get(f"{REGISTRY}/{key}")
except httpx.HTTPError as exc:
return ToolResult(
f"The module registry could not be reached ({type(exc).__name__}). "
"Write the resources directly, from the patterns and the schema."
)
if response.status_code == 404:
return ToolResult(f"The registry has no module {module} {version}.".strip())
if response.status_code != 200:
return ToolResult(
f"The module registry answered {response.status_code} for {module}."
)
try:
data = response.json()
except json.JSONDecodeError:
return ToolResult(f"The registry's answer for {module} was not readable.")
self._cache[key] = data
return data
def _render(
self,
data: Mapping[str, Any],
part: Mapping[str, Any],
source: str,
find: str,
) -> str:
version = data.get("version", "")
lines = [f'{source} version "{version}"']
for dependency in part.get("provider_dependencies") or []:
name, constraint = dependency.get("name", ""), dependency.get("version", "")
pin = self.pinned.get(name)
if pin and constraint and not admits(constraint, pin):
lines.append(
f"NOT USABLE: it requires {name} {constraint}, and the code is "
f"pinned to {name} {pin}. Write the resources directly."
)
elif not pin and name:
lines.append(
f"It also uses the {name} provider ({constraint or 'any version'});"
" Terraform installs it."
)
inputs = sorted(
part.get("inputs") or [],
key=lambda item: (not item.get("required"), item.get("name", "")),
)
if find:
wanted = [word.strip().lower() for word in find.split(",") if word.strip()]
inputs = [
item
for item in inputs
if any(
word
in f"{item.get('name', '')} {item.get('description', '')}".lower()
for word in wanted
)
]
lines.append(f"Inputs matching {find}: {len(inputs) or 'none'}")
else:
lines.append(f"Inputs ({len(inputs)}; required first):")
for item in inputs[:_MAX_INPUTS]:
need = "required" if item.get("required") else "optional"
kind = " ".join(str(item.get("type", "")).split())[:60]
about = " ".join(str(item.get("description", "")).split())[:_DESCRIPTION]
lines.append(f"- {item.get('name')} ({need}, {kind}): {about}")
if len(inputs) > _MAX_INPUTS:
lines.append(f"[{len(inputs) - _MAX_INPUTS} more; use `find`]")
outputs = [item.get("name", "") for item in part.get("outputs") or []]
if outputs and not find:
lines.append("Outputs: " + ", ".join(outputs))
submodules = [item.get("path", "") for item in data.get("submodules") or []]
if submodules and not find:
lines.append("Submodules: " + ", ".join(submodules))
return "\n".join(lines)