Pixie

Implements an academic paper (PDF or arXiv URL) as a NEW Pixie tool with reference fixtures from reported numbers. Use when the user gives a paper or arXiv link and asks to implement, reproduce, or replicate it. Do NOT use to cite (cite-source), for code (add-tool-from-repo), or specs (implement-model-from-spec).

Wraps a CLI binary or shell command (ffmpeg, curl, pandoc, imagemagick, yt-dlp) as a Pixie tool - generates tool.json from its flags plus a subprocess main.py, then validates. Use when the user names a CLI binary or shell command. Do NOT use for a Python script (wrap-local-script) or repo (add-tool-from-repo).

Generates a brand-new Pixie tool from a natural-language description - writes tool.json, pyproject.toml, main.py from scratch then validates. Use when the user asks to create, make, build, or generate a tool with NO artefact. Do NOT use given a Git URL, .py, .ipynb, .zip, Streamlit, Gradio, OpenAPI, or CLI binary.

Wraps an Excel .xlsx workbook as a Pixie tool by parsing its formula DAG and generating Python that reproduces every cell. Use when the user gives a .xlsx path and asks to wrap, port, or convert an Excel model. Do NOT use for .xlsm/.xlsb/.xls (refused), .csv (fetch-dataset-from-url), or prose.

Converts a Jupyter notebook (.ipynb) into a Pixie tool - extracts input/output cells, generates tool.json and FastAPI main.py, then validates. Use when the user gives a path to a .ipynb file and asks to add, wrap, convert, or import a notebook. Do NOT use for .py (wrap-local-script) or Streamlit (convert-streamlit-app).

Wraps a REST endpoint from an OpenAPI or Swagger spec as a Pixie tool - generates tool.json from spec parameters and a httpx main.py, then validates. Use when the user mentions OpenAPI, Swagger, openapi.yaml, or openapi.json. Do NOT use for a Python SDK repo (add-tool-from-repo) or vague API prose (add-tool-from-description).

Clones a Git repository and wraps its entrypoint as a Pixie tool - generates tool.json and FastAPI main.py then validates. Use when the user gives a Git URL and asks to add, clone, or wrap a repo. Do NOT use for .zip (import-tool), .py (wrap-local-script), .ipynb (add-tool-from-notebook), or prose (add-tool-from-description).

Archives a Pixie tool reversibly - hides it from the sidebar and deletes .venv to free disk; source kept. Use when the user asks to archive, hide, mothball, shelve, or stop using a tool without losing it. Do NOT use to delete forever (remove-tool), restore (unarchive-tool), or prune runs (clear-old-outputs).

Reports disk usage across EVERY Pixie tool - .venv, data, models, cache - sorted largest first, flagging archive candidates. Read-only. Use when the user asks about disk usage, storage, space, or footprint Pixie is taking. Do NOT use to inspect ONE tool (inspect-tool), live runtime (pixie-status), or lint style (lint-tool).

Bundles MANY Pixie runs or artefacts (a filtered set, not just one) into ONE zip server-side. Use when the user asks to bulk export, batch export, download many, archive runs, or package multiple outputs together. Do NOT use for one run (export-run, export-run-as-report), one artefact (export-as-format), or tool source (share-tool).

Records a citation, attribution, or source provenance (paper, Excel checksum, DOI, repo commit) on an EXISTING Pixie tool. Use when the user asks to cite, attribute, credit, or add a citation to a tool. Do NOT use to implement a paper anew (add-tool-from-paper), change behaviour (update-tool), or tag.

Runs the retention sweeper to delete OLD past RUNS and artefacts exceeding retain_runs, sparing starred and labelled. Use when the user asks to clear, clean, prune, sweep, or delete OLD runs or run history. Do NOT use to delete a tool (remove-tool), archive (archive-tool), or audit disk (audit-disk-usage).

Converts a Gradio app into a Pixie tool, mapping gr.Interface or gr.Blocks components onto tool.json inputs and outputs then validating. Use when the user mentions Gradio, gr.Interface, gr.Blocks, or .py importing gradio and asks to convert, port, or wrap it. Do NOT use for Streamlit (convert-streamlit-app) or plain .py (wrap-local-script).

