chirality-framework 17.0.0

A semantic calculator for executing a canonical, multi-stage pipeline for structured problem-solving and knowledge generation.

Chirality Framework: A Semantic Calculator

Version: 16.3.0 | Status: Active Development

The Chirality Framework is a "semantic calculator" designed to execute a fixed, canonical algorithm for structured problem-solving. It transforms a set of base matrices through a multi-stage semantic pipeline, producing a series of derived matrices that represent a complete traversal of a "semantic valley" from problem to evaluation.

The value of this project is in the unique, insightful output of the calculation and the observability of the process, not in the flexibility of the code.

Core Concept: The Canonical Pipeline

The framework computes a sequence of matrices, each representing a station in the semantic valley. The primary operations involve:

1. Semantic Dot Product: A two-stage LLM process involving: a. Semantic Resolution: Raw terms are resolved into a concise conceptual summary. b. Combined Ontological Lensing: The conceptual summary is interpreted through a unified lens of the cell's row, column, and station context in a single, powerful LLM call.
2. Station Shifting: An LLM-driven transformation of a matrix from one context (e.g., Verification) to another (e.g., Validation), also performed using the Combined Lensing pipeline.
3. Structural Operations: Standard matrix operations like transposing and slicing, which do not involve an LLM.

For a complete technical description, see the Canonical Algorithm Documentation.

The Ontological Modality Path

The sequence of stations in the semantic valley is not arbitrary; it follows a deep, underlying pattern of cognitive modalities. This path describes the type of work being done at each stage, revealing a structured cycle of systematic processing, epistemic (knowledge-based) evaluation, and alethic (truth-based) assessment.

Modality	Station	Operation
Problem	1. Problem Statement	[A], [B]
Systematic	2. Requirements	[C] = [A] * [B]
Process	3. Objectives	[D] = [A] + [F]
Epistemic	4. Verification	[K] = [D]^T, [X] = [K] * [J]
Epistemic	5. Validation	[Z] = shift([X])
Process	6. Evaluation	[G], [P], [T], [E]
Alethic	7. Assessment	[M] = [R] x [E]
Epistemic	8. Implementation	[W] = [M] x [X]
Alethic	9. Integration	[U] = [W] x [P]
Alethic	10. Reflection	[N] = [U] x [H]
Resolution	11. Resolution	Final = synth([N])

Clarifications:

• X/Z Modality: Both Verification (S4) and Validation (S5) are Epistemic. S4 strictly precedes S5.
• E Modality: Evaluation (S6) is a Process modality, not Epistemic.

For a detailed explanation of this conceptual architecture, see the Project Philosophy Documentation.

Quick Start: The End-to-End Workflow

The recommended way to use the framework is to compute the entire pipeline and view the results in the generated HTML viewer.

Prerequisites

• Python 3.9+
• An OpenAI API key set as the OPENAI_API_KEY environment variable.

Step 1: Compute the Full Pipeline

This command runs the entire semantic pipeline (Matrices C through E), generates snapshots of every matrix (including the base matrices A, B, and J), and creates detailed trace files for debugging.

# Install with OpenAI support
pip install 'chirality-framework[openai]'

# Set your API key (add to your shell profile for persistence)
export OPENAI_API_KEY="sk-..."

# Run the full pipeline with the OpenAI resolver
python3 -m chirality.cli compute-pipeline --resolver openai --snapshot-jsonl --include-base

This will create two directories, snapshots/<run_id>/ and traces/<run_id>/, containing the output files.

Step 2: Render and View the Results

This command reads the generated snapshots and creates a self-contained HTML file to display all the matrices in an elegant, readable format.

# Render the latest run and open it in your browser
python3 -m chirality.cli render-viewer --latest --open

This will create a viewer-output/ directory containing the index.html and style.css files and automatically open the page for you. You can change the output location with --output-dir.

Advanced Usage

App Integration Mode (Producer Contract)

For automation by external apps (e.g., chirality-app), use app mode to write a manifest and contract snapshots with a single JSON result to stdout.

