dizzy.cli

dizzy.cli

Dizzy — feature file generator CLI.

def_cmd(feat_file, output_dir, default_runtime='python-uv')

Generate def/ stub files from a .feat.yaml feature definition.

Source code in dizzy/src/dizzy/cli.py

@generate_app.command("definitions")
def def_cmd(
    feat_file: Annotated[Path, typer.Argument(help="Path to the .feat.yaml file")],
    output_dir: Annotated[Path, typer.Argument(help="Output directory for generated files")],
    default_runtime: Annotated[
        str,
        typer.Option(help="Default runtime assigned to all elements in libconfig.yaml"),
    ] = "python-uv",
) -> None:
    """Generate def/ stub files from a .feat.yaml feature definition."""
    feat = load_feat(feat_file)

    errors = validate_feat(feat)
    if errors:
        for err in errors:
            logger.error("%s", err)
        raise typer.Exit(code=1)

    if feat.commands:
        write_scaffold_commands(feat.commands, output_dir)

    if feat.events:
        write_scaffold_events(feat.events, output_dir)

    if feat.environment:
        write_scaffold_environment(feat.environment, output_dir)

    if feat.telemetry:
        write_scaffold_telemetry(feat.telemetry, output_dir)

    for query in feat.queries or []:
        write_scaffold_query(query, output_dir)

    for model in feat.models or []:
        write_scaffold_model(model, output_dir)

    write_libconfig_stub(feat, output_dir, default_runtime=default_runtime)

    logger.info("Generated def/ stubs and libconfig.yaml. Next steps:")
    logger.info("  1. Fill in class definitions in def/models/*.yaml")
    logger.info("  2. Add input/output shapes in def/queries/*.yaml")
    logger.info("  3. Add attributes to def/commands.yaml and def/events.yaml")
    logger.info("  4. Review runtimes in libconfig.yaml")
    logger.info("  5. Run: dizzy generate static <feat_file> <output_dir>")
    logger.info("  6. Run: dizzy generate libraries <feat_file> <output_dir>")

gen(feat_file=typer.Argument(..., help='Path to the .feat.yaml file'), output_dir=typer.Argument(..., help='Output directory for generated files'))

Generate the gen_def/ and gen_int/ type packages under lib/python-uv/ from def/.

Source code in dizzy/src/dizzy/cli.py