Converts a Streamlit app into a Pixie tool - maps st.* widgets to tool.json inputs and st.* outputs to partials. Single-form apps only; refuses multi-page or stateful ones. Use when the user mentions Streamlit, streamlit run, or .py importing streamlit. Do NOT use for Gradio (convert-gradio-app) or plain .py (wrap-local-script).

Copies ONE saved Pixie artefact file byte-for-byte to a user-supplied filesystem path. Use when the user asks to copy, save, write, or move ONE specific output to a one-off file or folder path. Do NOT use for a named recurring destination (send-to-folder), clipboard (copy-to-clipboard), or format conversion (export-as-format).

Copies a small TEXTUAL Pixie output (text, markdown, number, boolean, json, csv, kv, log) to the system clipboard. Use when the user asks to copy, clipboard, grab, or yank a small text output. Do NOT use for binary outputs (export-as-format) or to copy a file to a path (copy-output-to).

Diagnoses and fixes ONE Pixie tool that fails validation, crashes, hangs, or returns wrong output - validator-first. Use when the user says a named tool is broken, failing, or crashing. Do NOT use if Pixie itself is broken (pixie-doctor), for style (lint-tool), or just logs (view-logs).

Converts ONE saved Pixie artefact to a chosen format (PNG, SVG, PDF, XLSX, CSV, MP3) via the server-side exporter. Use when the user asks to export, convert, save as, or download an output AS a different format. Do NOT use for unchanged copy (copy-output-to), clipboard (copy-to-clipboard), or whole run (export-run).

Packages ONE Pixie run as a RENDERED markdown report.md plus an assets/ folder of artefacts (not raw JSON). Use when the user asks for a report, write-up, summary, or human-readable record of a run. Do NOT use for a raw JSON zip (export-run), one artefact (export-as-format), or many runs (bulk-export).

Exports ONE Pixie run as a RAW zip - inputs.json, outputs.json, every artefact file - no rendering. Use when the user asks to export, download, dump, or package one run's raw data. Do NOT use for rendered markdown report (export-run-as-report), many runs (bulk-export), one artefact (export-as-format), or tool source (share-tool).

Downloads a HuggingFace Hub dataset (public or token-gated) into a Pixie tool's data folder. Use when the user asks to fetch or import an HF dataset for a named tool. Do NOT use for Kaggle (fetch-dataset-from-kaggle), URLs (fetch-dataset-from-url), local files (import-dataset-from-local), or HF MODELS (use transformers).

Downloads a Kaggle dataset or competition into a Pixie tool's data folder using the user's Kaggle credentials. Use when the user asks to fetch, download, or import a Kaggle dataset for a named tool. Do NOT use for HuggingFace (fetch-dataset-from-huggingface), URLs (fetch-dataset-from-url), local files (import-dataset-from-local), or Kaggle notebooks.

Downloads a dataset from any HTTPS URL into a Pixie tool's data folder with safe extraction and checksum verification. Use when the user gives a non-Kaggle non-HuggingFace data URL and asks to fetch it. Do NOT use for Kaggle (fetch-dataset-from-kaggle), HuggingFace (fetch-dataset-from-huggingface), local paths (import-dataset-from-local), or Git repos (add-tool-from-repo).

Searches saved Pixie output ARTEFACTS by substring against filename, label, or tags across all tools. Use when the user asks to find, search, look for, locate, or grep a saved output, artefact, or file. Do NOT use to list everything (list-outputs), one tool's runs (view-runs), or open a folder (open-artefacts-folder).

Duplicates an existing Pixie tool under a new id with its own .venv so the copy can be customised independently. Use when the user asks to copy, duplicate, fork, or branch a Pixie tool. Do NOT use for cloning a Git repo (add-tool-from-repo) or just renaming one tool (rename-tool).

Builds a Pixie tool from a detailed ML model spec - architecture, training setup, hyperparameters, expected metric. Use when the user wants to BUILD a specific model rigorously and has NO paper, repo, or code. Do NOT use given a paper (add-tool-from-paper), repo (add-tool-from-repo), or an informal idea (add-tool-from-description).

