Skip to content

Add tablassert init to scaffold a graph project #276

Open

Description

@SkyeAv

Problem Statement

Starting a new graph means copying the tutorial YAMLs (docs/examples/) and editing
every field by hand. There is no command that lays out a working project: graph config,
table config, source placement, and .fullmap convention.

Proposed Solution

tablassert init [NAME] scaffolds a project directory: a minimal graph config, one
table config wired to a sample source, commented placeholders for provenance/RIG, and
a printed next-steps checklist (build-fullmap or prebuilt fetch, validate,
build-kg). Flags for source kind (--kind excel|text|parquet|...) pick the matching
source block.

Benefits

  • First successful build in minutes instead of schema archaeology.
  • Scaffolded output teaches the config conventions by example, in place.

Implementation Details

  • Cyclopts command alongside build-kg/validate (src/tablassert/cli.py); cli
    extra preflight via extras.require.
  • Generate through ingests.to_yaml and the pydantic models so scaffolds are
    schema-valid by construction, not string templates that drift.
  • Refuse to overwrite existing files without --force.
  • Docs: docs/cli.md command index and docs/tutorial.md pointer (docs-coverage test
    enforces sync).
  • Pairs with the draft-from-table-config issue: init starts empty, draft starts
    from an existing table config.

Success Metrics

  • tablassert init demo && tablassert validate demo/graph.yaml --schema graph passes
    on a fresh install; scaffolded tutorial build matches docs/examples/ output.

Activity

  1. SkyeAv commented on Nov 18, 2026

    @SkyeAv
    OwnerAuthor

    Related: #270 (draft graph config from a table config).

  2. SkyeAv commented on Nov 19, 2026

    @SkyeAv
    OwnerAuthor

    After reviewing #291, I am narrowing the success metric. A fresh scaffold should produce schema-valid graph.yaml and tables/table.yaml for each --kind, with tablassert validate ... --schema graph passing and overwrite protection intact.

    I am dropping the requirement that the scaffolded tutorial build match docs/examples/ output. Generating a sample data file implies a runnable build before the user has a fullmap and real source data, and adds format-specific writer concerns. Users should supply their own data and update the local path.

    @ArdaTkn, please adjust #291 to this scope.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions