Input

Input mode adapts an existing Lex app to a changed input-data format across seven change areas, treating the change as a code migration rather than a configuration setting.

A
Written By Atakan KayaLast updated 3 months ago

Input

Input mode adapts an existing LEX app to a changed input-data format: renamed, added or dropped columns, a new delimiter, a new encoding, a new row grain. It is a flat workflow over a fixed set of change areas, and it never commits or pushes.

Slash command: /lex-input.

Why this is a code change, not a setting

Lex ships no configurable input parser. Upload files are plain Django FileFields, parsed by hand-written pandas code inside calculate(), with column names as string literals. A new column heading therefore touches source, migrations and fixtures — there is no mapping table to edit. That is why the mode exists.

The flow

/lex-input
  ↓
kickstart_input_change(project_path=... OR github_url=...)   # mandatory first call
  ↓
register_format_change(source_kind="sample_file"|"verbal", ...)   # once per changed file
get_intake_brief()                       # analyst writes input-changes/format-spec-<run-id>.md
list_change_areas()                      # optional discovery
  ↓ per area you need:
get_change_brief(area, focus=...) → runSubagent(brief.agent) → notify_change_complete(...)
  ↓
finalize_input_change()                  # writes input-changes/INPUT-CHANGE-REPORT.md

Describing the new format

With source_kind="sample_file" the server reads the file itself: CSV, TSV and TXT are sniffed with the standard-library csv.Sniffer across comma, semicolon, tab and pipe, returning the delimiter, column names, count and up to three sample rows; XLSX, XLS and PDF go through the shared reader described in Tool surfaces. With source_kind="verbal" the lex-input-analyst agent interviews the user instead.

The seven change areas

Area

What it covers

upload-parser

The hand-written parsing code in calculate()

data-model

Upload and input model fields

migrations

Schema migrations for the model change

calc-fanout

Downstream calculations reading the changed fields

reports

Report definitions referencing old column names

serializers

DRF serializers and their validate_<field> methods

test-data

JSON scenario data and binary fixtures in the old format

There is no fixed order. upload-parser, migrations and test-data are recommended on every run — skipping one warns at finalize rather than blocking. The one mechanical check sits in notify_change_complete, which refuses a completion whose declared artifacts do not exist on disk.

The silent failures it exists to prevent

None of these throw, which is why a format change is more dangerous than it looks:

  • A .get() default on a renamed column — the import reports SUCCESS and stores wrong data.
  • An orphaned validate_<field> serializer method — after a rename it stops being called, so validation silently ends.
  • Stale binary fixtures — the suite stays green against the old format while the app reads the new one.
  • A renamed upsert key — updates become duplicating inserts.

Two structural points follow. A changed row grain can require an entirely new input model, because Lex enforces one input model per unique input-column schema. And recalculation is not automatic: the get_dependent_entries cascade is opt-in and half-migrated, so stale SUCCESS rows are re-triggered by setting is_calculated = "IN_PROGRESS" and saving.

Where output lands

Everything is written under <project_root>/input-changes/: format-spec-<run-id>.md, one <area>-<run-id>.md per area, an auto-maintained _index.md, and the consolidated INPUT-CHANGE-REPORT.md. Code changes land in the working tree for you to commit. See Outputs and artifacts.

Was this helpful?

Your feedback shapes what we write next.