@generate_app.command("static")
def gen(
    feat_file: Path = typer.Argument(..., help="Path to the .feat.yaml file"),
    output_dir: Path = typer.Argument(..., help="Output directory for generated files"),
) -> None:
    """Generate the gen_def/ and gen_int/ type packages under lib/python-uv/ from def/."""
    feat = load_feat(feat_file)

    errors = validate_feat(feat)
    if errors:
        for err in errors:
            logger.error("%s", err)
        raise typer.Exit(code=1)

    # Guard: check that all required def/ stubs exist before proceeding
    missing: list[str] = []
    if feat.commands and not (output_dir / "def" / "commands.yaml").exists():
        missing.append("def/commands.yaml")
    if feat.events and not (output_dir / "def" / "events.yaml").exists():
        missing.append("def/events.yaml")
    if feat.environment and not (output_dir / "def" / "environment.yaml").exists():
        missing.append("def/environment.yaml")
    if feat.telemetry and not (output_dir / "def" / "telemetry.yaml").exists():
        missing.append("def/telemetry.yaml")
    for query in feat.queries or []:
        stub = output_dir / "def" / "queries" / f"{query.name}.yaml"
        if not stub.exists():
            missing.append(f"def/queries/{query.name}.yaml")
    for model in feat.models or []:
        stub = output_dir / "def" / "models" / f"{model.name}.yaml"
        if not stub.exists():
            missing.append(f"def/models/{model.name}.yaml")

    if missing:
        logger.error(
            "def/ stubs not found. Run `dizzy generate definitions <feat_file> <output_dir>` first."
        )
        for path in missing:
            logger.error("  missing: %s", path)
        raise typer.Exit(code=1)

    # Step 1 — run LinkML toolchain on def/ stubs → lib/python-uv/gen_def/
    gen_def = gen_def_root(output_dir)
    if feat.commands:
        run_linkml_pydantic(
            output_dir / "def" / "commands.yaml",
            gen_def / "pydantic" / "commands.py",
        )

    if feat.events:
        run_linkml_pydantic(
            output_dir / "def" / "events.yaml",
            gen_def / "pydantic" / "events.py",
        )

    if feat.environment:
        run_linkml_pydantic(
            output_dir / "def" / "environment.yaml",
            gen_def / "pydantic" / "environment.py",
        )

    if feat.telemetry:
        run_linkml_pydantic(
            output_dir / "def" / "telemetry.yaml",
            gen_def / "pydantic" / "telemetry.py",
        )

    for query in feat.queries or []:
        run_linkml_pydantic(
            output_dir / "def" / "queries" / f"{query.name}.yaml",
            gen_def / "pydantic" / "query" / f"{query.name}.py",
        )

    for model in feat.models or []:
        run_linkml_pydantic(
            output_dir / "def" / "models" / f"{model.name}.yaml",
            gen_def / "pydantic" / "models" / f"{model.name}.py",
        )
        if "sqla" in (model.adapters or []):
            run_linkml_sqla(
                output_dir / "def" / "models" / f"{model.name}.yaml",
                gen_def / "sqla" / "models" / f"{model.name}.py",
            )

    # Step 2 — generate adapter classes
    unique_adapters: set[str] = set()
    for model in feat.models or []:
        unique_adapters.update(model.adapters or [])
    for adapter_name in unique_adapters:
        write_adapter(adapter_name, output_dir)

    # Step 3 — generate gen_int/ Protocol files from feat structure
    for query in feat.queries or []:
        write_gen_query_protocol(query, output_dir)

    for proc in feat.procedures or []:
        write_procedure_context(proc, output_dir)
        write_procedure_protocol(proc, output_dir)

    for policy in feat.policies or []:
        write_policy_context(policy, output_dir)
        write_policy_protocol(policy, output_dir)

    for proj in feat.projections or []:
        write_projection(proj, output_dir)

    # Step 4 — write __init__.py in every generated directory
    write_init_files(output_dir)

    # Step 5 — write pyproject.toml for the gen_def / gen_int type packages
    write_type_packages(output_dir)

    # Step 6 — runtime-neutral JSON Schema contracts, if libconfig asks for them.
    # libconfig is optional here: `generate static` has never required it, and a
    # config without a `json_schema` section emits nothing.
    libconfig_path = output_dir / "libconfig.yaml"
    config = load_libconfig(libconfig_path) if libconfig_path.exists() else None
    try:
        schemas = write_json_schemas(feat, output_dir, config)
    except ValueError as err:
        logger.error("%s", err)
        raise typer.Exit(code=1) from err
    if schemas:
        logger.info("Generated %d JSON Schema contract(s).", len(schemas))

    logger.info("Generated lib/python-uv/gen_def and lib/python-uv/gen_int type packages.")
    logger.info(
        "  Run: dizzy generate libraries <feat_file> <output_dir> to generate element packages."
    )

lib(feat_file=typer.Argument(..., help='Path to the .feat.yaml file'), output_dir=typer.Argument(..., help='Output directory (must contain libconfig.yaml)'))

Generate lib/ runtime packages from libconfig.yaml.

Source code in dizzy/src/dizzy/cli.py