Copies, symlinks, or moves a local file or folder into a Pixie tool's data folder as a dataset. Use when the user gives a local path and asks to import it as a dataset. Do NOT use for URLs (fetch-dataset-from-url), Kaggle (fetch-dataset-from-kaggle), HuggingFace (fetch-dataset-from-huggingface), or a .py script (wrap-local-script).

Installs a Pixie tool from a .zip someone packaged via share-tool - unpacks under tools/, runs uv sync, validates. Use when the user has a .zip or says someone shared, sent, or zipped them a tool. Do NOT use for a Git URL (add-tool-from-repo), .py (wrap-local-script), or restoring archived (unarchive-tool).

Shows one Pixie tool's current schema, inputs, outputs, dependencies, secrets, and validator status - read-only. Use when the user asks what THIS tool does, or to show, describe, or inspect a single named tool. Do NOT use to list all tools (list-tools), show past runs (view-runs), or fix anything (debug-tool).

Sets a short human-memorable label on one Pixie run - searchable via find-output, also protects from auto-pruning. Use when the user asks to label, name, rename, annotate, or 'call this' a specific RUN. Do NOT use to rename a tool (rename-tool), tag a tool (tag-tool), or star a run (star-run).

Statically checks one Pixie tool against style and convention rules - metadata, labels, imports, hardcoded-secret smells, log hygiene. Use when the user asks to lint, style-check, or review best practices on one tool. Do NOT use for a broken tool (debug-tool), disk usage (audit-disk-usage), or layout cleanup (organise-tool).

Lists saved output ARTEFACTS (files, images, audio, transcripts) from past Pixie tool RUNS, optionally filtered by tool. Use when the user asks to list, show, or browse saved OUTPUTS or ARTEFACTS. Do NOT use to list installed tools (list-tools), search by name (find-output), or show one tool's runs (view-runs).

Enumerates every installed Pixie tool under tools/ as a one-line-per-tool table with id, name, and validator status. Use when the user asks to list, show all, or enumerate installed tools. Do NOT use to inspect ONE (inspect-tool), show what's running (pixie-status), or list saved outputs (list-outputs).

Upgrades a Pixie tool whose tool.json uses an older schema_version to the current schema, preserving behaviour and re-validating. Use when the user mentions old format, schema version, deprecation, or asks to migrate or upgrade a tool's format. Do NOT use to fix a broken tool (debug-tool) or change inputs (update-tool).

Opens Pixie's artefacts/ folder (or one tool's, or one run's) in the OS native file browser - Explorer, Finder, xdg-open. Use when the user asks to open, reveal, or 'show in Finder/Explorer' the artefacts or outputs folder. Do NOT use to list artefacts inline (list-outputs) or copy one out (copy-output-to).

Restructures one Pixie tool's internal Python files into the src/ layout, adding tests/, notebooks/, CHANGELOG skeletons, then re-validates. Use when the user asks to organise, tidy, refactor, restructure, or clean up a tool's files or layout. Do NOT use to change inputs (update-tool), rename (rename-tool), or fix broken (debug-tool).

Diagnoses Pixie ITSELF - server, database, ports, dashboard, .venv, Python and uv versions. Use when the user says Pixie won't start, the dashboard is broken, or tools aren't showing up. Do NOT use if one named tool is broken (debug-tool) or just checking status (pixie-status).

Shows Pixie's current runtime state - whether the server is up, which tools are warm, ports, recent activity, uptime - read-only. Use when the user asks if Pixie is running, what's running now, or what's warm. Do NOT use if Pixie is broken (pixie-doctor) or to enumerate installed tools (list-tools).

Registers a named export TARGET (destination folder plus default format) in pixie.db so future exports go there in one command. Use when the user asks to set up, configure, register, or define an export target, preset, or shortcut. Do NOT use for one-shot send (send-to-folder) or conversion (export-as-format).

Permanently deletes an ENTIRE Pixie tool - folder, .venv, data/, .env, warm subprocess. Use when the user asks to remove, delete, uninstall, or get rid of a tool forever. Do NOT use to hide reversibly (archive-tool), delete old runs (clear-old-outputs), unassign from a workspace (workspace-remove-tool), or clear a secret (set-secret).