# Chirality Framework: A Semantic Calculator
[](https://pypi.org/project/chirality-framework/)
[](https://pypi.org/project/chirality-framework/)
[](LICENSE)
[](https://github.com/sgttomas/chirality-framework/actions/workflows/python-publish.yml)
[](https://github.com/psf/black)
[](https://github.com/sgttomas/chirality-framework/tags)
**Version: 17.1.1** | **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 Asset-Based Canonical Pipeline
The framework's logic is driven by a canonical pipeline that is orchestrated using a set of version-controlled, maintainer-authored text files called "prompt assets." All semantic interpretation is performed by an LLM guided by these assets.
The primary operations involve:
1. **Mechanical Construction (Stage 1):** The framework mechanically constructs the initial input for a cell, for example by creating term pairs for a semantic dot product. For Matrix D, this involves creating a sentence from a hard-coded formula. This stage does not use an LLM.
2. **Semantic Resolution (Stage 2):** For operations like semantic multiplication, an LLM, guided by an "operator" prompt asset, resolves the initial input into a single, concise concept.
3. **Combined Ontological Lensing (Stage 3):** The output from the previous stage is interpreted by an LLM guided by a "lensing" prompt asset. This single, powerful call synthesizes the content through the simultaneous perspectives of the cell's row, column, and the station's overall purpose (provided by a "station brief" asset).
For a complete technical description, see the **[Canonical Algorithm Documentation](docs/ALGORITHM.md)**.
For a complete technical description, see the **[Canonical Algorithm Documentation](docs/ALGORITHM.md)**.
## 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](docs/PHILOSOPHY.md)**.
## 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
- **Note**: The framework uses OpenAI's Responses API exclusively (not Chat Completions API)
### 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.
```bash
# Install with OpenAI support (requires OpenAI SDK >=1.50.0)
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.
```bash
# 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.
```bash
# 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.
```bash
# 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:
```bash
# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "chirality-framework",
"maintainer": "Chirality Framework Team",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "llm, ontology, semantic computing, pipeline orchestration, static site generator, knowledge generation",
"author": "Chirality Framework Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e6/03/38dbbfaf9d26701a2c9273687a5e6fb42f2bb4624ff3deacdf70b70de034/chirality_framework-17.1.1.tar.gz",
"platform": null,
"description": "# Chirality Framework: A Semantic Calculator\n\n[](https://pypi.org/project/chirality-framework/)\n[](https://pypi.org/project/chirality-framework/)\n[](LICENSE)\n[](https://github.com/sgttomas/chirality-framework/actions/workflows/python-publish.yml)\n[](https://github.com/psf/black)\n[](https://github.com/sgttomas/chirality-framework/tags)\n\n**Version: 17.1.1** | **Status: Active Development**\n\nThe 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.\n\nThe 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.\n\n## Core Concept: The Asset-Based Canonical Pipeline\n\nThe framework's logic is driven by a canonical pipeline that is orchestrated using a set of version-controlled, maintainer-authored text files called \"prompt assets.\" All semantic interpretation is performed by an LLM guided by these assets.\n\nThe primary operations involve:\n1. **Mechanical Construction (Stage 1):** The framework mechanically constructs the initial input for a cell, for example by creating term pairs for a semantic dot product. For Matrix D, this involves creating a sentence from a hard-coded formula. This stage does not use an LLM.\n2. **Semantic Resolution (Stage 2):** For operations like semantic multiplication, an LLM, guided by an \"operator\" prompt asset, resolves the initial input into a single, concise concept.\n3. **Combined Ontological Lensing (Stage 3):** The output from the previous stage is interpreted by an LLM guided by a \"lensing\" prompt asset. This single, powerful call synthesizes the content through the simultaneous perspectives of the cell's row, column, and the station's overall purpose (provided by a \"station brief\" asset).\n\nFor a complete technical description, see the **[Canonical Algorithm Documentation](docs/ALGORITHM.md)**.\n\nFor a complete technical description, see the **[Canonical Algorithm Documentation](docs/ALGORITHM.md)**.\n\n## The Ontological Modality Path\n\nThe 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.\n\n| Modality | Station | Operation |\n| :--- | :--- | :--- |\n| `Problem` | 1. Problem Statement | `[A], [B]` |\n| `Systematic` | 2. Requirements | `[C] = [A] * [B]` |\n| `Process` | 3. Objectives | `[D] = [A] + [F]` |\n| `Epistemic` | 4. Verification | `[K] = [D]^T, [X] = [K] * [J]` |\n| `Epistemic` | 5. Validation | `[Z] = shift([X])` |\n| `Process` | 6. Evaluation | `[G], [P], [T], [E]` |\n| `Alethic` | 7. Assessment | `[M] = [R] x [E]` |\n| `Epistemic` | 8. Implementation | `[W] = [M] x [X]` |\n| `Alethic` | 9. Integration | `[U] = [W] x [P]` |\n| `Alethic` | 10. Reflection | `[N] = [U] x [H]` |\n| `Resolution` | 11. Resolution | `Final = synth([N])` |\n\n**Clarifications:**\n- **X/Z Modality:** Both Verification (S4) and Validation (S5) are `Epistemic`. S4 strictly precedes S5.\n- **E Modality:** Evaluation (S6) is a `Process` modality, not Epistemic.\n\nFor a detailed explanation of this conceptual architecture, see the **[Project Philosophy Documentation](docs/PHILOSOPHY.md)**.\n\n## Quick Start: The End-to-End Workflow\n\nThe recommended way to use the framework is to compute the entire pipeline and view the results in the generated HTML viewer.\n\n### Prerequisites\n- Python 3.9+\n- An OpenAI API key set as the `OPENAI_API_KEY` environment variable\n- **Note**: The framework uses OpenAI's Responses API exclusively (not Chat Completions API)\n\n### Step 1: Compute the Full Pipeline\nThis 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.\n\n```bash\n# Install with OpenAI support (requires OpenAI SDK >=1.50.0)\npip install 'chirality-framework[openai]'\n\n# Set your API key (add to your shell profile for persistence)\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Run the full pipeline with the OpenAI resolver\npython3 -m chirality.cli compute-pipeline --resolver openai --snapshot-jsonl --include-base\n```\nThis will create two directories, `snapshots/<run_id>/` and `traces/<run_id>/`, containing the output files.\n\n### Step 2: Render and View the Results\nThis command reads the generated snapshots and creates a self-contained HTML file to display all the matrices in an elegant, readable format.\n\n```bash\n# Render the latest run and open it in your browser\npython3 -m chirality.cli render-viewer --latest --open\n```\nThis 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`.\n\n## Advanced Usage\n\n### App Integration Mode (Producer Contract)\nFor 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.\n\n```\npython3 -m chirality.cli compute-pipeline \\\n --resolver echo \\\n --out runs/my-run-1 \\\n --problem-file problem.json \\\n --max-seconds 900\n```\n\n- Writes per-cell JSONL snapshots for `C`, `D`, `X`, `E` under `runs/<run_id>/snapshots/` with format `cells-jsonl-v1`.\n- Writes `runs/<run_id>/index.json` last and atomically with checksums, sizes, and record counts.\n- Prints exactly one JSON line to stdout on success: `{ \"run_id\": \"...\", \"manifest\": \"runs/<run_id>/index.json\" }`.\n- Exit codes: `0` success; `2` invalid args; `3` timeout; `4` I/O; `5` resolver; `1` general.\n- Backward compatibility: also dual-writes legacy snapshots for all computed matrices to `snapshots/<run_id>/` for the built-in viewer.\n\n### App Mode (Chirality App Integration)\n\n- Generate a run:\n\n `python3 -m chirality.cli compute-pipeline --resolver <echo|openai> --out runs/<run_id> --problem-file problem.json --max-seconds 900`\n\n- Output:\n - `runs/<run_id>/index.json`\n - `runs/<run_id>/snapshots/{C,D,X,E}.jsonl`\n\n- Stdout (last line):\n\n `{\"run_id\":\"<run_id>\",\"manifest\":\"runs/<run_id>/index.json\"}`\n\n- Contract:\n - Manifest `framework_schema_version = \"1.0.0\"`\n - Each matrix entry includes `path`, `format:\"cells-jsonl-v1\"`, `records`, `sha256`, `bytes`\n - JSONL rows include `id, matrix, row, col, row_label, col_label, station, text, citations, refs, meta.order`\n\n### Using Framework Artifacts (chirality-app)\n\n- Set `CHIRALITY_RUNS_DIR=/absolute/path/to/chirality-framework/runs` in chirality-app `.env.local`\n- Ingest: `POST /api/agent/run` with body `{\"framework_run_id\":\"<run_id>\"}` (optionally include `\"enable_rag\": true`)\n- Export: `GET /api/agent/export/<run_id>` with header `X-Role: approver`\n\n### Computing Individual Matrices\nThe `compute-matrix` command allows you to compute and snapshot any single matrix, automatically handling its prerequisites.\n\n```bash\n# Compute just the final Evaluation matrix (E)\npython3 -m chirality.cli compute-matrix E --resolver openai --snapshot-jsonl\n\n# Snapshot a base matrix for reference\npython3 -m chirality.cli compute-matrix A --snapshot-jsonl\n```\n\n### Inspecting a Single Cell\nFor detailed debugging, the `compute-cell` command lets you observe the new canonical pipeline for any single cell in a matrix.\n\n```bash\n# Observe the computation of cell C[0,0] with verbose output\npython3 -m chirality.cli compute-cell C --i 0 --j 0 --resolver openai --verbose --trace\n```\n\n### Viewing Options\nThe `render-viewer` command has several options for customizing the output:\n\n```bash\n# Render a specific run with a custom title\npython3 -m chirality.cli render-viewer --run-id \"<run_id>\" --title \"My Analysis\"\n\n# Render with the \"Elements\" style for a more code-like view\npython3 -m chirality.cli render-viewer --latest --style elements\n\n# Disable the default value sanitization to see raw output\npython3 -m chirality.cli render-viewer --latest --style elements --no-sanitize-values\n```\n\n## Common CLI Commands\n\n- Compute full pipeline (dev): `python3 -m chirality.cli compute-pipeline --resolver echo --snapshot-jsonl --include-base -v`\n- App-mode run (artifacts): `python3 -m chirality.cli compute-pipeline --resolver echo --out runs/my-run-1 --problem-file problem.json --max-seconds 900`\n- Render latest viewer: `python3 -m chirality.cli render-viewer --latest --open`\n- Inspect a cell: `python3 -m chirality.cli compute-cell C --i 0 --j 0 -v`\n\nSee full CLI Quick Reference in `docs/API_REFERENCE.md#cli-reference`.\n\n## Development\n\nTo set up the development environment and run tests, please refer to the instructions in `CONTRIBUTING.md`.\n\nAdditional docs:\n- `docs/INTERFACE.md`: Producer mirror of the chirality-app contract (app mode).\n- `GEMINI.md`: Guidance for using Gemini/AI assistants with this repo.\n - `CLAUDE.md`: Guidance for using Claude Code with this repo.\n - `AGENTS.md`: Notes for agentic coding assistants working on this project.\n",
"bugtrack_url": null,
"license": null,
"summary": "A semantic calculator for executing a canonical, multi-stage pipeline for structured problem-solving and knowledge generation.",
"version": "17.1.1",
"project_urls": {
"Documentation": "https://github.com/sgttomas/chirality-framework/blob/main/README.md",
"Homepage": "https://github.com/sgttomas/chirality-framework",
"Issues": "https://github.com/sgttomas/chirality-framework/issues",
"Repository": "https://github.com/sgttomas/chirality-framework.git"
},
"split_keywords": [
"llm",
" ontology",
" semantic computing",
" pipeline orchestration",
" static site generator",
" knowledge generation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e46b3b6ac244d18c10c2c227c862b30462dbbf39cd362b7328037c9aa5bdf1b0",
"md5": "c05d45ee8632265dca66cb7382dd6bde",
"sha256": "0264472a35e6da374542e3f31283b34698b4b79a7f103c5f77cb8e0c6bb3b834"
},
"downloads": -1,
"filename": "chirality_framework-17.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c05d45ee8632265dca66cb7382dd6bde",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 89463,
"upload_time": "2025-09-06T20:44:14",
"upload_time_iso_8601": "2025-09-06T20:44:14.105586Z",
"url": "https://files.pythonhosted.org/packages/e4/6b/3b6ac244d18c10c2c227c862b30462dbbf39cd362b7328037c9aa5bdf1b0/chirality_framework-17.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e60338dbbfaf9d26701a2c9273687a5e6fb42f2bb4624ff3deacdf70b70de034",
"md5": "09876f59361d63ae397afc9d83e0bc43",
"sha256": "4d3fd8e1b3d6e8297ca05ee4544d26508aba6983cbe36d7de645c46999ad49cd"
},
"downloads": -1,
"filename": "chirality_framework-17.1.1.tar.gz",
"has_sig": false,
"md5_digest": "09876f59361d63ae397afc9d83e0bc43",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 86442,
"upload_time": "2025-09-06T20:44:15",
"upload_time_iso_8601": "2025-09-06T20:44:15.836863Z",
"url": "https://files.pythonhosted.org/packages/e6/03/38dbbfaf9d26701a2c9273687a5e6fb42f2bb4624ff3deacdf70b70de034/chirality_framework-17.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 20:44:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sgttomas",
"github_project": "chirality-framework",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "neo4j",
"specs": [
[
">=",
"5.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "openai",
"specs": [
[
">=",
"1.50.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
}
],
"lcname": "chirality-framework"
}
JSON
