1125 lines
54 KiB
JSON
1125 lines
54 KiB
JSON
{
|
|
"meta": {
|
|
"document_type": "Product Requirements Document",
|
|
"version": "1.0.0",
|
|
"project_codename": "SymClaw",
|
|
"tagline": "Open-Source Symbolic Computing for the Agentic Age",
|
|
"created": "2026-02-12",
|
|
"authors": ["Omar (Founder/CEO, HPC-AI Platform)"],
|
|
"status": "Draft — Architecture Review"
|
|
},
|
|
|
|
"executive_summary": {
|
|
"vision": "Build an open-source, high-performance symbolic mathematics engine in Rust that integrates with OpenClaw to deliver an AI-agentic, multi-channel scientific computing assistant — a Mathematica-class system that scientists can deploy on commodity hardware with one command.",
|
|
"problem_statement": [
|
|
"Mathematica is closed-source, expensive ($395/yr student, $2,495 perpetual), and locked to Wolfram's cloud.",
|
|
"Existing open-source CAS tools (SymPy, Maxima, SageMath) lack modern agentic AI integration and are not performance-optimized for edge/embedded deployment.",
|
|
"Scientists and researchers need a conversational, always-available math assistant that runs on their own infrastructure — from a Raspberry Pi cluster to a GPU workstation.",
|
|
"No existing system combines symbolic computing + equality saturation optimization + agentic AI routing + multi-channel delivery (WhatsApp, Telegram, iOS, web)."
|
|
],
|
|
"target_outcome": "A researcher messages 'derive the Navier-Stokes energy functional with respect to velocity field u' on Telegram and receives the symbolic result, LaTeX rendering, and an interactive parameter explorer pushed to their phone's Canvas — all computed on their own hardware."
|
|
},
|
|
|
|
"stakeholders": {
|
|
"primary_users": [
|
|
{
|
|
"persona": "Graduate Researcher (Physics/Math/Engineering)",
|
|
"pain_points": ["Can't afford Mathematica", "Needs CAS while away from desk", "Wants reproducible, version-controlled computations"],
|
|
"value_prop": "Free, self-hosted CAS accessible from any messaging app with persistent memory"
|
|
},
|
|
{
|
|
"persona": "Home Lab Hobbyist / Developer",
|
|
"pain_points": ["Wants to run compute on own hardware", "Interested in Rust/WASM performance", "Enjoys tinkering with infrastructure"],
|
|
"value_prop": "One-command deployment on Pi cluster with Tailscale remote access"
|
|
},
|
|
{
|
|
"persona": "Open Science Lab / University Group",
|
|
"pain_points": ["Budget constraints", "Need collaboration features", "Vendor lock-in concerns"],
|
|
"value_prop": "MIT-licensed, self-hosted, reproducible research infrastructure"
|
|
}
|
|
],
|
|
"secondary_users": [
|
|
"K-12 / undergraduate students learning calculus and algebra",
|
|
"Data scientists needing symbolic preprocessing before ML pipelines",
|
|
"Engineers doing control theory / signal processing work"
|
|
]
|
|
},
|
|
|
|
"architecture": {
|
|
"overview": "Three-layer architecture: Rust Symbolic Engine (compute) → OpenClaw Skill Bridge (agentic orchestration) → Multi-Channel Delivery (user surface)",
|
|
"layers": [
|
|
{
|
|
"name": "Layer 1: symclaw-core (Rust Crate)",
|
|
"responsibility": "Deterministic symbolic evaluation, simplification, differentiation, integration, linear algebra, and equation solving",
|
|
"technology": {
|
|
"language": "Rust (edition 2024)",
|
|
"key_crates": [
|
|
{"name": "egg", "version": "0.10+", "purpose": "E-graph equality saturation for optimal simplification"},
|
|
{"name": "proptest", "version": "1.x", "purpose": "Property-based testing for mathematical correctness"},
|
|
{"name": "serde", "version": "1.x", "purpose": "Serialization for AST interchange"},
|
|
{"name": "wasm-bindgen", "version": "0.2+", "purpose": "WASM compilation target for browser/mobile"},
|
|
{"name": "rayon", "version": "1.x", "purpose": "Data parallelism for cluster computation"},
|
|
{"name": "num", "version": "0.4+", "purpose": "Arbitrary precision arithmetic"},
|
|
{"name": "nalgebra", "version": "0.33+", "purpose": "Linear algebra operations"},
|
|
{"name": "latex-rs or custom", "version": "latest", "purpose": "LaTeX output rendering"}
|
|
],
|
|
"compile_targets": [
|
|
"x86_64-unknown-linux-gnu (primary — Pi cluster, servers)",
|
|
"aarch64-unknown-linux-gnu (Raspberry Pi 4/5 native)",
|
|
"wasm32-unknown-unknown (browser, OpenClaw Canvas)",
|
|
"x86_64-apple-darwin / aarch64-apple-darwin (macOS dev)"
|
|
]
|
|
},
|
|
"components": {
|
|
"ast": {
|
|
"description": "Core expression tree representation",
|
|
"design": {
|
|
"enum_name": "Expr",
|
|
"variants": [
|
|
"Num(Rational) — exact rational arithmetic",
|
|
"Float(f64) — IEEE 754 when exact isn't needed",
|
|
"Symbol(String) — named variables",
|
|
"Add(Vec<Arc<Expr>>) — n-ary addition (flattened)",
|
|
"Mul(Vec<Arc<Expr>>) — n-ary multiplication (flattened)",
|
|
"Pow(Arc<Expr>, Arc<Expr>) — exponentiation",
|
|
"Func(FuncName, Vec<Arc<Expr>>) — sin, cos, log, exp, etc.",
|
|
"Derivative(Arc<Expr>, Symbol, usize) — d^n/dx^n",
|
|
"Integral(Arc<Expr>, Symbol, Option<(Arc<Expr>, Arc<Expr>)>) — definite/indefinite",
|
|
"Matrix(Vec<Vec<Arc<Expr>>>) — symbolic matrices",
|
|
"Eq(Arc<Expr>, Arc<Expr>) — equations",
|
|
"Set(BTreeSet<Arc<Expr>>) — solution sets",
|
|
"Piecewise(Vec<(Arc<Expr>, Arc<Expr>)>) — conditional expressions",
|
|
"Sum(Arc<Expr>, Symbol, Arc<Expr>, Arc<Expr>) — sigma notation",
|
|
"Product(Arc<Expr>, Symbol, Arc<Expr>, Arc<Expr>) — pi notation",
|
|
"Limit(Arc<Expr>, Symbol, Arc<Expr>, LimitDirection) — limits",
|
|
"Tensor(TensorData) — future: tensor algebra"
|
|
],
|
|
"notes": [
|
|
"Use Arc<Expr> (not Box) for thread-safe sharing across rayon parallel iterators and cluster nodes",
|
|
"Implement Hash and Eq for expression deduplication / e-graph integration",
|
|
"Canonical ordering: sort commutative operands for deterministic comparison",
|
|
"Consider interning symbols via string interner crate for memory efficiency"
|
|
]
|
|
}
|
|
},
|
|
"rewriter": {
|
|
"description": "Rule-based symbolic transformation engine",
|
|
"subsystems": [
|
|
{
|
|
"name": "Pattern Matcher",
|
|
"approach": "Rust match arms + custom pattern DSL for rewrite rules",
|
|
"example_rules": [
|
|
"Derivative(Sin(x), x) → Cos(x)",
|
|
"Derivative(Cos(x), x) → Neg(Sin(x))",
|
|
"Derivative(Pow(x, Num(n)), x) → Mul(Num(n), Pow(x, Num(n-1)))",
|
|
"Derivative(Mul(f, g), x) → Add(Mul(Derivative(f, x), g), Mul(f, Derivative(g, x)))",
|
|
"Add(x, Num(0)) → x",
|
|
"Mul(x, Num(1)) → x",
|
|
"Mul(x, Num(0)) → Num(0)",
|
|
"Pow(x, Num(0)) → Num(1)",
|
|
"Pow(x, Num(1)) → x",
|
|
"Log(Exp(x)) → x",
|
|
"Exp(Log(x)) → x"
|
|
]
|
|
},
|
|
{
|
|
"name": "Equality Saturation Engine (egg integration)",
|
|
"approach": "Define Expr as an egg Language, run equality saturation with cost-based extraction",
|
|
"benefits": [
|
|
"Finds globally optimal simplification, not just greedy local rewrites",
|
|
"Handles commutative/associative rewriting without combinatorial explosion",
|
|
"Enables 'explain' mode — shows step-by-step derivation to user"
|
|
],
|
|
"implementation_notes": [
|
|
"Define custom CostFunction that prefers: constants > symbols > simple ops > complex ops",
|
|
"Implement ConstantFolding as an e-class Analysis",
|
|
"Set iteration limits and e-graph size limits to prevent runaway on complex expressions",
|
|
"Use egg's explain API to generate human-readable proof steps"
|
|
]
|
|
},
|
|
{
|
|
"name": "Simplifier",
|
|
"stages": [
|
|
"1. Flatten: Convert nested Add/Mul to n-ary form",
|
|
"2. Canonicalize: Sort operands, normalize signs",
|
|
"3. Fold Constants: Evaluate purely numeric subexpressions",
|
|
"4. Apply Algebraic Identities: trig, log, exponential identities",
|
|
"5. Equality Saturation: Run egg for global optimization",
|
|
"6. Extract: Pull out the lowest-cost equivalent expression"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
"solver": {
|
|
"description": "Equation solving and root finding",
|
|
"capabilities": [
|
|
"Polynomial root finding (quadratic formula, cubic/quartic via Cardano/Ferrari)",
|
|
"System of linear equations (Gaussian elimination on symbolic matrices)",
|
|
"Transcendental equation solving (Newton-Raphson with symbolic Jacobian)",
|
|
"Inequality solving and interval arithmetic",
|
|
"ODE solving (separable, linear first-order, second-order constant coefficient)"
|
|
]
|
|
},
|
|
"calculus": {
|
|
"description": "Differentiation, integration, limits, series",
|
|
"capabilities": [
|
|
"Symbolic differentiation (chain rule, product rule, quotient rule, implicit diff)",
|
|
"Symbolic integration (table lookup, substitution, integration by parts, partial fractions)",
|
|
"Taylor/Maclaurin series expansion",
|
|
"Limits (L'Hôpital's rule, squeeze theorem patterns)",
|
|
"Multivariate calculus (gradient, divergence, curl, Laplacian)"
|
|
]
|
|
},
|
|
"linear_algebra": {
|
|
"description": "Symbolic matrix operations",
|
|
"capabilities": [
|
|
"Determinant (Leibniz formula for small, LU for large)",
|
|
"Eigenvalue/eigenvector computation",
|
|
"Matrix inversion, transpose, trace",
|
|
"Characteristic polynomial",
|
|
"SVD (symbolic where tractable, numeric fallback)"
|
|
]
|
|
},
|
|
"output": {
|
|
"formats": [
|
|
{"name": "LaTeX", "purpose": "Rendering in Canvas, PDF generation, Jupyter"},
|
|
{"name": "MathML", "purpose": "Web accessibility, browser rendering"},
|
|
{"name": "ASCII", "purpose": "Terminal/CLI output, Telegram messages"},
|
|
{"name": "JSON AST", "purpose": "Programmatic consumption, inter-process"},
|
|
{"name": "Wolfram Language", "purpose": "Interop with existing Mathematica users (stretch goal)"},
|
|
{"name": "Python/SymPy", "purpose": "Export to Python ecosystem"}
|
|
]
|
|
},
|
|
"parser": {
|
|
"description": "Input expression parsing",
|
|
"formats": [
|
|
"Natural language (via LLM preprocessing in OpenClaw layer): 'derive x squared' → Derivative(Pow(x, 2), x)",
|
|
"Infix notation: 'd/dx(x^2 + 3*x)'",
|
|
"S-expression: (derivative (+ (pow x 2) (* 3 x)) x)",
|
|
"LaTeX input: '\\frac{d}{dx}(x^2 + 3x)'"
|
|
],
|
|
"implementation": "Use nom or pest crate for parser combinators"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"name": "Layer 2: symclaw-openclaw (OpenClaw Skill)",
|
|
"responsibility": "Bridge between the Rust engine and OpenClaw's agentic framework — NL intent parsing, tool invocation, visualization, and session management",
|
|
"technology": {
|
|
"runtime": "Node.js (OpenClaw host process) calling Rust engine via WASM or subprocess RPC",
|
|
"interop_options": [
|
|
{
|
|
"name": "WASM (preferred for single-node)",
|
|
"approach": "Compile symclaw-core to WASM, load via @aspect-build/aspect or wasm-pack, call from OpenClaw skill JS",
|
|
"pros": "Zero-copy, in-process, fast startup, works in browser Canvas",
|
|
"cons": "WASM limitations (no threads without SharedArrayBuffer, memory limits)"
|
|
},
|
|
{
|
|
"name": "Subprocess RPC (preferred for cluster)",
|
|
"approach": "Run symclaw-core as a native binary, communicate via JSON-RPC over stdin/stdout or Unix socket",
|
|
"pros": "Full Rust performance, threading, GPU access, can distribute across Pi cluster",
|
|
"cons": "IPC overhead, process management complexity"
|
|
},
|
|
{
|
|
"name": "HTTP Microservice (optional)",
|
|
"approach": "Run symclaw-core as an Axum/Actix web server, OpenClaw skill calls via HTTP",
|
|
"pros": "Language-agnostic, easy to scale, standard tooling",
|
|
"cons": "Network overhead, another process to manage"
|
|
}
|
|
]
|
|
},
|
|
"components": {
|
|
"skill_definition": {
|
|
"file": "SKILL.md",
|
|
"frontmatter": {
|
|
"name": "symclaw",
|
|
"description": "Symbolic mathematics engine — differentiation, integration, simplification, equation solving, plotting, and interactive parameter exploration",
|
|
"metadata": {
|
|
"openclaw": {
|
|
"requires": {
|
|
"bins": ["symclaw-engine"],
|
|
"env": [],
|
|
"config": []
|
|
},
|
|
"primaryEnv": null
|
|
}
|
|
}
|
|
},
|
|
"capabilities_exposed": [
|
|
"/math <expression> — Evaluate/simplify a mathematical expression",
|
|
"/derive <expr> wrt <var> — Symbolic differentiation",
|
|
"/integrate <expr> wrt <var> — Symbolic integration",
|
|
"/solve <equation> for <var> — Solve equations",
|
|
"/plot <expr> [range] — Generate plot and push to Canvas",
|
|
"/manipulate <expr> <params> — Interactive parameter exploration on Canvas",
|
|
"/latex <expr> — Render expression as LaTeX",
|
|
"/explain <expr> — Show step-by-step simplification with egg proofs",
|
|
"/matrix <operation> <data> — Matrix operations",
|
|
"/series <expr> about <point> order <n> — Taylor series expansion"
|
|
]
|
|
},
|
|
"tool_functions": [
|
|
{
|
|
"name": "math_eval",
|
|
"description": "Core evaluation — parse input, run through engine, return result + LaTeX",
|
|
"input": {"expression": "string", "output_format": "latex|ascii|json|mathml"},
|
|
"output": {"result": "string", "latex": "string", "steps": "string[]", "errors": "string[]"}
|
|
},
|
|
{
|
|
"name": "math_plot",
|
|
"description": "Generate plot data from symbolic expression",
|
|
"input": {"expression": "string", "variable": "string", "range": "[number, number]", "samples": "number"},
|
|
"output": {"plot_data": "{ x: number[], y: number[] }", "svg": "string", "canvas_html": "string"}
|
|
},
|
|
{
|
|
"name": "math_manipulate",
|
|
"description": "Push interactive parameter explorer to Canvas/mobile node",
|
|
"input": {"expression": "string", "parameters": [{"name": "string", "min": "number", "max": "number", "step": "number", "default": "number"}]},
|
|
"output": {"canvas_payload": "A2UI JSONL", "surface_id": "string"}
|
|
},
|
|
{
|
|
"name": "math_explain",
|
|
"description": "Show derivation steps using egg's explain API",
|
|
"input": {"expression": "string", "target": "string (optional — what to simplify to)"},
|
|
"output": {"steps": [{"rule": "string", "before": "string", "after": "string"}], "latex_steps": "string"}
|
|
}
|
|
],
|
|
"nlp_intent_mapping": {
|
|
"description": "Map natural language math requests to engine calls. OpenClaw's LLM handles this, but the SKILL.md provides structured examples.",
|
|
"examples": [
|
|
{"input": "What's the derivative of sin(x^2)?", "tool": "math_eval", "expression": "d/dx(sin(x^2))"},
|
|
{"input": "Simplify (x^2 - 1) / (x - 1)", "tool": "math_eval", "expression": "simplify((x^2 - 1) / (x - 1))"},
|
|
{"input": "Solve x^2 + 5x + 6 = 0", "tool": "math_eval", "expression": "solve(x^2 + 5*x + 6 = 0, x)"},
|
|
{"input": "Plot sin(x) from -pi to pi", "tool": "math_plot", "expression": "sin(x)", "range": [-3.14159, 3.14159]},
|
|
{"input": "Show me how x^3 - 3x^2 + 3x - 1 simplifies", "tool": "math_explain", "expression": "x^3 - 3*x^2 + 3*x - 1"},
|
|
{"input": "Let me explore how a affects a*sin(b*x)", "tool": "math_manipulate", "expression": "a*sin(b*x)"}
|
|
]
|
|
},
|
|
"canvas_integration": {
|
|
"description": "A2UI-based interactive math surfaces",
|
|
"surfaces": [
|
|
{
|
|
"name": "Scientist's Dashboard",
|
|
"components": [
|
|
"Expression input with LaTeX preview",
|
|
"Result display with step-by-step expansion",
|
|
"Interactive 2D/3D plot (using Plotly.js or D3 in Canvas)",
|
|
"Parameter sliders (Manipulate mode)",
|
|
"History sidebar with previous computations",
|
|
"Export buttons (PDF, LaTeX, Python)"
|
|
]
|
|
},
|
|
{
|
|
"name": "Manipulate Surface",
|
|
"components": [
|
|
"Dynamic sliders for each parameter",
|
|
"Real-time plot update as sliders move",
|
|
"Expression display showing current parameter values",
|
|
"Snapshot button to capture current state"
|
|
],
|
|
"implementation": "A2UI JSONL pushes Slider + Plot components; Canvas JS calls back to symclaw-core WASM for re-evaluation on slider change"
|
|
}
|
|
]
|
|
},
|
|
"session_management": {
|
|
"description": "Persist computation state across messages",
|
|
"approach": [
|
|
"Use OpenClaw's JSONL transcript for audit trail of all computations",
|
|
"Store named expressions in MEMORY.md: 'User defined f(x) = x^2 + 3x - 7'",
|
|
"Support 'assume' declarations: 'Assume x > 0' persists in session context",
|
|
"Variable bindings carry across messages within a session"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"name": "Layer 3: symclaw-infra (Deployment)",
|
|
"responsibility": "One-command deployment, cluster orchestration, remote access",
|
|
"components": {
|
|
"docker": {
|
|
"images": [
|
|
{
|
|
"name": "symclaw-engine",
|
|
"base": "rust:slim-bookworm (build) → debian:bookworm-slim (runtime)",
|
|
"contents": "Compiled symclaw-core binary + CLI",
|
|
"size_target": "< 50MB"
|
|
},
|
|
{
|
|
"name": "symclaw-gateway",
|
|
"base": "node:22-slim",
|
|
"contents": "OpenClaw Gateway + symclaw skill + WASM module",
|
|
"size_target": "< 200MB"
|
|
}
|
|
],
|
|
"compose": {
|
|
"services": {
|
|
"gateway": {
|
|
"image": "symclaw-gateway",
|
|
"ports": ["18789:18789"],
|
|
"volumes": ["~/.openclaw:/root/.openclaw", "~/.symclaw:/root/.symclaw"],
|
|
"environment": ["ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}"]
|
|
},
|
|
"engine": {
|
|
"image": "symclaw-engine",
|
|
"deploy": {
|
|
"replicas": "auto (matches available cores)",
|
|
"resources": {"limits": {"cpus": "4", "memory": "2G"}}
|
|
}
|
|
},
|
|
"webchat": {
|
|
"image": "symclaw-gateway",
|
|
"command": "openclaw webchat",
|
|
"ports": ["3000:3000"]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"nix": {
|
|
"flake": {
|
|
"inputs": ["nixpkgs", "rust-overlay", "flake-utils"],
|
|
"outputs": {
|
|
"packages": ["symclaw-core", "symclaw-cli", "symclaw-wasm"],
|
|
"devShells": ["Full development environment with Rust, Node, cargo-watch, wasm-pack"],
|
|
"nixosModules": ["systemd service for Gateway + Engine"]
|
|
}
|
|
},
|
|
"benefits": "Reproducible builds, declarative deployment, NixOS integration for Pi cluster"
|
|
},
|
|
"raspberry_pi_cluster": {
|
|
"topology": {
|
|
"control_node": "Pi 5 (8GB) — runs OpenClaw Gateway + Tailscale",
|
|
"compute_nodes": "Pi 4/5 (4-8GB each) — run symclaw-engine instances",
|
|
"networking": "Tailscale mesh or local VLAN",
|
|
"load_balancing": "Round-robin via OpenClaw multi-agent routing or custom dispatcher"
|
|
},
|
|
"deployment": {
|
|
"approach": "Nix flakes + deploy-rs for fleet management",
|
|
"one_command": "symclaw deploy --cluster [email protected].{10..14}"
|
|
},
|
|
"performance_notes": [
|
|
"Pi 5 ARM Cortex-A76 handles typical symbolic algebra in < 100ms",
|
|
"Equality saturation on complex expressions may need 2-5 seconds — use async/streaming response",
|
|
"For heavy computations, route to x86 workstation (RTX 5090 node) via Tailscale",
|
|
"WASM fallback allows computation in browser if all cluster nodes are busy"
|
|
]
|
|
},
|
|
"tailscale": {
|
|
"integration": "OpenClaw has built-in Tailscale Serve/Funnel support",
|
|
"modes": [
|
|
"Serve (tailnet-only): Access from any device on your Tailscale network",
|
|
"Funnel (public, auth-gated): Access from anywhere with password protection"
|
|
],
|
|
"use_cases": [
|
|
"Access 'Science Assistant' from phone while at conference",
|
|
"Share computation results with collaborator on same tailnet",
|
|
"Remote development — SSH into Pi cluster from anywhere"
|
|
]
|
|
},
|
|
"gpu_acceleration": {
|
|
"description": "Optional GPU offload for numeric-heavy operations",
|
|
"targets": [
|
|
"CUDA (RTX 5090 in Omar's homelab) — numeric linear algebra, ODE solvers",
|
|
"Vulkan compute (cross-platform fallback)",
|
|
"WebGPU (browser Canvas for client-side plotting)"
|
|
],
|
|
"integration": "Feature-gated in symclaw-core: cargo build --features cuda"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
|
|
"implementation_plan": {
|
|
"methodology": "Iterative development with 2-week sprints, each ending in a deployable artifact",
|
|
"phases": [
|
|
{
|
|
"phase": "Phase 0: Foundation",
|
|
"duration": "2 weeks",
|
|
"objective": "Project scaffolding, CI/CD, development environment",
|
|
"deliverables": [
|
|
{
|
|
"id": "P0.1",
|
|
"task": "Initialize Rust workspace with cargo workspaces",
|
|
"details": [
|
|
"Create workspace: symclaw/ with members: core/, cli/, wasm/, openclaw-skill/",
|
|
"Set up Cargo.toml with shared dependencies and feature flags",
|
|
"Configure clippy, rustfmt, deny.toml for lint/audit"
|
|
]
|
|
},
|
|
{
|
|
"id": "P0.2",
|
|
"task": "CI/CD pipeline",
|
|
"details": [
|
|
"GitHub Actions: test (x86 + aarch64 cross), clippy, fmt, build WASM, build Docker images",
|
|
"Nightly: property-based test suite with proptest (longer run times)",
|
|
"Release: cargo-dist for binary releases, wasm-pack publish, Docker Hub push"
|
|
]
|
|
},
|
|
{
|
|
"id": "P0.3",
|
|
"task": "Development environment",
|
|
"details": [
|
|
"Nix flake with devShell: Rust nightly, wasm-pack, Node 22, cargo-watch, mold linker",
|
|
"VS Code workspace with rust-analyzer, WASM debugging config",
|
|
".envrc for direnv integration"
|
|
]
|
|
},
|
|
{
|
|
"id": "P0.4",
|
|
"task": "Documentation skeleton",
|
|
"details": [
|
|
"mdBook setup for user-facing docs",
|
|
"Architecture Decision Records (ADR) directory",
|
|
"CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE (MIT + Apache 2.0 dual)"
|
|
]
|
|
}
|
|
],
|
|
"exit_criteria": "cargo test passes on x86 and aarch64, WASM builds, CI green"
|
|
},
|
|
{
|
|
"phase": "Phase 1: Engine Core — Arithmetic & Algebra",
|
|
"duration": "4 weeks (Sprints 1-2)",
|
|
"objective": "Core AST, parser, simplifier, and basic algebra",
|
|
"sprints": [
|
|
{
|
|
"sprint": "Sprint 1 (Weeks 3-4)",
|
|
"deliverables": [
|
|
{
|
|
"id": "P1.1",
|
|
"task": "Expr AST implementation",
|
|
"details": [
|
|
"Implement Expr enum with Num, Float, Symbol, Add, Mul, Pow, Func, Neg",
|
|
"Implement Display (pretty-print), Debug, Hash, Eq, PartialEq, Clone",
|
|
"Arc-wrapped recursive types with From/Into conversions for ergonomics",
|
|
"Canonical ordering for commutative operations"
|
|
],
|
|
"acceptance": "Can construct and display: 3*x^2 + 2*x - 7"
|
|
},
|
|
{
|
|
"id": "P1.2",
|
|
"task": "Parser (infix notation)",
|
|
"details": [
|
|
"Implement Pratt parser or use pest/nom for: numbers, symbols, +, -, *, /, ^, (, ), function calls",
|
|
"Operator precedence: ^(right-assoc) > unary- > */÷ > +-",
|
|
"Implicit multiplication: 2x, 3(x+1), xy",
|
|
"Built-in constants: pi, e, i"
|
|
],
|
|
"acceptance": "parse('3*x^2 + sin(2*pi*x) - 1/2') returns correct AST"
|
|
},
|
|
{
|
|
"id": "P1.3",
|
|
"task": "Constant folding & basic simplification",
|
|
"details": [
|
|
"Evaluate numeric subexpressions: 2 + 3 → 5, 6/4 → 3/2",
|
|
"Identity rules: x + 0, x * 1, x * 0, x^0, x^1",
|
|
"Flatten nested Add/Mul, combine like terms"
|
|
],
|
|
"acceptance": "simplify('x + 0 + 3 + 2') returns 'x + 5'"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"sprint": "Sprint 2 (Weeks 5-6)",
|
|
"deliverables": [
|
|
{
|
|
"id": "P1.4",
|
|
"task": "Egg integration — equality saturation simplifier",
|
|
"details": [
|
|
"Define Expr as egg::Language (implement Language trait)",
|
|
"Implement core rewrite rules as egg::Rewrite",
|
|
"Implement ConstantFolding analysis",
|
|
"Cost function: prefer fewer nodes, lower operation complexity",
|
|
"Runner with iteration limit (100) and node limit (10000)"
|
|
],
|
|
"acceptance": "egg simplifies (x^2 - 1)/(x - 1) to (x + 1)"
|
|
},
|
|
{
|
|
"id": "P1.5",
|
|
"task": "LaTeX output",
|
|
"details": [
|
|
"Implement to_latex() for all Expr variants",
|
|
"Proper fraction rendering: \\frac{a}{b}",
|
|
"Function rendering: \\sin, \\cos, \\ln, \\sqrt",
|
|
"Matrix rendering: \\begin{pmatrix}...\\end{pmatrix}"
|
|
],
|
|
"acceptance": "to_latex(Pow(x, Div(1, 2))) returns '\\sqrt{x}'"
|
|
},
|
|
{
|
|
"id": "P1.6",
|
|
"task": "CLI (symclaw-cli)",
|
|
"details": [
|
|
"REPL with readline support (rustyline)",
|
|
"Commands: simplify, eval, latex, quit",
|
|
"History, tab completion for functions",
|
|
"Pipe support: echo 'x^2 + 2*x + 1' | symclaw simplify"
|
|
],
|
|
"acceptance": "Interactive REPL that simplifies expressions and shows LaTeX"
|
|
},
|
|
{
|
|
"id": "P1.7",
|
|
"task": "Property-based test suite",
|
|
"details": [
|
|
"proptest strategies for generating random Expr trees",
|
|
"Invariant: simplify(e).eval(x=random) ≈ e.eval(x=random) for all x",
|
|
"Invariant: parse(display(e)) == e (round-trip)",
|
|
"Invariant: simplify(simplify(e)) == simplify(e) (idempotence)"
|
|
],
|
|
"acceptance": "1000+ property tests pass with no numerical drift > 1e-10"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"exit_criteria": "CLI can parse, simplify, and LaTeX-render polynomial and trigonometric expressions"
|
|
},
|
|
{
|
|
"phase": "Phase 2: Engine Core — Calculus & Solving",
|
|
"duration": "4 weeks (Sprints 3-4)",
|
|
"objective": "Differentiation, integration, equation solving, series",
|
|
"sprints": [
|
|
{
|
|
"sprint": "Sprint 3 (Weeks 7-8)",
|
|
"deliverables": [
|
|
{
|
|
"id": "P2.1",
|
|
"task": "Symbolic differentiation",
|
|
"details": [
|
|
"Power rule, constant rule, sum rule",
|
|
"Product rule, quotient rule, chain rule",
|
|
"Trig derivatives: sin, cos, tan, arcsin, arccos, arctan",
|
|
"Exponential/log derivatives",
|
|
"Higher-order derivatives: d^n/dx^n",
|
|
"Partial derivatives for multivariate expressions"
|
|
],
|
|
"acceptance": "d/dx(sin(x^2)) correctly returns 2*x*cos(x^2)"
|
|
},
|
|
{
|
|
"id": "P2.2",
|
|
"task": "Equation solver",
|
|
"details": [
|
|
"Linear equations: ax + b = 0",
|
|
"Quadratic formula: ax^2 + bx + c = 0 (exact roots, complex support)",
|
|
"Polynomial factoring (rational root theorem, synthetic division)",
|
|
"Systems of linear equations (symbolic Gaussian elimination)"
|
|
],
|
|
"acceptance": "solve(x^2 - 5*x + 6 = 0) returns {x = 2, x = 3}"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"sprint": "Sprint 4 (Weeks 9-10)",
|
|
"deliverables": [
|
|
{
|
|
"id": "P2.3",
|
|
"task": "Symbolic integration",
|
|
"details": [
|
|
"Power rule integration",
|
|
"Trig integrals (table lookup)",
|
|
"Substitution (u-sub with pattern matching)",
|
|
"Integration by parts (LIATE heuristic)",
|
|
"Partial fractions for rational functions",
|
|
"Definite integrals with limit evaluation"
|
|
],
|
|
"acceptance": "integrate(x*exp(x), x) returns x*exp(x) - exp(x) + C"
|
|
},
|
|
{
|
|
"id": "P2.4",
|
|
"task": "Series expansion",
|
|
"details": [
|
|
"Taylor series about a point",
|
|
"Maclaurin series (Taylor about 0)",
|
|
"Order control: expand to n terms",
|
|
"Remainder estimation"
|
|
],
|
|
"acceptance": "taylor(sin(x), x, 0, 5) returns x - x^3/6 + x^5/120"
|
|
},
|
|
{
|
|
"id": "P2.5",
|
|
"task": "Limits",
|
|
"details": [
|
|
"Direct substitution",
|
|
"L'Hôpital's rule for 0/0 and ∞/∞",
|
|
"One-sided limits",
|
|
"Limits at infinity"
|
|
],
|
|
"acceptance": "limit(sin(x)/x, x, 0) returns 1"
|
|
},
|
|
{
|
|
"id": "P2.6",
|
|
"task": "WASM compilation & test",
|
|
"details": [
|
|
"Ensure all Phase 1-2 code compiles to wasm32-unknown-unknown",
|
|
"wasm-bindgen exports for: parse, simplify, differentiate, integrate, solve, to_latex",
|
|
"Size budget: < 2MB gzipped WASM",
|
|
"Browser test harness with wasm-pack test --headless --chrome"
|
|
],
|
|
"acceptance": "WASM module loads in browser, solves quadratic equation in < 50ms"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"exit_criteria": "CLI handles calculus homework-level problems correctly; WASM compiles and runs in browser"
|
|
},
|
|
{
|
|
"phase": "Phase 3: OpenClaw Integration",
|
|
"duration": "3 weeks (Sprints 5-6)",
|
|
"objective": "Fully functional OpenClaw skill with Canvas visualization",
|
|
"sprints": [
|
|
{
|
|
"sprint": "Sprint 5 (Weeks 11-12)",
|
|
"deliverables": [
|
|
{
|
|
"id": "P3.1",
|
|
"task": "SKILL.md authoring",
|
|
"details": [
|
|
"Write comprehensive SKILL.md with YAML frontmatter",
|
|
"Document all commands with examples",
|
|
"Gate on symclaw-engine binary or WASM availability",
|
|
"Include install instructions in metadata.openclaw.requires"
|
|
],
|
|
"acceptance": "OpenClaw loads skill, shows /math in autocomplete"
|
|
},
|
|
{
|
|
"id": "P3.2",
|
|
"task": "Tool implementation (Node.js wrapper)",
|
|
"details": [
|
|
"Implement math_eval, math_plot, math_explain tool functions",
|
|
"WASM loading: dynamic import of symclaw.wasm",
|
|
"Subprocess fallback: spawn symclaw-cli with JSON I/O",
|
|
"Error handling: parse errors, computation timeouts, overflow",
|
|
"Streaming for long computations: send partial results"
|
|
],
|
|
"acceptance": "Telegram message 'derive sin(x^2)' returns '2x·cos(x²)' + LaTeX image"
|
|
},
|
|
{
|
|
"id": "P3.3",
|
|
"task": "LaTeX rendering to image",
|
|
"details": [
|
|
"Use MathJax or KaTeX server-side rendering to SVG/PNG",
|
|
"Embed in Telegram/WhatsApp messages as image attachment",
|
|
"Fallback: ASCII art for channels that don't support images"
|
|
],
|
|
"acceptance": "WhatsApp user sees beautifully rendered math formulas"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"sprint": "Sprint 6 (Week 13)",
|
|
"deliverables": [
|
|
{
|
|
"id": "P3.4",
|
|
"task": "Canvas — Scientist's Dashboard",
|
|
"details": [
|
|
"HTML/CSS/JS Canvas surface with: input field, result display, plot area",
|
|
"Plot rendering using Plotly.js or Chart.js loaded from CDN",
|
|
"LaTeX rendering in-browser via KaTeX",
|
|
"A2UI JSONL push for dynamic updates",
|
|
"Responsive layout for mobile (iOS/Android node Canvas)"
|
|
],
|
|
"acceptance": "User asks to plot sin(x); Canvas shows interactive plot on phone"
|
|
},
|
|
{
|
|
"id": "P3.5",
|
|
"task": "Canvas — Manipulate mode",
|
|
"details": [
|
|
"Parameter extraction from expression (detect free symbols not being plotted)",
|
|
"A2UI Slider components pushed to Canvas",
|
|
"Real-time re-evaluation: slider onChange triggers WASM recalculation in Canvas JS",
|
|
"Plot updates at 30fps as slider moves"
|
|
],
|
|
"acceptance": "User says 'manipulate a*sin(b*x)'; phone shows sliders for a, b with live plot"
|
|
},
|
|
{
|
|
"id": "P3.6",
|
|
"task": "Session memory integration",
|
|
"details": [
|
|
"Store defined functions in MEMORY.md: 'f(x) = x^2 + 3x - 7'",
|
|
"Recall across messages: 'now differentiate f'",
|
|
"Assumption tracking: 'assume x > 0' affects simplification",
|
|
"Computation history: 'show last 5 results'"
|
|
],
|
|
"acceptance": "Multi-turn conversation maintains mathematical context"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"exit_criteria": "End-to-end flow: Telegram → OpenClaw → Engine → Canvas works for calculus problems"
|
|
},
|
|
{
|
|
"phase": "Phase 4: Infrastructure & Deployment",
|
|
"duration": "2 weeks (Sprint 7)",
|
|
"objective": "One-command deployment, cluster support, Tailscale, CI/CD for releases",
|
|
"deliverables": [
|
|
{
|
|
"id": "P4.1",
|
|
"task": "Docker Compose stack",
|
|
"details": [
|
|
"Multi-stage Dockerfile for symclaw-engine (Rust build → slim runtime)",
|
|
"Dockerfile for symclaw-gateway (Node + OpenClaw + skill + WASM)",
|
|
"docker-compose.yml with engine, gateway, webchat services",
|
|
"Health checks, restart policies, resource limits",
|
|
"ARM64 multi-arch builds for Raspberry Pi"
|
|
],
|
|
"acceptance": "docker compose up -d brings full stack on x86 and ARM"
|
|
},
|
|
{
|
|
"id": "P4.2",
|
|
"task": "Nix flake",
|
|
"details": [
|
|
"flake.nix with packages, devShells, nixosModules",
|
|
"Cross-compilation to aarch64 via crane or naersk",
|
|
"NixOS module: services.symclaw.enable = true",
|
|
"Cachix binary cache for pre-built artifacts"
|
|
],
|
|
"acceptance": "nix run github:symclaw/symclaw starts the full stack"
|
|
},
|
|
{
|
|
"id": "P4.3",
|
|
"task": "Pi cluster deployment tooling",
|
|
"details": [
|
|
"Ansible or deploy-rs playbook for fleet deployment",
|
|
"Auto-discovery of compute nodes on local network",
|
|
"Load balancing: dispatch heavy computations to least-loaded node",
|
|
"Monitoring: Prometheus metrics from engine (eval latency, memory, e-graph size)"
|
|
],
|
|
"acceptance": "symclaw deploy --cluster deploys to 4 Pi nodes in < 5 minutes"
|
|
},
|
|
{
|
|
"id": "P4.4",
|
|
"task": "Tailscale integration",
|
|
"details": [
|
|
"Document OpenClaw's built-in Tailscale Serve/Funnel config",
|
|
"Provide symclaw-specific tailscale config snippet",
|
|
"Test: access from phone on different network"
|
|
],
|
|
"acceptance": "Access Scientist's Dashboard from phone on cellular while Gateway runs on home Pi"
|
|
},
|
|
{
|
|
"id": "P4.5",
|
|
"task": "openclaw onboard integration",
|
|
"details": [
|
|
"Publish symclaw skill to ClawHub",
|
|
"Support openclaw onboard wizard extension: auto-detect Rust toolchain, offer to install engine",
|
|
"One-command: openclaw skill install symclaw"
|
|
],
|
|
"acceptance": "New user can install and use SymClaw in < 10 minutes"
|
|
}
|
|
],
|
|
"exit_criteria": "One-command install works on macOS, Linux (x86 + ARM), and Docker"
|
|
},
|
|
{
|
|
"phase": "Phase 5: Polish, Testing & Alpha Release",
|
|
"duration": "3 weeks (Sprints 8-9)",
|
|
"objective": "Comprehensive testing, documentation, community prep, V0.1 Alpha release",
|
|
"deliverables": [
|
|
{
|
|
"id": "P5.1",
|
|
"task": "Comprehensive test suite",
|
|
"details": {
|
|
"unit_tests": [
|
|
"Every rewrite rule tested individually with known input/output",
|
|
"Parser round-trip: parse(display(parse(input))) == parse(input)",
|
|
"LaTeX output matches expected strings",
|
|
"Edge cases: division by zero, complex numbers, very large/small numbers"
|
|
],
|
|
"property_tests": [
|
|
"Simplification preserves numerical value (10,000+ random expressions)",
|
|
"Differentiation + integration round-trip: ∫(d/dx f(x))dx ≈ f(x) + C",
|
|
"Idempotence: simplify(simplify(e)) == simplify(e)",
|
|
"Commutativity: simplify(a + b) == simplify(b + a)"
|
|
],
|
|
"integration_tests": [
|
|
"OpenClaw message → engine → response pipeline",
|
|
"Telegram bot receives message, returns correct math",
|
|
"Canvas A2UI push renders correctly in browser test",
|
|
"Multi-turn session: define function, then differentiate it"
|
|
],
|
|
"stress_tests": [
|
|
"1000 concurrent evaluations on Pi cluster",
|
|
"E-graph explosion: expressions designed to stress equality saturation",
|
|
"WASM memory limits: expressions that approach 4GB boundary",
|
|
"Long-running integration: 24-hour continuous operation stability"
|
|
],
|
|
"benchmark_suite": [
|
|
"Compare simplification speed with SymPy on standard benchmark set",
|
|
"Measure e-graph size vs. simplification quality tradeoff",
|
|
"WASM vs. native performance comparison",
|
|
"Latency: message received → response sent (target: < 2 seconds for typical queries)"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"id": "P5.2",
|
|
"task": "Documentation",
|
|
"details": [
|
|
"mdBook user guide: Getting Started, Tutorials, API Reference",
|
|
"Architecture document with diagrams (Mermaid)",
|
|
"OpenClaw skill README with screenshots and GIFs",
|
|
"Video: 5-minute demo of end-to-end usage",
|
|
"Comparison table: SymClaw vs. Mathematica vs. SymPy vs. Maxima"
|
|
]
|
|
},
|
|
{
|
|
"id": "P5.3",
|
|
"task": "Community preparation",
|
|
"details": [
|
|
"GitHub repo setup: issue templates, PR template, labels, milestones",
|
|
"Discord server or Matrix room for community",
|
|
"CONTRIBUTING.md with 'good first issues' labeled",
|
|
"Blog post: 'Why We Built an Open-Source Mathematica in Rust'",
|
|
"Hacker News / Reddit launch post draft"
|
|
]
|
|
},
|
|
{
|
|
"id": "P5.4",
|
|
"task": "V0.1 Alpha release",
|
|
"details": [
|
|
"GitHub Release with changelog",
|
|
"crates.io publish: symclaw-core",
|
|
"npm publish: @symclaw/openclaw-skill",
|
|
"Docker Hub: symclaw/engine, symclaw/gateway",
|
|
"ClawHub: symclaw skill listing"
|
|
]
|
|
}
|
|
],
|
|
"exit_criteria": "V0.1 Alpha: installable, documented, tested, with known-issues list"
|
|
}
|
|
],
|
|
"future_phases": [
|
|
{
|
|
"phase": "Phase 6 (V0.5 Beta)",
|
|
"features": [
|
|
"Linear algebra module (eigenvalues, SVD, Jordan form)",
|
|
"ODE/PDE solvers",
|
|
"Number theory (prime factorization, modular arithmetic)",
|
|
"Graph theory / combinatorics module",
|
|
"Jupyter kernel (symclaw as Jupyter backend)",
|
|
"VS Code extension with inline LaTeX preview"
|
|
]
|
|
},
|
|
{
|
|
"phase": "Phase 7 (V1.0 Launch)",
|
|
"features": [
|
|
"GPU-accelerated numeric fallback (CUDA via RustyTorch integration)",
|
|
"Distributed computation across Clawbernetes cluster",
|
|
"Collaborative notebooks (multi-user Canvas sessions)",
|
|
"Wolfram Language import/export (migration path for Mathematica users)",
|
|
"Publication-ready PDF generation (LaTeX → PDF pipeline)",
|
|
"Integration with Omar's SLAI GPU scheduler for heavy workloads"
|
|
]
|
|
},
|
|
{
|
|
"phase": "Phase 8 (V2.0 — Science Platform)",
|
|
"features": [
|
|
"Domain-specific modules: Physics (units, kinematics), Chemistry (stoichiometry), Biology (population models)",
|
|
"ML integration: symbolic regression via RustyTorch",
|
|
"Natural language theorem proving",
|
|
"Real-time collaboration with CRDTs",
|
|
"Marketplace for community-contributed rule sets and problem libraries"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
|
|
"milestones": [
|
|
{
|
|
"version": "V0.1 Alpha",
|
|
"target_date": "Week 18 (T+18 weeks from start)",
|
|
"deliverables": "Core Rust library + CLI + OpenClaw skill + Docker deployment",
|
|
"audience": "Developers, Rust community, Home Lab hobbyists"
|
|
},
|
|
{
|
|
"version": "V0.5 Beta",
|
|
"target_date": "T+30 weeks",
|
|
"deliverables": "OpenClaw Skill + Canvas Dashboard + Manipulate + Pi cluster deployment",
|
|
"audience": "Early adopters, power users, math enthusiasts"
|
|
},
|
|
{
|
|
"version": "V1.0 Launch",
|
|
"target_date": "T+44 weeks",
|
|
"deliverables": "One-click install, comprehensive docs, GPU support, Jupyter integration",
|
|
"audience": "Universities, Open Science projects, research groups"
|
|
}
|
|
],
|
|
|
|
"risks_and_mitigations": [
|
|
{
|
|
"risk": "Symbolic integration is an unsolved problem — many integrals have no closed form",
|
|
"impact": "High",
|
|
"probability": "Certain",
|
|
"mitigation": "Implement Risch algorithm incrementally; provide numeric fallback with clear messaging; leverage LLM for heuristic suggestions; benchmark against SymPy's coverage as baseline"
|
|
},
|
|
{
|
|
"risk": "E-graph explosion on complex expressions leads to OOM or timeout",
|
|
"impact": "High",
|
|
"probability": "Medium",
|
|
"mitigation": "Strict iteration limits (100), node count limits (10K), time budgets (5s); fallback to greedy simplification; profile with dhat/heaptrack"
|
|
},
|
|
{
|
|
"risk": "WASM performance insufficient for real-time Manipulate sliders",
|
|
"impact": "Medium",
|
|
"probability": "Low",
|
|
"mitigation": "Pre-compile expression to fast numeric evaluator (JIT-like partial evaluation); cache WASM compilation; fall back to server-side evaluation with WebSocket streaming"
|
|
},
|
|
{
|
|
"risk": "OpenClaw API/skill format changes break integration",
|
|
"impact": "Medium",
|
|
"probability": "Medium",
|
|
"mitigation": "Pin to specific OpenClaw version; abstract skill interface behind adapter layer; maintain CI that tests against OpenClaw's latest"
|
|
},
|
|
{
|
|
"risk": "Security: malicious expressions cause DoS (infinite loops, memory exhaustion)",
|
|
"impact": "High",
|
|
"probability": "Medium",
|
|
"mitigation": "Sandboxed execution (Docker/WASM); expression complexity limits; timeout enforcement; OpenClaw's built-in sandboxing"
|
|
},
|
|
{
|
|
"risk": "Scope creep — trying to match Mathematica's 6,600 built-in functions",
|
|
"impact": "High",
|
|
"probability": "High",
|
|
"mitigation": "Ruthlessly prioritize: calculus + algebra + linear algebra cover 80% of use cases; accept 'not yet implemented' gracefully; extensible architecture allows community contributions"
|
|
},
|
|
{
|
|
"risk": "Low adoption due to SymPy's established ecosystem",
|
|
"impact": "Medium",
|
|
"probability": "Medium",
|
|
"mitigation": "Differentiate on: (1) performance (Rust >> Python), (2) agentic AI integration (unique), (3) edge deployment (WASM + Pi), (4) conversational interface (WhatsApp/Telegram)"
|
|
}
|
|
],
|
|
|
|
"success_metrics": {
|
|
"alpha": {
|
|
"correctness": "> 95% accuracy on MIT OCW calculus problem sets",
|
|
"performance": "< 100ms for typical simplification on Pi 5, < 50ms on x86",
|
|
"adoption": "100+ GitHub stars, 20+ alpha testers",
|
|
"reliability": "< 1% crash rate over 1000 random expressions"
|
|
},
|
|
"beta": {
|
|
"correctness": "> 98% accuracy on undergraduate math curriculum",
|
|
"performance": "< 2s end-to-end (message → rendered response) for 95th percentile",
|
|
"adoption": "1000+ GitHub stars, 5+ university pilot deployments",
|
|
"features": "Covers differential equations, linear algebra, series"
|
|
},
|
|
"launch": {
|
|
"correctness": "Parity with SymPy on core algebra/calculus; surpass on simplification quality (egg advantage)",
|
|
"performance": "10x faster than SymPy on benchmark suite",
|
|
"adoption": "5000+ GitHub stars, 50+ active contributors, 3+ university courses using SymClaw",
|
|
"ecosystem": "20+ community-contributed rule sets on ClawHub"
|
|
}
|
|
},
|
|
|
|
"competitive_landscape": {
|
|
"comparison": [
|
|
{
|
|
"product": "Wolfram Mathematica",
|
|
"strengths": "6,600 functions, 35+ years of development, Wolfram Alpha integration, professional support",
|
|
"weaknesses": "Closed source, expensive ($395-$2,495), cloud-dependent, no agentic AI integration",
|
|
"symclaw_advantage": "Open source, free, self-hosted, AI-native, runs on Pi"
|
|
},
|
|
{
|
|
"product": "SymPy (Python)",
|
|
"strengths": "Mature, large community, Jupyter integration, extensive documentation",
|
|
"weaknesses": "Python performance limitations, no agentic integration, no edge deployment",
|
|
"symclaw_advantage": "10x+ faster (Rust), WASM browser deployment, OpenClaw integration, equality saturation"
|
|
},
|
|
{
|
|
"product": "SageMath",
|
|
"strengths": "Comprehensive (wraps many backends), notebook interface",
|
|
"weaknesses": "Heavy installation (GB+), slow startup, no mobile/messaging support",
|
|
"symclaw_advantage": "Lightweight (< 50MB), instant startup, multi-channel (WhatsApp, Telegram, etc.)"
|
|
},
|
|
{
|
|
"product": "Maxima / GNU Octave",
|
|
"strengths": "Free, established, good for specific domains",
|
|
"weaknesses": "Dated interfaces, no modern AI integration, limited community growth",
|
|
"symclaw_advantage": "Modern Rust codebase, AI-agentic, active community model, Canvas visualization"
|
|
},
|
|
{
|
|
"product": "ChatGPT / Claude (direct LLM math)",
|
|
"strengths": "Natural language, accessible, broad knowledge",
|
|
"weaknesses": "Non-deterministic, hallucinations on complex math, no persistent state, no symbolic guarantees",
|
|
"symclaw_advantage": "Deterministic symbolic engine guarantees correctness; LLM handles NL intent, engine handles computation"
|
|
}
|
|
]
|
|
},
|
|
|
|
"technical_decisions": [
|
|
{
|
|
"decision": "ADR-001: Use Arc<Expr> over Box<Expr>",
|
|
"rationale": "Thread-safe sharing needed for rayon parallelism and potential cluster distribution. Arc's reference counting overhead is acceptable given the compute-heavy workload.",
|
|
"alternatives_considered": ["Box<Expr> (faster, single-threaded only)", "Rc<Expr> (no Send/Sync)"],
|
|
"status": "Accepted"
|
|
},
|
|
{
|
|
"decision": "ADR-002: Equality saturation via egg crate as primary simplifier",
|
|
"rationale": "E-graphs find globally optimal simplifications that greedy rewriting misses. The egg crate is production-proven (POPL 2021) and actively maintained.",
|
|
"alternatives_considered": ["Pure pattern-matching rewriter (simpler, but misses optimizations)", "Custom e-graph implementation (unnecessary when egg exists)"],
|
|
"status": "Accepted"
|
|
},
|
|
{
|
|
"decision": "ADR-003: WASM as primary OpenClaw integration, subprocess RPC as fallback",
|
|
"rationale": "WASM allows in-process execution without IPC overhead and enables browser Canvas computation. Subprocess fallback for when full Rust performance (threads, GPU) is needed.",
|
|
"alternatives_considered": ["HTTP microservice only (simpler, but adds network hop)", "FFI/NAPI (tighter coupling, platform-specific builds)"],
|
|
"status": "Accepted"
|
|
},
|
|
{
|
|
"decision": "ADR-004: Dual license MIT + Apache 2.0",
|
|
"rationale": "Maximum adoption: MIT for simplicity, Apache 2.0 for patent protection. Standard in Rust ecosystem.",
|
|
"alternatives_considered": ["GPL (copyleft would limit commercial adoption)", "MIT only (no patent protection)"],
|
|
"status": "Accepted"
|
|
},
|
|
{
|
|
"decision": "ADR-005: nom over pest for parser",
|
|
"rationale": "nom is more flexible for dynamic grammar extension (user-defined functions, custom notation), compiles to WASM cleanly, and integrates well with Rust's type system.",
|
|
"alternatives_considered": ["pest (PEG grammar, cleaner for static grammars)", "lalrpop (LR parser, overkill for math expressions)", "tree-sitter (focused on IDE use)"],
|
|
"status": "Proposed — evaluate during Sprint 1"
|
|
}
|
|
],
|
|
|
|
"integration_with_existing_stack": {
|
|
"description": "How SymClaw fits into Omar's existing HPC-AI platform ecosystem",
|
|
"connections": [
|
|
{
|
|
"project": "RustyTorch",
|
|
"integration": "Numeric fallback for expressions that can't be solved symbolically — evaluate numerically using RustyTorch tensors; symbolic regression (find symbolic formula from numeric data)",
|
|
"phase": "V1.0+"
|
|
},
|
|
{
|
|
"project": "SLAI (GPU Scheduler)",
|
|
"integration": "Route heavy symbolic computations (large e-graphs, numeric ODE solving) to GPU-equipped nodes via SLAI scheduling",
|
|
"phase": "V1.0+"
|
|
},
|
|
{
|
|
"project": "Clawbernetes",
|
|
"integration": "Deploy SymClaw engine as Clawbernetes workload; auto-scale compute pods based on query complexity; distribute e-graph computation across cluster",
|
|
"phase": "V1.0+"
|
|
},
|
|
{
|
|
"project": "StratoSwarm",
|
|
"integration": "SymClaw as a distributed service within StratoSwarm's agent mesh; cross-node computation routing",
|
|
"phase": "V2.0+"
|
|
},
|
|
{
|
|
"project": "OpenClaw Mission Control Dashboard",
|
|
"integration": "SymClaw metrics (eval latency, cache hit rate, e-graph stats) surfaced in Mission Control; computation history in dashboard",
|
|
"phase": "V0.5+"
|
|
}
|
|
]
|
|
},
|
|
|
|
"appendix": {
|
|
"reference_implementations": [
|
|
{"name": "egg math.rs test", "url": "https://github.com/egraphs-good/egg/blob/main/tests/math.rs", "relevance": "Starting point for defining math Language in egg"},
|
|
{"name": "SymPy", "url": "https://github.com/sympy/sympy", "relevance": "Feature parity target, test case source"},
|
|
{"name": "Symbolica", "url": "https://github.com/benruijl/symbolica", "relevance": "High-performance Rust CAS, architectural inspiration"},
|
|
{"name": "cas-rs", "url": "https://github.com/eliphatfs/cas-rs", "relevance": "Minimal Rust CAS, good reference for AST design"},
|
|
{"name": "OpenClaw SKILL.md spec", "url": "https://docs.openclaw.ai/tools/skills", "relevance": "Skill authoring format and requirements"}
|
|
],
|
|
"relevant_papers": [
|
|
"Willsey et al., 'egg: Fast and Extensible Equality Saturation', POPL 2021",
|
|
"Tate et al., 'Equality Saturation: A New Approach to Optimization', POPL 2009",
|
|
"Risch, 'The Solution of the Problem of Integration in Finite Terms', 1969",
|
|
"Moses, 'Symbolic Integration: The Stormy Decade', CACM 1971"
|
|
]
|
|
}
|
|
}
|