python3 -m chirality.cli compute-pipeline \
  --resolver echo \
  --out runs/my-run-1 \
  --problem-file problem.json \
  --max-seconds 900

• Writes per-cell JSONL snapshots for C, D, X, E under runs/<run_id>/snapshots/ with format cells-jsonl-v1.
• Writes runs/<run_id>/index.json last and atomically with checksums, sizes, and record counts.
• Prints exactly one JSON line to stdout on success: { "run_id": "...", "manifest": "runs/<run_id>/index.json" }.
• Exit codes: 0 success; 2 invalid args; 3 timeout; 4 I/O; 5 resolver; 1 general.
• Backward compatibility: also dual-writes legacy snapshots for all computed matrices to snapshots/<run_id>/ for the built-in viewer.

App Mode (Chirality App Integration)

• Generate a run:

  python3 -m chirality.cli compute-pipeline --resolver <echo|openai> --out runs/<run_id> --problem-file problem.json --max-seconds 900

• Output:

  • runs/<run_id>/index.json
  • runs/<run_id>/snapshots/{C,D,X,E}.jsonl

• Stdout (last line):

  {"run_id":"<run_id>","manifest":"runs/<run_id>/index.json"}

• Contract:

  • Manifest framework_schema_version = "1.0.0"
  • Each matrix entry includes path, format:"cells-jsonl-v1", records, sha256, bytes
  • JSONL rows include id, matrix, row, col, row_label, col_label, station, text, citations, refs, meta.order

Using Framework Artifacts (chirality-app)

• Set CHIRALITY_RUNS_DIR=/absolute/path/to/chirality-framework/runs in chirality-app .env.local
• Ingest: POST /api/agent/run with body {"framework_run_id":"<run_id>"} (optionally include "enable_rag": true)
• Export: GET /api/agent/export/<run_id> with header X-Role: approver

Computing Individual Matrices

The compute-matrix command allows you to compute and snapshot any single matrix, automatically handling its prerequisites.

# Compute just the final Evaluation matrix (E)
python3 -m chirality.cli compute-matrix E --resolver openai --snapshot-jsonl

# Snapshot a base matrix for reference
python3 -m chirality.cli compute-matrix A --snapshot-jsonl

Inspecting a Single Cell

For detailed debugging, the compute-cell command lets you observe the new canonical pipeline for any single cell in a matrix.

# Observe the computation of cell C[0,0] with verbose output
python3 -m chirality.cli compute-cell C --i 0 --j 0 --resolver openai --verbose --trace

Viewing Options

The render-viewer command has several options for customizing the output:

# Render a specific run with a custom title
python3 -m chirality.cli render-viewer --run-id "<run_id>" --title "My Analysis"

# Render with the "Elements" style for a more code-like view
python3 -m chirality.cli render-viewer --latest --style elements

# Disable the default value sanitization to see raw output
python3 -m chirality.cli render-viewer --latest --style elements --no-sanitize-values

Common CLI Commands

• Compute full pipeline (dev): python3 -m chirality.cli compute-pipeline --resolver echo --snapshot-jsonl --include-base -v
• App-mode run (artifacts): python3 -m chirality.cli compute-pipeline --resolver echo --out runs/my-run-1 --problem-file problem.json --max-seconds 900
• Render latest viewer: python3 -m chirality.cli render-viewer --latest --open
• Inspect a cell: python3 -m chirality.cli compute-cell C --i 0 --j 0 -v

See full CLI Quick Reference in docs/API_REFERENCE.md#cli-reference.

Development

To set up the development environment and run tests, please refer to the instructions in CONTRIBUTING.md.

Additional docs:

• docs/INTERFACE.md: Producer mirror of the chirality-app contract (app mode).
• GEMINI.md: Guidance for using Gemini/AI assistants with this repo.
• CLAUDE.md: Guidance for using Claude Code with this repo.
• AGENTS.md: Notes for agentic coding assistants working on this project.