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 usesIt 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.
Description
Section titled “Description”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.
Arguments
Section titled “Arguments”Type: list of string. Required.
The Python files or folders to check, inside the project root.
discovery
Section titled “discovery”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. |
Result
Section titled “Result”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. |
Example
Section titled “Example”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."}Errors
Section titled “Errors”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.