@paradigma-inc/flywheel 0.1.11 → 0.1.13

package/skills/flywheel-reproduce/references/INTERFACES.md

@@ -0,0 +1,201 @@
+# Interfaces
+
+Canonical reference for Flywheel user-facing interfaces and public contracts.
+
+Last updated: 2026-03-21
+
+## Primary Clients
+
+- `project/flywheel-webui` - canonical web product UI
+- `project/flywheel-api` - canonical programmatic client interface (local + HTTP)
+- MCP hosts (Codex/Claude/ChatGPT) via `/mcp-server`
+
+## Canonical Entity Model
+
+All interfaces operate on the same core entities:
+
+- node
+- node edge (branch/merge graph links)
+- artifact
+- execution
+- compute lease
+- budget grant
+
+Node snapshots are the canonical durable contract for resume, review, and
+cross-client interoperability.
+
+## Core HTTP Surface
+
+### Node lifecycle and graph
+
+- `GET /mcp/nodes`
+- `GET /mcp/nodes/{node_id}`
+- `GET /mcp/nodes/{node_id}/tree`
+- `POST /mcp/nodes/stage/create`
+- `PATCH /mcp/nodes/{node_id}/stage/update`
+- `POST /mcp/nodes/{node_id}/commit`
+- `POST /mcp/nodes/{node_id}/branch`
+- `POST /mcp/nodes/merge`
+- `DELETE /mcp/nodes/{node_id}`
+- `POST /mcp/nodes/bulk-delete`
+
+### Artifact lifecycle
+
+- `POST /mcp/nodes/{node_id}/artifacts/uploads/prepare`
+- `POST /mcp/nodes/{node_id}/artifacts/uploads/finalize`
+- `GET /mcp/nodes/{node_id}/artifacts`
+- `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}`
+- `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}/preview`
+- `DELETE /mcp/nodes/{node_id}/artifacts/{artifact_id}`
+- `PUT /mcp/artifacts/uploads/{upload_id}`
+
+### Execution lifecycle
+
+- `POST /mcp/nodes/{node_id}/executions`
+- `GET /mcp/nodes/{node_id}/executions`
+- `POST /mcp/nodes/{node_id}/executions/{execution_id}/terminate`
+
+### Compute catalog
+
+- `GET /compute/providers`
+- `GET /compute/offers`
+- `GET /compute/offers/{provider}`
+
+### Managed compute and budgets
+
+- `GET /mcp/nodes/{node_id}/compute/options`
+- `POST /mcp/nodes/{node_id}/compute/acquire`
+- `GET /mcp/compute/status`
+- `GET /mcp/compute/connection`
+- `POST /mcp/compute/release`
+- `POST /mcp/compute/release-all`
+- `GET /mcp/nodes/{node_id}/budget/grants`
+- `GET /mcp/nodes/{node_id}/budget/campaign-grants`
+- `POST /mcp/nodes/{node_id}/budget/campaign-grants`
+- `PATCH /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
+- `DELETE /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
+
+### Sharing, tags, and audit
+
+- `GET /mcp/nodes/{node_id}/sharing`
+- `PUT /mcp/nodes/{node_id}/sharing`
+- `POST /mcp/nodes/sharing/bulk`
+- `GET /mcp/nodes/{node_id}/audit`
+- `POST /mcp/nodes/{root_node_id}/tags`
+- `PATCH /mcp/nodes/{root_node_id}/tags/{tag_id}`
+- `DELETE /mcp/nodes/{root_node_id}/tags/{tag_id}`
+- `PUT /mcp/nodes/{node_id}/tags`
+
+### Export and summaries
+
+- `POST /mcp/export`
+- `POST /mcp/import`
+- `POST /mcp/export-summary`
+- `POST /mcp/export-summary-stream`
+- `POST /mcp/export-summary-pdf`
+- `POST /mcp/export-summary-render-pdf`
+
+### Auth and integrations
+
+- `GET /auth/status`
+- `GET /auth/accounts`
+- `POST /auth/accounts/merge/source-proof`
+- `POST /auth/accounts/merge/preview`
+- `POST /auth/accounts/merge`
+- `POST /auth/accounts/detach`
+- `GET /auth/integrations/status`
+- `PUT /auth/integrations/wandb`
+- `PUT /auth/integrations/huggingface`
+- `DELETE /auth/integrations/wandb`
+- `DELETE /auth/integrations/huggingface`
+
+### Analytics
+
+- `POST /analytics/events`
+- `GET /admin/analytics/kpis`
+- `GET /admin/analytics/overview`
+
+## MCP Tool Surface
+
+### Discovery and sharing tools
+
+- `flywheel_auth_status`
+- `flywheel_get_credits_balance`
+- `flywheel_list_nodes`
+- `flywheel_get_node`
+- `flywheel_get_node_tree`
+- `flywheel_get_node_sharing`
+- `flywheel_set_node_sharing`
+- `flywheel_bulk_set_node_sharing`
+- `flywheel_create_node_tag`
+- `flywheel_update_node_tag`
+- `flywheel_delete_node_tag`
+- `flywheel_set_node_tag_assignments`
+
+### Node and graph tools
+
+- `flywheel_stage_node_create`
+- `flywheel_stage_node_update`
+- `flywheel_commit_node`
+- `flywheel_branch_node`
+- `flywheel_merge_nodes`
+- `flywheel_delete_node`
+- `flywheel_bulk_delete_nodes`
+
+### Artifact tools
+
+- `flywheel_prepare_artifact_uploads`
+- `flywheel_finalize_artifact_uploads`
+- `flywheel_list_artifacts`
+- `flywheel_get_artifact`
+- `flywheel_get_artifact_preview`
+- `flywheel_delete_artifact`
+
+### Execution tools
+
+- `flywheel_launch_execution`
+- `flywheel_list_executions`
+- `flywheel_terminate_execution`
+
+### Compute lease and budget tools
+
+- `flywheel_compute_list_options`
+- `flywheel_request_compute_grant_approval`
+- `flywheel_list_compute_grants`
+- `flywheel_compute_acquire`
+- `flywheel_compute_status`
+- `flywheel_compute_connection`
+- `flywheel_compute_release`
+- `flywheel_compute_release_all`
+
+### Campaign budget tools
+
+- `flywheel_list_campaign_budgets`
+- `flywheel_create_campaign_budget`
+- `flywheel_update_campaign_budget`
+- `flywheel_revoke_campaign_budget`
+
+### Contract, audit, and export tools
+
+- `flywheel_get_contract`
+- `flywheel_list_audit`
+- `flywheel_summarize_node_tree`
+- `flywheel_export_subgraph`
+- `flywheel_import_subgraph`
+- `flywheel_export_summary`
+- `flywheel_export_summary_stream`
+- `flywheel_export_summary_pdf`
+- `flywheel_export_summary_render_pdf`
+
+## Legacy Archival Export
+
+Experimental settings keep legacy history export available as an archival
+migration aid. This path is read-only and outside canonical node workflows.
+
+## Related Docs
+
+- `docs/flywheel/CONCEPT.md`
+- `docs/flywheel/FLYWHEEL_MCP.md`
+- `docs/flywheel/PROVISIONING.md`
+- `docs/flywheel/ARTIFACTS.md`
+- `docs/flywheel/GIT_INTEGRATION.md`

