seshat-bi 0.2.0

Seshat BI: agent-first Retail BI readiness checker (static retail check + live retail validate over the medallion warehouse and Power BI conventions).

An agent-first Retail BI readiness system: profile the source, map its meaning, build the medallion warehouse, validate it, define metrics, prepare the semantic model, design the dashboard -- and only then publish.

---

Why Seshat

Seshat was the ancient Egyptian figure of writing, measurement, and record keeping -- you mapped and documented the world before you built on it. This tool takes the same stance toward retail data: nothing advances without recorded evidence and a passed gate.

Seshat BI answers one question, safely:

Is this retail source ready to become trusted Power BI analytics?

It is not a pile of SQL scripts and .pbix files. It is a disciplined operating kit for an AI agent (or a BI developer) that refuses to skip a step. Readiness is never a faked confidence score -- it is status + evidence + blocking_reasons.

[!NOTE] Naming. The product is Seshat BI. The distribution is seshat-bi and the import module is seshat; seshat is also the primary command, with retail kept as a deprecated compatibility command/module for one deprecation cycle. It was previously developed under the internal name Tower BI Agent Kit; the governance spine is still called the Readiness System. Same product, one brand.

---

The seven-star readiness spine

The seven points of the Seshat star are the seven readiness stages. Each is a gate: a stage is never entered before the prior one passes.

flowchart LR
    RAW([raw source]):::raw
    S1[1 - Source Ready<br/><sub>profiled and understood</sub>]:::stage
    S2[2 - Mapping Ready<br/><sub>grain / keys / PII / placement</sub>]:::stage
    S3[3 - Silver Ready<br/><sub>typed, cleaned, statically clean</sub>]:::stage
    S4[4 - Gold Ready<br/><sub>Kimball mart + live-validated</sub>]:::stage
    S5[5 - Semantic Model Ready<br/><sub>metric contracts + governed model</sub>]:::stage
    S6[6 - Dashboard Ready<br/><sub>designed from approved metrics</sub>]:::stage
    S7[7 - Publish Ready<br/><sub>handoff pack, approved to publish</sub>]:::stage

    RAW --> S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7

    classDef raw fill:#E8D8BD,stroke:#001E35,stroke-width:1px,color:#001E35;
    classDef stage fill:#001E35,stroke:#C69214,stroke-width:1.5px,color:#F7F1E7;

The ordering is non-negotiable, and the gates are the product:

[!IMPORTANT]

• No source goes directly to silver.
• No gold reaches Power BI before validation.
• No dashboard is designed before its metrics are defined.
• No Power BI execution runs before semantic-model readiness.

---

Quickstart

Seshat BI gives an agent one truthful next action for turning raw retail data into governed BI. Your first run needs neither a database nor Power BI Desktop.

See the readiness proof

Run the bundled, invented retail fixture entirely offline:

seshat demo init
seshat demo run
seshat demo report --format html

The report is written to .seshat-output/demo/index.html. It shows the evidence, blockers, approvals, and next allowed action for all seven stages. Offline proof stops honestly at Gold Ready because the live validation boundary needs a database.

[!NOTE] seshat-bi is the intended distribution name. Repository implementation does not prove public availability; the install commands below become the public path only when the corresponding public-install evidence is recorded.

Distribution surface	Repository state	Public availability authority
Python (seshat-bi)	build/lifecycle validation implemented	public PyPI install evidence
Claude Code GitHub plugin	generated repository bundle	external add/install acceptance plus owner publication
Codex repository plugin	generated repository bundle	external CLI/IDE acceptance
Claude public catalog	separate owner action	catalog install evidence
OpenAI public plugin listing	separate submission/review	accepted listing/install evidence

Statuses must say available, unavailable, unverified, or a concrete blocked reason per surface; one successful surface never implies a coordinated full launch.

Three steps to first success

1. pipx install seshat-bi (after public availability is verified)
2. seshat init-project my-bi
3. cd my-bi, run git init, then seshat check

Try without a database

Windows (release-gated path)

pipx install seshat-bi           # after public availability is verified
pipx ensurepath                  # reopen PowerShell if seshat is not found
seshat --help
seshat init-project my-bi
cd my-bi
git init
seshat status --format json      # expected: {"tables": []}
seshat next --format agent       # truthful Source Ready onboarding action
seshat check                     # expected: exit 0

macOS / Linux (documented; best-effort tested)

pipx install seshat-bi           # after public availability is verified
pipx ensurepath                  # reopen your shell if seshat is not found
seshat --help
seshat init-project my-bi
cd my-bi
git init
seshat status --format json      # expected: {"tables": []}
seshat next --format agent       # truthful Source Ready onboarding action
seshat check                     # expected: exit 0

