README.md

Calc Flow documentation

This directory holds Calc Flow's published documentation and point-in-time engineering records. The current-state guides linked under Start here always reflect the latest state of the project on main; overwrite them in place when the code changes rather than maintaining per-release copies. Fundamental changes are recorded in the existing repo-root CHANGELOG.md, and the v1-to-v2 migration boundary is preserved in the historical records listed below.

Start here

• Getting started — published-package and from-source installation, Studio startup, and an install smoke test
• Executable examples — complete Python/Rust inventory, one-command runner, expected behavior, and choosing an example to copy
• Introduction — architecture, data contract, graph compilation, table execution, optional array providers, and recovery
• Design and architecture — component ownership, batch and streaming data paths, checkpoint transactions, extension and security boundaries
• Continuous streaming guide — sources, cursors, watermarks, windows, sinks, delivery, checkpoints, recovery, and operations
• Stream message envelope — the v3 stream message contract: typed messages, event-time progress, windows, state manifests and backends, the operator emission boundary, and current delivery guarantees
• Connectors and stream projects — exact connector identities, delivery limits, project fragments, windows, and recovery
• Python API guide — PipelineBuilder, batches, UDFs, async execution, NumPy/JAX, symbolic declarations and static analysis, projects, and runners
• Symbolic workflows — composed financial features, batch/continuous execution, checkpoint recovery, static NumPy/JAX matrices, capability failures, Studio inspection, and performance output
• Rust API guide — native batches, operators, graph compiler, UDF/provider registries, and recovery, with paired examples
• API reference — the supported surfaces at a glance: Rust exports, Python members, and the Studio HTTP API
• Python release guide — local packaging rehearsal, artifact matrix verification, Trusted Publishers, and the PyPI procedure

Project orientation

• Repository README — workspace entry point, quick starts, architecture map, and examples
• AGENTS.md — the authoritative agent guide: commands, coding style, architecture summary, test layout, and release invariants
• CLAUDE.md — Claude Code operational guidance, kept in step with AGENTS.md
• Codex agent team — Codex-native roster, workflow, artifact layout, and invocation examples
• Claude agent team — preserved Claude compatibility roster and workflow
• Examples — executable v3 Python examples
• Rust examples — executable calc-flow crate examples
• Benchmarks — informational benchmark harness
• Streaming engine research — point-in-time Arroyo/RisingWave architecture research and Calc-Flow continuous-runtime recommendations
• Symbolic computation engine design — point-in-time Python symbolic IR, batch/stream lowering, and native operator design, paired with its phased implementation plan. The immutable declaration and static-analysis layer is available today; see the Python API guide
• Project schema — the canonical generated v3 project contract
• Studio README — the local calc-flow-studio application

Historical records

These files are release history, not normative docs. They describe older surfaces and are preserved for audit; leave them untouched. The current (normative) docs above always override them.

• v2 release guide — the v1-to-v2 migration boundary, package versions, upgrade checklist, and release artifacts. This is the pointer for anyone moving from frozen Python v1 to Rust-native v2.
• v1 final API — the final Python v1 API reference. The frozen v1 implementation is preserved in commit c87324e.
• v0.2 migration — the v0.1-to-v0.2 prototype migration, predating v1.
• Engineering records — dated design notes, implementation plans, specifications, and hand-offs. These preserve the decisions and execution state at the time they were written; they are not current API or operational guidance.

Immutable v1 semantic fixtures live under tests/fixtures/v1/ as historical parity evidence; they are not a v2 runtime or package path.

Conventions

All documentation uses GitHub-flavored Markdown: inline code with backticks, file paths relative to the document, and cross-references as relative links. Align table columns with pipes and pad separator rows so their dashes span the full column width. Docs describe what exists, not the design history that led there; cite the type, function, or file name rather than source line numbers.