package/skills/flywheel-reproduce/references/experiment-design-protocol.md

@@ -0,0 +1,204 @@
+# Experiment Design Protocol
+
+Use this when the user needs help turning research intent into a well-formed experiment or exploration before spending compute.
+
+## Goal
+
+Help the user clarify what they are trying to learn, shape the work around that question, and avoid wasting compute before the design is solid.
+
+## Operating rules
+
+- Treat design and execution as separate phases.
+- Optimize for clarity of experimental purpose, not speed to a first run.
+- Adapt depth to the user's experience and the clarity already present in the conversation.
+- Apply epistemic discipline: separate what is known from what is assumed, and name uncertainty instead of smoothing it over.
+- Support both hypothesis-driven and exploratory work.
+- Support simple runs and complex shapes such as multi-stage pipelines, sweep-then-deep-dive, multi-arm comparisons, and custom structures.
+- Keep all 10 brief fields, but allow exploratory fields to be marked `exploratory` or `TBD` rather than fabricated.
+- Use quick Socratic questioning to surface assumptions, confidence, and what would change the user's mind. Keep it to 1-2 short questions per turn.
+- Propose defaults for structural choices such as experiment shape, stop condition, or artifact plan. Use questions rather than defaults for epistemic choices such as beliefs, assumptions, and what evidence would matter.
+- When a reasoning or design gap is visible, raise it as a question rather than an assertion.
+- If the core gate is satisfied and the user wants to proceed, stop asking more design questions.
+- Use Flywheel `insight` nodes to preserve design context when it will help across turns or sessions.
+
+## Phase 1: Clarify what the user is trying to learn
+
+Start with:
+
+1. What are you trying to learn or decide?
+2. Is this mainly hypothesis-driven or exploratory right now?
+
+Keep this phase quick. Ask 1-2 short questions per turn, and use light Socratic questioning as an epistemic check after the user states the learning goal: briefly surface what seems known versus assumed before moving on.
+
+If the work is hypothesis-driven, ask:
+
+- What is the hypothesis?
+- Compared to what baseline or alternative?
+- What result would matter?
+
+If the work is exploratory, ask:
+
+- What is the big question?
+- What would you need to learn first before tackling it?
+- What is the cheapest or cleanest way to learn that first piece?
+- What signal or pattern are you looking for?
+
+If the user is still fuzzy after this phase, stay in planning mode. If needed, create or update an `insight` node rather than an `empirical` node.
+
+## Phase 2: Shape the work
+
+Choose or define the experiment shape through quick Socratic questioning:
+
+- single focused run
+- multi-stage pipeline
+- sweep then deep-dive
+- multi-arm comparison
+- custom shape
+
+If the user is unsure about structure, propose a default shape, stop condition, or artifact plan instead of extending the question loop.
+
+Then fill the experiment brief:
+
+- `question`: the decision or learning goal
+- `hypothesis`: the claim being tested
+- `comparator`: the baseline or alternative
+- `unit_of_work`: what one run, branch, or stage actually changes
+- `primary_metric`: the main number or observable to inspect
+- `artifact_plan`: which artifact will help interpret the result
+- `budget_cap`: max spend or runtime for the current stage
+- `stop_condition`: when to stop rather than letting the run expand
+- `interpretation`: what would count as signal, no signal, or ambiguity
+- `next_branch_if_inconclusive`: the follow-up branch if the result is unclear
+
+For exploratory work, `hypothesis` or `comparator` may be marked `exploratory` or `TBD`, but the learning goal still needs to be explicit.
+
+## Phase 3: Run the adaptive design gate
+
+Frame the gate as preventing waste, not enforcing bureaucracy.
+
+Always check:
+
+- the question or goal is explicit
+- at least one metric or observable is defined
+- a budget cap or stop condition exists
+
+For hypothesis-driven work, also check:
+
+- there is a falsifiable hypothesis
+- there is a comparator or baseline
+
+For exploratory work, instead check:
+
+- the user can say what they are looking for
+- the first learning step is scoped well enough to run
+
+Additional checks when relevant:
+
+- an artifact plan or `no_artifacts_reason` exists
+- the run shape matches the question and is not changing too many important things without purpose
+- an interpretation rule or next branch is defined
+
+If the core gate passes and the user wants to proceed, let them run even if some non-core details are still `TBD`.
+
+When blocked, ask only the next necessary question instead of reopening the whole brief.
+
+## Phase 4: Confirm the plan
+
+Before any compute request or training launch, restate:
+
+- what we are trying to learn
+- the experiment shape
+- the metric or observable
+- the artifact plan
+- the budget or stop condition
+- what result would change the next step
+
+If the run is expensive or high-risk, ask for explicit confirmation.
+
+## Phase 5: Drive Flywheel
+
+Use Flywheel in layers when possible.
+
+Before execution, load `references/flywheel-mcp-tool-map.md` and verify the
+exact tool surface exposed by the current MCP host before critical flows.
+
+### Design layer
+
+Use an `insight` node to capture rationale, open questions, experiment shape, and any decomposition needed for exploratory or multi-stage work.
+
+Typical flow:
+
+1. `mcp__flywheel__flywheel_stage_node_create`
+2. `mcp__flywheel__flywheel_stage_node_update`
+3. `mcp__flywheel__flywheel_commit_node`
+
+### Execution layer
+
+Only after the design gate passes, create or branch the `empirical` node for the runnable part of the work.
+
+Typical flow:
+
+1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_stage_node_create`
+2. `mcp__flywheel__flywheel_stage_node_update` with the explicit run summary and the local question or hypothesis for that branch
+3. `mcp__flywheel__flywheel_request_compute_grant_approval` only after the user accepts the design
+4. `mcp__flywheel__flywheel_list_compute_grants` or `mcp__flywheel__flywheel_list_approval_sessions` when you need to resolve the approved `compute_grant_id`
+5. `mcp__flywheel__flywheel_compute_acquire` and related compute tools only when execution is actually needed
+6. `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, then `mcp__flywheel__flywheel_finalize_artifact_uploads`
+7. Do a brief epistemic check before commit: verify what the evidence actually shows, whether it matches the interpretation rule from the brief, and whether any gap between the data and the hoped-for story needs to be named explicitly in the node summary.
+8. `mcp__flywheel__flywheel_commit_node`
+
+Important notes:
+
+- Exploratory work can stay in `insight` nodes until a specific empirical probe is ready.
+- Because `empirical` commits require a non-empty `hypothesis`, turn each runnable exploratory probe into a concrete local question or hypothesis for that branch.
+- For multi-stage or multi-arm work, use branches to represent stages or arms and keep summaries clear about how each branch feeds the next.
+- Completed empirical work needs artifacts or a `no_artifacts_reason`.
+
+## Adaptive question flow
+
+Ask in short batches of 1-2 questions per turn. Keep the flow light, Socratic, and epistemic rather than exhaustive.
+
+1. What are you trying to learn or decide?
+2. Is this hypothesis-driven or exploratory?
+3. Briefly separate what the user seems to know from what they seem to be assuming before locking the design.
+4. If hypothesis-driven: what is the hypothesis and compared to what?
+5. If exploratory: what is the first thing you need to learn and what is the cheapest way to learn it?
+6. What experiment shape fits this work?
+7. What metric or observable and artifact will you inspect?
+8. What budget or stop condition keeps this from wasting compute?
+9. What interpretation rule will distinguish evidence from expectation?
+10. If the result is ambiguous, what is the next branch?
+
+## Output template
+
+Use this shape when turning a vague request into an executable plan:
+
+```md
+Experiment brief
+
+- Question:
+- Hypothesis:
+- Comparator:
+- Unit of work:
+- Primary metric or observable:
+- Artifact plan:
+- Budget/time cap:
+- Stop condition:
+- Interpretation rule:
+- Next branch if inconclusive:
+
+Experiment type: hypothesis-driven | exploratory
+Design gate: ready | blocked
+Remaining gap:
+Recommended next action:
+```
+
+## Generalization rule
+
+Reuse the same protocol across domains by changing the unit of work and artifact type:
+
+- model training -> metrics tables, loss curves, checkpoints
+- benchmark comparisons -> score tables, latency plots, error slices
+- prompt evaluations -> rubric tables, failure examples, sampled outputs
+- product experiments -> funnels, event tables, user-segment slices
+- scientific workflows -> figures, logs, result tables, notebooks

