# Chartsmith

> Give it a chart image. Get back the same facts with more force.

![Chartsmith — The same facts, more force](docs/current/assets/chartsmith-devpost-thumbnail.png)

Chartsmith is a one-shot autonomous chart-redesign system. It accepts an image
alone, reconstructs what the chart says, explores materially different visual
directions, renders and inspects real candidates, repairs visible defects, and
releases only an accepted redesign with an audit trail.

The product tests a simple idea: strong visualization design is not merely
decoration or taste. Much of it can be reasoned about—what the audience should
notice first, which visual grammar best serves that message, what evidence must
remain intact, and whether the finished image is genuinely clearer and more
persuasive.

[Live showcase](https://chartsmith-build-week.sseo.chatgpt.site) ·
[Public repository](https://github.com/sseo0817/chartsmith) ·
[Build Week provenance](PUBLIC_RELEASE.md) ·
[Product doctrine](docs/current/product_doctrine.md)

## See the transformation

![Ten accepted source-to-redesign journeys](examples/build_week_vnext/portfolio_contact_sheet.jpg)

The submission includes ten distinct accepted examples across paired
distributions, ranked bars, scientific scatter panels, a line chart, grouped
bars, heatmap, bubble scatter, interval plot, funnel, and stacked area chart.
Every journey contains its source, final image, comparison, reconstruction,
concept set, evaluator result, review dossier, and model provenance.

The [public showcase](https://chartsmith-build-week.sseo.chatgpt.site) presents
all ten immediately. Genuine new-image generation remains a local workflow
because a high-quality run can take tens of minutes; the deployment never
simulates a live result.

## What makes it a system

A single “make this chart better” call can produce an attractive image, but it
does not reliably preserve chart grammar, expose design reasoning, inspect its
own rendered pixels, or keep repairing until release gates pass. Chartsmith uses
a deterministic seven-stage outer workflow:

1. **Perceptual reconstruction** — infer claims, labels, geometry, uncertainty,
   and data-bearing structure from the image.
2. **Design proposition** — generate three meaningfully different communication
   ideas, including hybrid visual forms beyond a chart library's defaults.
3. **Autonomous selection** — choose the strongest defensible direction.
4. **Render** — build a real image through code-native or hybrid generation.
5. **Rendered-image review** — inspect the pixels actually produced, not only
   the render plan.
6. **Repair or pivot** — fix production defects locally or change concept when
   the idea itself fails.
7. **Release evaluation** — require production integrity, epistemic integrity,
   material communication gain, design authorship, and GPT-5.6 provenance.

Model intelligence operates inside bounded stages. Scheduling, artifacts,
budgets, and release rules stay deterministic and auditable.

## Product experience

The judge-facing app is in [`app/web`](app/web). It makes intermediate work
useful to a waiting viewer: reconstruction becomes a visual evidence summary;
concepts become designed direction cards; reviews identify what the system saw
and repaired; and the final release explains why it passed.

### Verified Windows quick start

Start with [`START_HERE.md`](START_HERE.md) for the first-launch checklist,
success state, and troubleshooting.

Prerequisites: Python 3.11 or newer, Node.js 22.13 or newer, and a ChatGPT
account that can sign in to Codex. From an extracted Chartsmith local edition,
run one command:

```powershell
python scripts\setup_and_start.py
```

The setup verifies that the downloaded edition is complete, creates an isolated
Python environment, installs locked web requirements, installs Python
requirements, resolves a supported Codex executable, and starts both product
services. It stops with an exact login command when Codex is not signed in.
Then open `http://localhost:3000/`. The ten accepted examples are
available immediately. Uploading a new image invokes the genuine local
workflow; a full redesign can take tens of minutes.

On macOS or Linux, install and sign in to a current Codex CLI first, then run
the same setup command.

## Run the workflow directly

Install a current official Codex CLI without replacing a global installation:

```powershell
$codexBin = .\scripts\bootstrap_codex.ps1 | Select-Object -Last 1
```

Then validate and run:

```powershell
.\.venv\Scripts\python.exe scripts\chartsmith_vnext.py validate
.\.venv\Scripts\python.exe scripts\chartsmith_vnext.py run <image-path> --codex-bin $codexBin
```

The Codex-native image backend does not require `OPENAI_API_KEY`. The judgment
boundary uses GPT-5.6; hybrid concepts can invoke GPT Image 2.

## Evidence and quality gates

The portfolio authority is
[`milestone4_portfolio.yaml`](config/experiments/build_week_vnext/milestone4_portfolio.yaml).
The compact evidence index is
[`portfolio_manifest.json`](examples/build_week_vnext/portfolio_manifest.json).

Validate the product and release:

```powershell
python scripts\chartsmith_vnext.py validate
python scripts\validate_milestone4_portfolio.py
python -m unittest discover -s tests -v
python scripts\validate_repo_state.py

Push-Location app\web
npm test
Pop-Location
```

The public tree itself is a reproducible, rights-conscious export:

```powershell
python scripts\build_public_release.py
python scripts\validate_public_release.py output\public_release\chartsmith
```

## Build Week boundary

Chartsmith began before OpenAI Codex Build Week. The preserved pre-event baseline
is identified by tag `pre-build-week-clean-20260719`. During Build Week, the
project:

- replaced a longer experimental workflow with the promoted compact vNext
  system;
- hardened it through small-case, in-depth evaluation;
- built the complete judge-facing product and polished intermediate-stage UX;
- expanded the evidence from three development cases to ten accepted examples;
- packaged publication, deployment, media, video, licensing, and submission
  evidence.

[`BUILD_WEEK_PLAN.md`](BUILD_WEEK_PLAN.md) and the milestone documents under
[`docs/current`](docs/current) distinguish planned work, implementation, and
completion evidence.

## Repository map

- `app/web/` — showcase and local upload product
- `config/experiments/build_week_vnext/` — promoted workflow, prompts, schemas,
  and portfolio
- `scripts/chartsmith_vnext.py` — deterministic workflow runner
- `scripts/model_invocation.py` — bounded Codex model invocation
- `examples/build_week_vnext/` — compact accepted evidence bundles
- `references/design_inspiration/reference_index.json` — source-linked,
  text-only design guidance used during concept exploration
- `docs/current/` — current doctrine, architecture, operations, and milestone
  evidence

`PROJECT_STATE.yaml` is the machine-readable authority for the implemented
state. `AGENTS.md` defines the maintenance contract.

## Limits

- Image-only reconstruction is intentionally approximate. Chartsmith targets
  presentation-quality communication, not high-stakes numerical certification.
- Full-quality local runs are compute-intensive and can take tens of minutes.
- Slight image-derived numeric error can be acceptable; visible production
  defects, invented chart structure, and broken semantic mappings are not.
- The hosted submission is an evidence-rich showcase, not a simulated hosted
  generation service.

## License

Original Chartsmith code and documentation are MIT licensed. Seven synthetic
portfolio sources are CC0 1.0. Three attributed official figures and all
dependency code retain their original rights. See
[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