A successful first run lists init-project, status, next, and check in seshat --help. The next result says not_started, includes evidence and blockers, and never invents a pass or a numeric score.

If seshat is not on PATH after installation, run pipx ensurepath, reopen the shell, or use python -m seshat.cli <verb>. The legacy fallback python -m retail.cli <verb> remains available for one deprecation cycle.

Problem	What to do
python or pipx is missing	Install Python 3.13 and pipx, then retry.
seshat is not found	Run pipx ensurepath, reopen the shell, or use python -m seshat.cli <verb>.
check or next says Git is unavailable / the directory is not a repo	Install Git if needed, then run git init in the new workspace.
Plugin installation fails	Confirm the marketplace is publicly released; the local-path flow is development-only.

Connect a database later

A normal install brings no database, file, test, or lint dependency. When live validation is needed, install only the relevant extra:

pipx inject seshat-bi psycopg2-binary  # or install "seshat-bi[db]" (target — not yet published)
seshat validate --source-map mappings/<table>/source-map.yaml

mssql, mysql, snowflake, and files are additional user-path extras. Put credentials only in the git-ignored .env file. See the complete user install guide and the Claude Code and Codex guide.

What is built today

Everything below is on main, each with a written spec (under specs/ or docs/superpowers/specs/) and held by the retail check gate. (For what is planned but not yet built, see the Roadmap.)

Capability	What it gives you
Spec-Kit foundation + agent constitution	The governance law every workflow obeys (.specify/memory/constitution.md).
Source-mapping gate	source-map.yaml must be reviewed before any silver SQL is written.
retail check (static gate)	A static gate over committed SQL, TMDL/PBIR, config, docs, and repo text (rule catalog: docs/glossary.md); the exit code is the authority.
retail validate (live surface)	PK uniqueness, date coverage, orphan FKs, reconciliation, source-map-driven checks.
DAX governance L1-L2	DAX best-practice rules D1-D11 enforced statically inside retail check (single-quote handling, ALL-variants, dollar-quote tokenizer, and more).
retail semantic-check (L3 contract drift)	Detects when a committed measure's denominator drifts from its metric contract.
retail value-check (L4 value proxy)	Recomputes a measure's live aggregate and compares it to an owner-approved expected value within tolerance -- never fakes a pass.
retail generate (DAX Generator)	Generates a verified best-practice DAX measure from an approved metric contract, with a self-proving loop.
retail status (agent-control surface)	A read-only --format json projection of committed readiness state (per-table current_stage, evidence, blocking_reasons, next_action) for an agent/host to poll -- a projection of committed evidence, never a computed or fabricated score.
seshat command + init-project	seshat is the product-brand alias of retail (same entry point). seshat init-project <name> scaffolds a fresh, empty Retail-BI project workspace for a new user.
PBIR authoring adapters	Deterministic, local-file, reviewable writers for committed PBIR JSON: pbir-apply-theme, pbir-format-visual, pbir-set-page-background, pbir-set-geometry -- style/lay out existing bound visuals; never create/retype a visual or grant a stage. Publish/execution stays gated (F016).
Readiness spine (F005-F015, incl. F011A)	The full seven-stage model: source intelligence, grain confidence, metric contracts, semantic-model readiness, dashboard design + the four-surface Visual Foundation, QC control room, reconciliation ledger, drift detector.
Companion Modules & Adapters (F025-F030)	Six docs-first skills: PR readiness reviewer, readiness viewer, approval console, evidence-pack generator, and optional dbt / Dagster adapters (advisory only -- they never create truth).
F034 authoring slice	The trace template, Dashboard Ready evidence item, and the read-only visual-implementation-review workflow (the built page itself stays a human Power BI Desktop action).
C086 pharmacy worked example	A complete, filled run of the pipeline -- proof of the pattern, not the universal schema.
retail_store_sales worked example	The validated worked example -- traverses the full seven-stage spine (to Dashboard Ready, Publish Ready warning) -- proves the generic playbook (no returns; PII kept; English-only).
Offline readiness proof (HTML)	seshat demo report --format html renders the seven-stage proof as a static, disclosure-safe page -- evidence, blockers, approvals, next action; honest stop at the live boundary (spec 120 US1).
Review integration (--format review/sarif + GitHub action)	Stable review JSON with changed-state digest, optional SARIF 2.1.0, and a read-only composite action under integrations/github-action/ (spec 120 US2).
seshat mcp (read-only agent governor)	Optional stable MCP v1 stdio adapter exposing six read-only governance tools; refuses execution and approval by construction (docs, spec 120 US3).
seshat passport export/verify	Portable, disclosure-safe readiness evidence snapshots with content-hash verification (verified/changed/missing/incompatible/unavailable) -- records approvals, never grants them (docs, spec 120 US4).
seshat pack scaffold/validate	Governed, declarative local extension packs across six knowledge categories, with fail-closed validation and three generic reference packs (docs, spec 120 US5).
Contributor surfaces	Five structured issue forms, an evidence-prompting PR template, and five bounded starter lanes reachable through three documents (start here, spec 120 US6).
seshat benchmark run/report	Vendor-neutral categorical agent safety benchmark with a deterministic scripted reference participant and disclosed run conditions -- never a score or leaderboard (docs, spec 120 US7).
seshat explorer build	Self-contained offline HTML portfolio explorer: table-by-stage status, evidence availability, blockers, approvals, metric lineage; disclosure-gated generation (docs, spec 120 US8).