package/skills/flywheel-reproduce/references/flywheel-mcp-tool-map.md

@@ -0,0 +1,160 @@
+# Flywheel MCP Tool Map
+
+This reference describes the Flywheel MCP tool families and the common runtime
+contract expected by the public Flywheel skill.
+
+Use it as a routing guide, not as a session snapshot. Always verify the exact
+tool surface exposed by your current MCP host before executing critical flows.
+
+## Core Contract Expectations
+
+- Node lifecycle and graph-mutation flows use optimistic locking
+  (`expected_revision`).
+- Node commits require `kind`, `outcome`, and `summary`.
+- `kind` is typically `insight` or `empirical`.
+- `insight` commits require non-empty `insights`.
+- `empirical` commits require a non-empty `hypothesis`; completed empirical
+  commits also require artifacts or a `no_artifacts_reason`.
+- Artifact publish is a two-step flow:
+  prepare upload, upload raw bytes to returned signed URLs, then finalize
+  the upload batch.
+
+## Tool Families
+
+### Session, Auth, and Contract
+
+- `mcp__flywheel__flywheel_auth_status`
+- `mcp__flywheel__flywheel_get_contract`
+- `mcp__flywheel__flywheel_get_contract_section`
+- `mcp__flywheel__flywheel_get_credits_balance`
+
+### Node Discovery and Read
+
+- `mcp__flywheel__flywheel_list_nodes`
+- `mcp__flywheel__flywheel_get_node`
+- `mcp__flywheel__flywheel_get_node_tree`
+- `mcp__flywheel__flywheel_get_node_ancestry`
+- `mcp__flywheel__flywheel_summarize_node_tree`
+- `mcp__flywheel__flywheel_get_campaign_snapshot`
+- `mcp__flywheel__flywheel_list_audit`
+
+### Node Mutation, Branching, and Commit
+
+- `mcp__flywheel__flywheel_stage_node_create`
+- `mcp__flywheel__flywheel_stage_node_update`
+- `mcp__flywheel__flywheel_commit_node`
+- `mcp__flywheel__flywheel_branch_node`
+- `mcp__flywheel__flywheel_merge_nodes`
+- `mcp__flywheel__flywheel_add_parent`
+- `mcp__flywheel__flywheel_remove_parent`
+- `mcp__flywheel__flywheel_delete_node`
+- `mcp__flywheel__flywheel_bulk_delete_nodes`
+
+### Access Policy and Collaboration
+
+- `mcp__flywheel__flywheel_get_node_sharing`
+- `mcp__flywheel__flywheel_set_sharing_for_node`
+- `mcp__flywheel__flywheel_set_sharing_for_nodes`
+
+### Tags and Graph Annotation
+
+- `mcp__flywheel__flywheel_create_node_tag`
+- `mcp__flywheel__flywheel_update_node_tag`
+- `mcp__flywheel__flywheel_delete_node_tag`
+- `mcp__flywheel__flywheel_set_node_tag_assignments`
+
+### Artifacts
+
+- `mcp__flywheel__flywheel_list_artifacts`
+- `mcp__flywheel__flywheel_get_artifact`
+- `mcp__flywheel__flywheel_get_artifact_preview`
+- `mcp__flywheel__flywheel_prepare_artifact_uploads`
+- `mcp__flywheel__flywheel_finalize_artifact_uploads`
+- `mcp__flywheel__flywheel_set_artifact_note`
+- `mcp__flywheel__flywheel_delete_artifact`
+
+Common artifact types include:
+`text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`,
+`checkpoint`, and `diff_carousel`.
+
+### Export and Import
+
+- `mcp__flywheel__flywheel_export_subgraph`
+- `mcp__flywheel__flywheel_import_subgraph`
+- `mcp__flywheel__flywheel_export_summary`
+- `mcp__flywheel__flywheel_export_summary_stream`
+- `mcp__flywheel__flywheel_export_summary_pdf`
+- `mcp__flywheel__flywheel_export_summary_render_pdf`
+
+### Executions
+
+- `mcp__flywheel__flywheel_launch_execution`
+- `mcp__flywheel__flywheel_list_executions`
+- `mcp__flywheel__flywheel_terminate_execution`
+
+### Managed Compute
+
+- `mcp__flywheel__flywheel_approval_session_heartbeat`
+- `mcp__flywheel__flywheel_list_approval_sessions`
+- `mcp__flywheel__flywheel_expire_approval_session`
+- `mcp__flywheel__flywheel_request_compute_grant_approval`
+- `mcp__flywheel__flywheel_list_compute_grants`
+- `mcp__flywheel__flywheel_compute_list_options`
+- `mcp__flywheel__flywheel_compute_acquire`
+- `mcp__flywheel__flywheel_compute_status`
+- `mcp__flywheel__flywheel_compute_connection`
+- `mcp__flywheel__flywheel_compute_release`
+- `mcp__flywheel__flywheel_compute_release_all`
+
+### Campaign Budgets (Organizer Flows)
+
+- `mcp__flywheel__flywheel_list_campaign_budgets`
+- `mcp__flywheel__flywheel_create_campaign_budget`
+- `mcp__flywheel__flywheel_update_campaign_budget`
+- `mcp__flywheel__flywheel_revoke_campaign_budget`
+
+### Migration Helpers
+
+Some installations may expose migration-only helper tools with hashed names.
+Treat these as specialized one-off tools, not part of day-to-day research
+workflows.
+
+## Practical Tool Sequences
+
+### Insight Node Flow
+
+1. `mcp__flywheel__flywheel_stage_node_create`
+2. `mcp__flywheel__flywheel_stage_node_update`
+3. `mcp__flywheel__flywheel_commit_node`
+
+### Empirical Node With Artifacts
+
+1. `mcp__flywheel__flywheel_stage_node_create`
+2. `mcp__flywheel__flywheel_stage_node_update`
+3. Run experiment or compute steps
+4. `mcp__flywheel__flywheel_prepare_artifact_uploads`
+5. Upload artifact bytes to signed URLs
+6. `mcp__flywheel__flywheel_finalize_artifact_uploads`
+7. `mcp__flywheel__flywheel_commit_node`
+
+### Managed Compute Flow
+
+1. `mcp__flywheel__flywheel_approval_session_heartbeat`
+2. `mcp__flywheel__flywheel_request_compute_grant_approval`
+3. `mcp__flywheel__flywheel_list_compute_grants` (if needed)
+4. `mcp__flywheel__flywheel_compute_acquire`
+5. `mcp__flywheel__flywheel_compute_status` until ready
+6. `mcp__flywheel__flywheel_compute_connection`
+7. `mcp__flywheel__flywheel_compute_release` (or `..._release_all`)
+
+### Share a Graph With Collaborators
+
+1. `mcp__flywheel__flywheel_get_node_sharing`
+2. `mcp__flywheel__flywheel_set_sharing_for_node` (or `..._for_nodes`)
+3. `mcp__flywheel__flywheel_export_summary` or `..._export_subgraph` for handoff
+
+## Safety Notes
+
+- Prefer `get_contract` before implementing strict assumptions in automation.
+- Avoid call-order assumptions not mandated by contract.
+- Keep checks bounded: list/read first, then mutate only the intended nodes.