Skip to content

xpd find

Find libraries and rules for a task, without importing Python Use xpd find before you choose a library or a function for a task. It searches the library symbols, rules and recipes that ship with xpd for a task you describe in words, and it needs no library installed. A recipe is a short worked example from a library's documentation, or one of xpd's own playbooks. Read an entry it returns with xpd api before you write the call.

Terminal window
xpd find [OPTIONS] [QUERY]

<QUERY>

The task, in your own words, such as "grouped regression".

--package <PACKAGE>

Search only this library, by its Python import name, such as sklearn.

--kind <KIND>

Search only symbols, rules or recipes.

Values: symbol, rule, recipe.

--limit <LIMIT>

Maximum results per kind (defaults to 5 symbols, 3 rules and 3 recipes)

--format <FORMAT>

Print text, or JSON with symbols, rules and recipes.

Default: text.

Values: text, json.

--index <INDEX>

Additional index generated from local source.

--check <CHECK>

Run real discovery questions and fail if an expected entry misses the top five.

Cannot be combined with <QUERY>.

Terminal window
$ xpd find "rounded bars" --kind recipe
Recipes
plotly/recipe/rounded-bars [recipe]
Rounded Bars
pandas/recipe/round-each-value-in-the-index-to-the [recipe]
Round each value in the Index to the given number of decimals.
numpy/recipe/round-to-nearest-integer-towards-zero [recipe]
Round to nearest integer towards zero.

Without --kind, the output has the headings Symbols, Rules and Recipes, each ranked on its own. A symbol line shows the names of its parameters and its rule links.

A playbook is a recipe of xpd's own, which holds the house style for a kind of task. It has the asks it answers, a complete module that reports 0 issues under style = "strict", the commands to run in order and the rules that the code satisfies. xpd api prints all four parts.

Playbook What its code is Asks it answers, for example
xpd/recipe/pandas-pipeline Step functions that each return frame.assign(...), joined with pipe "build a robust pandas pipeline"
xpd/recipe/feature-module One typed function for each feature, named for the column it returns "write a feature engineering module"
xpd/recipe/linear-script A script that filtered and wrote a frame line by line, as one chain that xpd equiv proves equal "turn this non-linear code into a linear pipeline"
xpd/recipe/plotly-chart A line chart with a plain template, labels on the lines, and words and a unit on the axes "improve my charts"

A loose ask finds its playbook, because the asks of a playbook are part of the text that find searches.

Terminal window
$ xpd find "improve my charts" --kind recipe
Recipes
xpd/recipe/plotly-chart [recipe]
A plotly chart that passes the plotly pack. A chart in the house style follows the plotly rules, which apply Edward Tufte's book "The Visual Display of Quantitative Information" to plotly figures. The template is plain and set once, each line carries its own label in place of a legend, the axes carry words and a unit, and the value axis starts at zero.
Rules: plotly/default-template, plotly/legend-instead-of-labels, plotly/axis-title-column-name, plotly/bar-axis-without-zero, plotly/area-axis-without-zero, plotly/explicit-grid, plotly/boxed-axis-frame, plotly/redundant-color, plotly/rainbow-colorscale, plotly/pie-chart, plotly/rotated-tick-labels, plotly/all-caps-title
plotly/recipe/scatter-line-area-and-bar-charts [recipe]
Scatter, Line, Area and Bar Charts
plotly/recipe/polar-chart-with-plotly-express [recipe]
Polar chart with Plotly Express

Between two recipes with the same score, a playbook comes first. With the xpd plugin installed, xpd hook runs this search on each prompt and prints the playbook for the agent, so nobody has to ask for it. The playbooks are the Markdown files in rules/xpd/playbooks of the repository.

find ranks each group by keywords and by meaning, so "make the bars have soft corners" finds the recipe for rounded bars. The meaning comes from the EmbeddingGemma 300M model. The first find downloads the 333 MB model once with the project's Python, and later searches run offline. Without Python, without the download or with --index, find ranks by keywords only and prints one line on stderr that says why.

System Where the model is kept
XDG_CACHE_HOME is set $XDG_CACHE_HOME/xpd/models
Linux ~/.cache/xpd/models
macOS ~/Library/Caches/xpd/models
Windows %LOCALAPPDATA%\xpd\models

A match means the entry fits the words of the query. Class members are not results, so use api to read them.

--check FILE runs the search questions in a JSON file, each with the entries it should find, and fails when an expected entry is not in the top five of its own kind. It also fails when the code of a playbook has an issue under the strict style. The repository checks indexes/questions.json before each commit that changes an index.

Exit code Meaning
0 The search ran, even when nothing matched, or every question of --check passed
2 xpd could not run, a question of --check failed, a playbook has an issue, or an index could not be read