A green static check is necessary but not sufficient: semantic correctness needs the live validation boundary when a database is available.

---

Architecture

flowchart LR
    SRC([raw source]):::raw
    B[bronze<br/><sub>landing</sub>]:::med
    S[silver<br/><sub>cleaned</sub>]:::med
    G[gold<br/><sub>Kimball mart</sub>]:::gold
    PBI[Power BI PBIP<br/><sub>reads gold only</sub>]:::pbi

    SRC -.->|manual load now, automated later| B
    B --> S --> G --> PBI

    subgraph DO [DigitalOcean PostgreSQL]
        B
        S
        G
    end

    classDef raw fill:#E8D8BD,stroke:#001E35,color:#001E35;
    classDef med fill:#001E35,stroke:#0B9A9A,stroke-width:1.5px,color:#F7F1E7;
    classDef gold fill:#001E35,stroke:#C69214,stroke-width:2px,color:#F2C14E;
    classDef pbi fill:#0B9A9A,stroke:#001E35,stroke-width:1.5px,color:#F7F1E7;
    style DO fill:#F7F1E7,stroke:#C69214,stroke-dasharray:4 3,color:#001E35;

Responsibilities stay separated; Power BI is the reporting target, never the source of truth.

Layer	Responsibility
Agent Experience	Reads readiness state, performs only the next allowed action.
Source Intelligence	Profiles sources, detects grain, maps business meaning, tracks drift.
Mapping Governance	Makes source-map.yaml reviewable before any silver SQL.
Validation & Readiness	retail check, retail validate, QC control room, reconciliation ledger.
Metrics & Semantic Model	KPI packs, metric contracts, semantic-model readiness.
Dashboard & Delivery	Dashboard blueprints and handoff packs; execution adapter comes last.

---

Start here as an agent

Agent Mode -- the guarded loop (inspect -> seshat status -> seshat next -> do only the next allowed action -> seshat check -> stop at the gate) is documented in docs/agent-mode.md. seshat next --format agent (or --format json for hosts) answers: current stage, readiness state, evidence, blockers, next allowed action, forbidden scope, validation commands, and the stop point.

Read in this order, then act on the target's readiness state -- and only the next allowed action:

1. AGENTS.md -- the short operating contract: what the agent can and cannot do.
2. .specify/memory/constitution.md -- the full governance law.
3. docs/readiness/readiness-model.md -- the seven-stage spine.
4. docs/architecture/readiness-pipeline.md -- how readiness sits on the kit.
5. docs/worked-examples/retail-store-sales.md -- the filled worked example; the full spine to Dashboard Ready.
6. docs/worked-examples/README.md -- the worked-examples index (which to read when).

Typical agent flow

read readiness status
  -> profile source
  -> draft source-map.yaml
  -> record assumptions / questions / issues
  -> STOP for review if mapping is blocked
  -> build silver only after Mapping Ready passes
  -> build gold only after silver is clean
  -> validate gold before Power BI
  -> define metric contracts before dashboard design
  -> create handoff pack before publish

---

Repository layout

Path	Purpose
AGENTS.md	Operating contract for AI agents. Read first.
.specify/	Spec-Kit constitution and governance memory.
src/seshat/	The retail CLI package: static + live governance surfaces.
warehouse/	Tool-agnostic medallion SQL: bronze / silver / gold + migrations.
powerbi/	Power BI PBIP artifacts. Power BI reads gold only.
specs/	Feature specs, plans, tasks, checklists (one directory per feature; see specs/README.md).
mappings/	Filled per-table source-mapping artifacts, one folder per table.
templates/	Generic blanks: profiles, maps, contracts, readiness, dashboards, handoff packs.
reports/	Dashboard / page / visual blueprints and delivery artifacts.
pipelines/	Ingestion area: manual now, automated feed later.
docs/readiness/	The seven-stage Readiness System spine.
docs/roadmap/	Delivered ledger + the planned companion tier.
docs/brand/	The Seshat BI visual identity and brand rules.
assets/brand/	Committed brand assets (logo, seven-point star).