@generate_app.command("libraries")
def lib(
    feat_file: Path = typer.Argument(..., help="Path to the .feat.yaml file"),
    output_dir: Path = typer.Argument(..., help="Output directory (must contain libconfig.yaml)"),
) -> None:
    """Generate lib/ runtime packages from libconfig.yaml."""
    feat = load_feat(feat_file)

    errors = validate_feat(feat)
    if errors:
        for err in errors:
            logger.error("%s", err)
        raise typer.Exit(code=1)

    libconfig_path = output_dir / "libconfig.yaml"
    if not libconfig_path.exists():
        logger.error("libconfig.yaml not found. Run `dizzy generate definitions` first.")
        raise typer.Exit(code=1)

    config = load_libconfig(libconfig_path)
    config_errors = validate_libconfig(config, feat)
    if config_errors:
        for err in config_errors:
            logger.error("%s", err)
        raise typer.Exit(code=1)

    # Determine which runtimes have at least one element assigned
    active_runtimes: set[str] = set()
    for section in [config.procedures, config.policies, config.queries, config.projections]:
        for binding in section or []:
            for rt in binding.runtimes or []:
                active_runtimes.add(str(rt))

    # Run LinkML type generation for each active non-Python runtime
    def_dir = output_dir / "def"

    def _run_rust_gen(schema: Path, category: str, name: str) -> None:
        if schema.exists():
            run_linkml_rust(
                schema,
                output_dir / "lib" / "rust-cargo" / "gen_def" / category / f"{name}.rs",
            )

    def _run_ts_gen(schema: Path, category: str, name: str) -> None:
        if schema.exists():
            run_linkml_typescript(
                schema,
                output_dir / "lib" / "typescript-npm" / "gen_def" / category / f"{name}.ts",
            )

    if "rust-cargo" in active_runtimes:
        _run_rust_gen(def_dir / "commands.yaml", ".", "commands")
        _run_rust_gen(def_dir / "events.yaml", ".", "events")
        for model in feat.models or []:
            _run_rust_gen(def_dir / "models" / f"{model.name}.yaml", "models", model.name)
        for query in feat.queries or []:
            _run_rust_gen(def_dir / "queries" / f"{query.name}.yaml", "queries", query.name)

    if "typescript-npm" in active_runtimes:
        _run_ts_gen(def_dir / "commands.yaml", ".", "commands")
        _run_ts_gen(def_dir / "events.yaml", ".", "events")
        for model in feat.models or []:
            _run_ts_gen(def_dir / "models" / f"{model.name}.yaml", "models", model.name)
        for query in feat.queries or []:
            _run_ts_gen(def_dir / "queries" / f"{query.name}.yaml", "queries", query.name)

    # Build element dispatch tables per runtime
    runtime_members: dict[str, list[tuple[str, str]]] = {
        "python-uv": [],
        "rust-cargo": [],
        "typescript-npm": [],
    }

    _writers: dict[str, dict[str, Callable[..., Any]]] = {
        "python-uv": {
            "procedure": write_procedure_python_uv,
            "policy": write_policy_python_uv,
            "query": write_query_python_uv,
            "projection": write_projection_python_uv,
        },
        "rust-cargo": {
            "procedure": write_procedure_rust_cargo,
            "policy": write_policy_rust_cargo,
            "query": write_query_rust_cargo,
            "projection": write_projection_rust_cargo,
        },
        "typescript-npm": {
            "procedure": write_procedure_typescript_npm,
            "policy": write_policy_typescript_npm,
            "query": write_query_typescript_npm,
            "projection": write_projection_typescript_npm,
        },
    }

    for kind, bindings, feat_items in [
        ("procedure", config.procedures or [], feat.procedures or []),
        ("policy", config.policies or [], feat.policies or []),
        ("query", config.queries or [], feat.queries or []),
        ("projection", config.projections or [], feat.projections or []),
    ]:
        feat_by_name = {item.name: item for item in feat_items}
        for binding in bindings:
            element_def = feat_by_name[binding.name]
            for rt in binding.runtimes or []:
                runtime = str(rt)
                runtime_members[runtime].append((kind, binding.name))
                _writers[runtime][kind](element_def, output_dir)

    # Write workspace manifests for each active runtime
    for runtime, members in runtime_members.items():
        if not members:
            continue
        if runtime == "python-uv":
            write_workspace_python_uv(members, output_dir)
        elif runtime == "rust-cargo":
            write_workspace_rust_cargo(members, output_dir)
        elif runtime == "typescript-npm":
            write_workspace_typescript_npm(members, output_dir)

    logger.info("Generated lib/ packages. Implement the stubs in lib/<runtime>/<kind>/<name>/src/")

wiring(feat_file=typer.Argument(..., help='Path to the .feat.yaml file'), output_dir=typer.Argument(..., help='Output directory (must contain libconfig.yaml)'), dizzy_source=typer.Option(None, '--dizzy-source', help='Where the generated workspace gets DIZZY: a checkout path (relative to lib/<runtime>/) or a git URL. DIZZY is not published to a package index, so this defaults to the canonical repository.'))

Generate lib//wiring/ — the binding from elements to the runtime.

Source code in dizzy/src/dizzy/cli.py

