Skip to content

discovery_gate tool

Use discovery_gate after choosing a library with find and api, before any project code runs. It checks that the files call the chosen symbols with names and keywords that xpd's index knows, and that the record of the choice is consistent. It reads the source and runs nothing. Pass its result to gates as proof.discovery.

discovery_gate(paths, discovery)
fail if choice.name is not among the candidates
fail if the choice is a symbol and choice.symbols leaves it out
for each direct call to a name from the modules of choice.symbols
fail if api does not know it as a callable symbol
fail on a keyword that is not among its indexed parameters, and on ** arguments
fail for each chosen symbol that no call uses

It checks how the source spells each call, so it cannot see instance methods, runtime aliases, argument values or whether the library is installed.

discovery_gate(paths, discovery)
  • Changes no file
  • A second call with the same arguments changes nothing more
  • Stays inside the project

Tags: discovery, pipeline.

The server gives the agent this description of the tool.

Read Python files and check direct imported calls in the chosen symbols' modules.

Resolve import aliases and ask the binary's api for each direct call's dotted name. Require every chosen symbol to be called and every literal keyword to occur in the index's parameter list. Fail on unknown names and ** arguments. Run before equiv. This is a source spelling check, not Python name or type resolution. It cannot see instance methods, runtime aliases, shadowing, argument values, positional binding, required arguments, or dependency availability. The index may omit valid APIs and inherited or variadic parameters. It runs no project code and imports no library. Pass its result as proof.discovery, and save discovery in the training contract.

Type: list of string. Required.

The Python files or folders to check, inside the project root.

Type: object. Required.

The search, the entries read and the choice, as the agent recorded them.

