Summary
Falcon is currently CLI-first: falcon launch is the only supported entry point, and the runtime, the blessed TUI, and signal handling are fused inside launch_mode. This makes the framework hard to teach and hard to explore. This issue tracks building a Python-first front door so falcon can be driven from notebooks (Colab/Jupyter), for both pedagogical use and expert iteration.
The full design lives in plans/COLAB_API_PLAN.md on the plan/colab-notebook-api branch.
Key design decisions (settled)
- Flat config surface. Config is set through flat, prefixed, typed keyword arguments (
loop_num_epochs=600); the YAML file stays nested; a deterministic prefix transform bridges the two.
- Config-shape taxonomy. Every config slot is a product (flat kwargs), sum (typed object), composite (construction expression), or collection (list). The surface style is derived from the slot's type.
_target_ unification is Step 0. Absorb net_type, one resolver, _target_ always resolves to a class, fixed reserved structural keys.launch() blocks by default; non-blocking launch(wait=False) is a supported escape hatch.- Ray lifecycle split.
falcon.init() sets up/connects to Ray; launch() reuses it and never tears it down.
- v1 in-cell output is one interleaved, color-tagged log stream (driver + all node logs). Structured ipywidgets displays are optional phase 2.
- Notebook-defined models ride to Ray actors via cloudpickle; the one off-trail piece is an escape hatch for classes with no import path.
Phasing
- Unify
_target_ resolution
- Extract
_run_pipeline from launch_mode (CLI behavior unchanged)
- Cloudpickle spike (gates the rest)
- Flat config surface (synthesized signatures, the YAML bridge)
falcon.init / launch / shutdown / session + v1 log streamGraph.add_node builder + falcon.Simulator + live-object support + JAX actor-env passthrough- Rich reprs + Mermaid graph +
plot_metrics / corner
- Phase-2 monitoring (optional)
- Notebook CI + example notebooks
Open questions
- Outcome of the cloudpickle spike (gates everything notebook-class-related)
- Whether to adopt a short-name registry (
catalogue) for _target_
- Flattened-signature parameter counts per estimator
See the plan doc for full detail and rationale.
Summary
Falcon is currently CLI-first:
falcon launchis the only supported entry point, and the runtime, the blessed TUI, and signal handling are fused insidelaunch_mode. This makes the framework hard to teach and hard to explore. This issue tracks building a Python-first front door so falcon can be driven from notebooks (Colab/Jupyter), for both pedagogical use and expert iteration.The full design lives in
plans/COLAB_API_PLAN.mdon theplan/colab-notebook-apibranch.Key design decisions (settled)
loop_num_epochs=600); the YAML file stays nested; a deterministic prefix transform bridges the two._target_unification is Step 0. Absorbnet_type, one resolver,_target_always resolves to a class, fixed reserved structural keys.launch()blocks by default; non-blockinglaunch(wait=False)is a supported escape hatch.falcon.init()sets up/connects to Ray;launch()reuses it and never tears it down.Phasing
_target_resolution_run_pipelinefromlaunch_mode(CLI behavior unchanged)falcon.init/launch/shutdown/session+ v1 log streamGraph.add_nodebuilder +falcon.Simulator+ live-object support + JAX actor-env passthroughplot_metrics/cornerOpen questions
catalogue) for_target_See the plan doc for full detail and rationale.