@generate_app.command("wiring")
def wiring(
    feat_file: Path = typer.Argument(..., help="Path to the .feat.yaml file"),
    output_dir: Path = typer.Argument(..., help="Output directory (must contain libconfig.yaml)"),
    dizzy_source: str | None = typer.Option(
        None,
        "--dizzy-source",
        help=(
            "Where the generated workspace gets DIZZY: a checkout path (relative to "
            "lib/<runtime>/) or a git URL. DIZZY is not published to a package index, "
            "so this defaults to the canonical repository."
        ),
    ),
) -> None:
    """Generate lib/<runtime>/wiring/ — the binding from elements to the runtime."""
    feat = load_feat(feat_file)

    errors = validate_feat(feat)
    if errors:
        for err in errors:
            logger.error("%s", err)
        raise typer.Exit(code=1)

    libconfig_path = output_dir / "libconfig.yaml"
    if not libconfig_path.exists():
        logger.error("libconfig.yaml not found. Run `dizzy generate definitions` first.")
        raise typer.Exit(code=1)

    config = load_libconfig(libconfig_path)
    config_errors = validate_libconfig(config, feat)
    if config_errors:
        for err in config_errors:
            logger.error("%s", err)
        raise typer.Exit(code=1)

    # The wiring imports every element package, so it can only be generated for a
    # runtime that has them. Today that is python-uv; rust/ts stop at types + stubs.
    members: list[tuple[str, str]] = []
    for kind, bindings in [
        ("procedure", config.procedures or []),
        ("policy", config.policies or []),
        ("query", config.queries or []),
        ("projection", config.projections or []),
    ]:
        for binding in bindings:
            if "python-uv" in [str(rt) for rt in binding.runtimes or []]:
                members.append((kind, binding.name))

    if not members:
        logger.error(
            "No python-uv elements in libconfig.yaml — nothing to wire. "
            "Run `dizzy generate libraries` first."
        )
        raise typer.Exit(code=1)

    write_wiring_python_uv(feat, feat_file, output_dir)
    # Re-emit the manifest with the wiring package as a member. Listing it before
    # it exists would make the whole workspace unresolvable, so `libraries` leaves
    # it out and this stage adds it.
    write_workspace_python_uv(members, output_dir, include_wiring=True, dizzy_source=dizzy_source)
    logger.info(
        "Generated lib/python-uv/wiring/. Build a HostApp with "
        "wiring.host_app(...) and point $DIZZY_HOST_APP at it."
    )

simulate(feat_file, scenario_file, session_path=Path('session.jsonl'), provider='openrouter', model=None, verbose=False)

LLM-driven execution of a feature-file against a scenario (level 0).

Source code in dizzy/src/dizzy/cli.py

@app.command()
def simulate(
    feat_file: Annotated[Path, typer.Argument(help="Path to the .feat.yaml file")],
    scenario_file: Annotated[Path, typer.Argument(help="Path to the .scenario.yaml file")],
    session_path: Annotated[Path, typer.Argument(help="Output session JSONL file")] = Path(
        "session.jsonl"
    ),
    provider: Annotated[
        str, typer.Option(help="LLM provider: openrouter | ollama | unsloth")
    ] = "openrouter",
    model: Annotated[
        str | None, typer.Option(help="Model override (provider default if omitted)")
    ] = None,
    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Stream LLM output")] = False,
) -> None:
    """LLM-driven execution of a feature-file against a scenario (level 0)."""
    session = Session(session_path).load_features(feat_file)
    procedure_executor = SimProcedureExecutor(
        session._feature, provider=provider, model=model, verbose_stream=verbose
    )
    policy_executor = SimPolicyExecutor(
        session._feature, provider=provider, model=model, verbose_stream=verbose
    )
    session.run_scenario(scenario_file, procedure_executor, policy_executor)
    findings = [e for e in session._session if e["type"] == "finding"]
    if findings:
        logger.info("%d finding(s) recorded — see %s", len(findings), session_path)
    else:
        logger.info("Run complete, no findings. Session: %s", session_path)

config()

Print a template dizzy configuration file.

Source code in dizzy/src/dizzy/cli.py

@app.command()
def config() -> None:
    """Print a template dizzy configuration file."""
    typer.echo(CONFIG_TEMPLATE, nl=False)

docs(page='cli')

Print Dizzy documentation (default: the CLI manpage & roadmap).

Source code in dizzy/src/dizzy/cli.py

@app.command()
def docs(
    page: Annotated[
        str,
        typer.Argument(help=f"Page to print: {' | '.join(DOC_PAGES)}"),
    ] = "cli",
) -> None:
    """Print Dizzy documentation (default: the CLI manpage & roadmap)."""
    if page not in DOC_PAGES:
        logger.error("Unknown docs page %r. Available pages: %s", page, ", ".join(DOC_PAGES))
        raise typer.Exit(code=1)

    _print_doc(DOC_PAGES[page])

onboard()

Print the agent-facing DIZZY overview: components, feature-file role, change taxonomy, exemplar events, and which command fits each lifecycle step.

Source code in dizzy/src/dizzy/cli.py

@app.command()
def onboard() -> None:
    """Print the agent-facing DIZZY overview: components, feature-file role,
    change taxonomy, exemplar events, and which command fits each lifecycle step."""
    _print_doc("onboard.md")