The 52 fields of `discovery`
Field Type Required Default Description
discovery.question object yes The question that the agent asked find.
discovery.question.task string yes The task, as it was given to find.
discovery.candidates object yes Candidates ranked separately within each kind, including entries read through api.
discovery.candidates.symbols list of object no
discovery.candidates.symbols[].kind string yes
discovery.candidates.symbols[].package string yes
discovery.candidates.symbols[].name string yes
discovery.candidates.symbols[].callable "class", "function", "method", "property" or null yes
discovery.candidates.symbols[].parameters list of string yes
discovery.candidates.symbols[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.symbols[].summary string yes
discovery.candidates.symbols[].members list of object yes
discovery.candidates.symbols[].members[].name string yes
discovery.candidates.symbols[].members[].parameters list of string yes
discovery.candidates.symbols[].members[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.symbols[].members[].summary string yes
discovery.candidates.symbols[].members[].property boolean no false The member is read and not called.
discovery.candidates.symbols[].rules list of string yes
discovery.candidates.rules list of object no
discovery.candidates.rules[].kind string yes
discovery.candidates.rules[].package string yes
discovery.candidates.rules[].name string yes
discovery.candidates.rules[].callable "class", "function", "method", "property" or null yes
discovery.candidates.rules[].parameters list of string yes
discovery.candidates.rules[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.rules[].summary string yes
discovery.candidates.rules[].members list of object yes
discovery.candidates.rules[].members[].name string yes
discovery.candidates.rules[].members[].parameters list of string yes
discovery.candidates.rules[].members[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.rules[].members[].summary string yes
discovery.candidates.rules[].members[].property boolean no false The member is read and not called.
discovery.candidates.rules[].rules list of string yes
discovery.candidates.recipes list of object no
discovery.candidates.recipes[].kind string yes
discovery.candidates.recipes[].package string yes
discovery.candidates.recipes[].name string yes
discovery.candidates.recipes[].callable "class", "function", "method", "property" or null yes
discovery.candidates.recipes[].parameters list of string yes
discovery.candidates.recipes[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.recipes[].summary string yes
discovery.candidates.recipes[].members list of object yes
discovery.candidates.recipes[].members[].name string yes
discovery.candidates.recipes[].members[].parameters list of string yes
discovery.candidates.recipes[].members[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.recipes[].members[].summary string yes
discovery.candidates.recipes[].members[].property boolean no false The member is read and not called.
discovery.candidates.recipes[].rules list of string yes
discovery.choice object yes The candidate that the agent chose, and why.
discovery.choice.name string yes The selected candidate's exact name.
discovery.choice.reason string yes Why this candidate fits the task.
discovery.choice.symbols list of string yes Indexed callable symbols the code must call, including a recipe's symbols.
The 63 fields of the result
Field Type Required Default Description
discovery object yes
discovery.question object yes The question that the agent asked find.
discovery.question.task string yes The task, as it was given to find.
discovery.candidates object yes Candidates ranked separately within each kind, including entries read through api.
discovery.candidates.symbols list of object no
discovery.candidates.symbols[].kind string yes
discovery.candidates.symbols[].package string yes
discovery.candidates.symbols[].name string yes
discovery.candidates.symbols[].callable "class", "function", "method", "property" or null yes
discovery.candidates.symbols[].parameters list of string yes
discovery.candidates.symbols[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.symbols[].summary string yes
discovery.candidates.symbols[].members list of object yes
discovery.candidates.symbols[].members[].name string yes
discovery.candidates.symbols[].members[].parameters list of string yes
discovery.candidates.symbols[].members[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.symbols[].members[].summary string yes
discovery.candidates.symbols[].members[].property boolean no false The member is read and not called.
discovery.candidates.symbols[].rules list of string yes
discovery.candidates.symbols[].signature string or null yes Return indexed parameter names. parameters_written has the defaults and kinds.
discovery.candidates.rules list of object no
discovery.candidates.rules[].kind string yes
discovery.candidates.rules[].package string yes
discovery.candidates.rules[].name string yes
discovery.candidates.rules[].callable "class", "function", "method", "property" or null yes
discovery.candidates.rules[].parameters list of string yes
discovery.candidates.rules[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.rules[].summary string yes
discovery.candidates.rules[].members list of object yes
discovery.candidates.rules[].members[].name string yes
discovery.candidates.rules[].members[].parameters list of string yes
discovery.candidates.rules[].members[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.rules[].members[].summary string yes
discovery.candidates.rules[].members[].property boolean no false The member is read and not called.
discovery.candidates.rules[].rules list of string yes
discovery.candidates.rules[].signature string or null yes Return indexed parameter names. parameters_written has the defaults and kinds.
discovery.candidates.recipes list of object no
discovery.candidates.recipes[].kind string yes
discovery.candidates.recipes[].package string yes
discovery.candidates.recipes[].name string yes
discovery.candidates.recipes[].callable "class", "function", "method", "property" or null yes
discovery.candidates.recipes[].parameters list of string yes
discovery.candidates.recipes[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.recipes[].summary string yes
discovery.candidates.recipes[].members list of object yes
discovery.candidates.recipes[].members[].name string yes
discovery.candidates.recipes[].members[].parameters list of string yes
discovery.candidates.recipes[].members[].parameters_written list of string no The parameter list as the source writes it: each parameter with its type annotation and default, and a * or / that stands alone between parameters. A stub file writes ... for a default, which says only that the parameter is optional.
discovery.candidates.recipes[].members[].summary string yes
discovery.candidates.recipes[].members[].property boolean no false The member is read and not called.
discovery.candidates.recipes[].rules list of string yes
discovery.candidates.recipes[].signature string or null yes Return indexed parameter names. parameters_written has the defaults and kinds.
discovery.choice object yes The candidate that the agent chose, and why.
discovery.choice.name string yes The selected candidate's exact name.
discovery.choice.reason string yes Why this candidate fits the task.
discovery.choice.symbols list of string yes Indexed callable symbols the code must call, including a recipe's symbols.
paths list of string yes
gate object yes One requirement of a pipeline run, and whether the evidence meets it.
gate.name string yes
gate.stage "discovery", "raw data", "profile", "split", "preprocessing", "model", "validation", "proof", "persisted model" yes
gate.evidence list of "profile", "check", "graph", "equiv", "contract", "api", "source", "refit" yes The tools whose results decide the gate.
gate.passed boolean yes
gate.detail string yes What was found, or each reason the gate failed.

With the server's root at samples/pipeline, the call below passes the record in discovery.json.

{"paths":["train.py","predict.py","features.py"],"discovery":"(the contents of discovery.json)"}

The result repeats the record and the paths, and adds the gate.

{"name":"indexed-api-calls","stage":"discovery","evidence":["api","source"],"passed":true,"detail":"Checked 1 direct imported calls for indexed callable names and literal keyword names in api's parameter lists. No code was run."}

A record that does not match the schema fails before the gate runs. A failed check is a result, with passed: false and a detail that names the call.