Getting Started & Installation
Relevant source files
The following files were used as context for generating this wiki page:
- CONTRIBUTING.md
- AGENTS.md
- openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/documentation-site/spec.md
- openspec/changes/archive/2026-05-15-rebuild-website-astro/tasks.md
- openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md
- openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/website-platform/spec.md
DeepCausality is a Rust-based monorepo designed for computational causality, enabling fast, context-aware causal reasoning over complex multi-stage models. The project recently underwent a transition to a "dynamic causality" framing, moving away from its legacy "hypergeometric computational causality" label to better reflect its application in advanced, dynamic systems.
Sources: AGENTS.md:120-125, openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md:10-15
Getting started involves setting up the Rust development environment for the core library crates or, for web-facing components, initializing the Astro-based documentation and marketing platform. The framework is structured into 20 library crates covering core logic, data structures, algorithms, and specialized physics/topology modules.
Sources: AGENTS.md:135-155, openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/website-platform/spec.md:5-10
Development Environment Setup
Prerequisites
Before contributing or using DeepCausality, ensure you have the following installed:
- Rust Toolchain: version 1.75 or higher (required for HKT and other functional features).
- Make: Used to simplify common development tasks.
- pnpm: Required for building the website and documentation platform.
- Node.js: Required for the Astro-based web components.
Sources: AGENTS.md:160-170, openspec/changes/archive/2026-05-15-rebuild-website-astro/tasks.md:15-20, openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md:30
Build Commands
The project utilizes a makefile in the root directory to standardize the build and test process across the monorepo.
| Command | Description |
|---|---|
make build | Builds the entire monorepo. |
make test | Runs tests for the entire monorepo (resource intensive). |
make fix | Fixes linting issues using clippy. |
make format | Formats all code according to cargo fmt. |
make check | Checks for security vulnerabilities. |
Sources: AGENTS.md:162-171
Project Structure & Crate Organization
DeepCausality is organized as a monorepo containing 20 library crates categorized by their functional domain. When starting development, it is preferred to build and test specific crates rather than the entire monorepo.
The diagram above shows the high-level organization of the monorepo's 20 crates.
Sources: AGENTS.md:135-158
Standard Module Layout
Each crate adheres to a strict internal structure to maintain consistency:
src/errors/mod.rs: Individual error types.src/traits/mod.rs: Trait definitions.src/types/mod.rs: Core type definitions.tests/: Replicates thesrcfolder structure for unit and integration tests.
Sources: AGENTS.md:188-215
Website & Documentation Platform
The documentation and landing page are built using Astro 6.3.2 and are located in the website/web/ directory. This sub-project is self-contained and operates independently of the Rust Cargo workspace.
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/tasks.md:15-18, openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/website-platform/spec.md:5-12
Installation and Build
To set up the web environment:
- Navigate to the web directory:
cd website/web/ - Install dependencies:
pnpm install - Build the static site:
pnpm build
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/tasks.md:25-27, openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/website-platform/spec.md:15-18
Documentation Sections
The documentation is organized into the following top-level sections:
getting-started: Installation guides and "Hello Causaloid" examples.concepts: In-depth explanations of the Causal Monad, HKT, and CDL.guides: End-to-end pipeline walkthroughs.reference: Per-crate summaries and links to docs.rs.monograph: Digital versions of the EPP (Effect Propagation Process) preprints.
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/documentation-site/spec.md:5-20, openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md:130-140
Contributing Guidelines
The project follows a "spec-driven development" workflow. New features must be proposed via a specification before implementation begins.
The sequence above illustrates the workflow for introducing new features into the codebase.
Sources: openspec/changes/archive/spec-kit-old/README_OLD.md:35-50
Critical Constraints
- No Unsafe: The use of
unsafecode is strictly prohibited across all crates. - No Direct Commits: AI agents are forbidden from performing
git commitdirectly. - Static Dispatch: Prefer static dispatch over dynamic dispatch (
dyn) to ensure zero-cost abstractions. - Test Coverage: Maintain a code coverage rate between 95% and 97%.
Sources: AGENTS.md:25-35, AGENTS.md:250-265, openspec/changes/archive/spec-kit-old/README_OLD.md:85-90
Summary
Getting started with DeepCausality requires configuring a Rust environment for library development and a Node.js/pnpm environment for the documentation platform. By following the standardized make commands and adhering to the spec-driven development process, developers can contribute to a framework focused on high-performance, verifiable dynamic causality.
Sources: AGENTS.md:162-171, openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/website-platform/spec.md:15-20