---

Power BI policy

Power BI is the reporting target, not the source of truth.

• Reads from gold only.
• Every measure traces to a metric contract; blueprints invent no KPIs.
• PBIP artifacts stay source-control friendly (plain-text TMDL/PBIR).
• Publishing / execution automation is deferred until semantic-model readiness passes.

---

Roadmap

The originally-specified sequence (F005-F015, including F011A) is fully shipped to main. What remains is deliberately human-gated or deferred for want of a consumer -- never blocked by missing effort:

[!WARNING] The items below are not current capabilities. Do not treat a gated or deferred feature as if it were shipped.

Remaining item	State	Why it waits
F016 -- Power BI execution adapter	gated, by design	Execution-only (materializes/publishes an already-approved model; cannot define metrics, mappings, semantic logic, or dashboard design). Deliberately last; not startable before semantic_model_ready is pass.
F034 built page	human action	The agent ships the trace template + review workflow; a person builds the approved design in Power BI Desktop and commits the PBIR.
F024 + F031-F033	spec-only	Companion architecture doc + maintenance automation -- no runtime consumer yet (the adapters they would maintain are docs-only skills).
pbi-tools extract / L3 new operators	deferred	Revisit when a real .pbix + installed toolchain (pbi-tools) or a real predicate consumer (L3) appears.

[!NOTE] The Companion Modules & Adapters that did ship (F025-F030 -- PR readiness reviewer, readiness viewer, approval console, evidence-pack generator, and the optional dbt / Dagster adapters) are listed under What is built today. dbt and Dagster are optional companion engines and advisory only -- they never create truth.

Guiding rules: any new feature must improve exactly one readiness stage, and docs / templates / checklists come before automation. Full ledger: docs/roadmap/roadmap.md.

---

What this is not

Seshat BI is a small, governed Retail BI factory -- agent-led, evidence-based, and blocked by real BI gates before delivery. It is deliberately not:

• a one-click automatic dashboard generator,
• a Fabric deployment platform,
• an ML / forecasting system,
• a universal ERP connector,
• a fully automated mapping-approval engine,
• a Power BI execution-first tool.

---

Brand

The public identity is Seshat BI: a seven-point gold star (canonical truth and the seven readiness gates), a teal data network (lineage and the BI model), and the seated Seshat figure with a stylus (mapping and documentation before transformation). The star is always seven-pointed.

Full guide: docs/brand/visual-identity.md -- reusable mark: assets/brand/seshat-seven-star.svg.

Palette: deep_navy #001E35 | rich_gold #C69214 | teal #0B9A9A | ivory #F7F1E7.

---

Contributing

• Commit subjects follow <type>: <description> (feat / fix / refactor / docs / chore / build / ci / perf / test / style / revert / brand), scope-free -- no docs(018): parentheses (governance rule P2). An automated [bot] ... subject prefix is exempt.
• Conventions: docs/conventions.md.
• Glossary (terms, abbreviations, rule ids): docs/glossary.md.
• Contributing (setup, local checks, PR flow): CONTRIBUTING.md.
• First contribution (three-document newcomer path + bounded starter lanes): docs/contributing/first-contribution.md.
• FAQ (common questions, with sources): docs/faq.md.
• Release notes: RELEASE_NOTES.md -- and the v0.1 snapshot docs/releases/v0.1.md.
• Local verification (mirrors CI intent): docs/quality/local-verification.md.
• Guided demo (worked example): docs/demo/retail-store-sales-demo.md.
• Capability snapshot: docs/quality/post-idea-bank-capability-state.md -- what works now / planned / forbidden / needs-ruling / needs-data, by layer.
• Net Sales end-to-end trace (paper proof of one KPI path): docs/demo/net-sales-end-to-end-readiness-trace.md.
• Big Data strategy (scale is a condition, not a tool): docs/big-data/big-data-capability-report.md + the assessment templates docs/big-data/data-volume-assessment.md.
• Integration smoke test for the idea-bank features: docs/quality/top-idea-bank-integration-smoke-test.md.
• Before a PR, retail check must pass and committed text must be ASCII / UTF-8 without BOM.
• License: Apache-2.0 (see LICENSE).

_{Seshat BI -- governed knowledge, measured structure, trusted BI.}