cclab 0.1.0

High-performance Rust-powered Python platform: MongoDB/PostgreSQL ORM, HTTP client, task queue, KV store, and more

cclab (Chris Cheng Lab)

High-performance platform built in Rust: a Python compiler (Mamba), a full-stack Python library suite (cclab.*), developer tools (CLI/MCP), and specialized domain engines.

Mamba — Force-Typed Python Compiler

Mamba is a force-typed Python compiler that compiles Python-like source code to native machine code via Cranelift. It is NOT a transpiler or interpreter — it produces real binaries.

Compiler pipeline:

Source → Lexer (logos) → Parser → Name Resolution → Type Inference → HIR → MIR → Codegen (Cranelift) → Native Binary

Stage	Description
lexer	Token generation via logos DFA
parser	AST construction
resolve	Name resolution and scope analysis
types	Force-typed type inference and checking
hir	High-level intermediate representation
mir	Mid-level IR for optimization
codegen	Native code generation via Cranelift JIT/AOT
runtime	Minimal runtime support
ffi	Foreign function interface for C interop
config	Project configuration (.mamba.toml)
diagnostic	Error reporting with source spans

Crate: crates/cclab-mamba

---

Python Libraries (cclab.*)

Rust-powered Python libraries exposed via PyO3. Zero runtime dependencies — all functionality is compiled Rust. Install with pip install cclab.

All sub-crate bindings are aggregated through cclab and feature-gated for selective compilation.

Web & API

Module	Purpose	Replaces	Status
schema	Data validation, schema, type coercion	Pydantic + orjson	✅ 95%
api	REST API framework, routing, middleware	uvicorn + FastAPI	✅ 95%
http	HTTP client, connection pooling	httpx	✅ 95%
fetch	Async HTTP client, latency tracking	httpx	✅ 95%
crypto	Hashing, encryption, JWT, TOTP, passwords	cryptography, PyJWT, bcrypt	✅ 90%

Database & Storage

Module	Purpose	Replaces	Status
pg	PostgreSQL ORM, migrations	asyncpg + SQLAlchemy	✅ 95%
mongo	MongoDB thin wrapper	pymongo	✅ 95%
kv	In-memory + disk tiered KV store	(unique)	✅ 95%
hive	Hive/Presto client, connection pooling	PyHive	✅ 95%

Async & Distributed

Module	Purpose	Replaces	Status
runtime	Tokio-backed asyncio event loop	uvloop	✅ 95%
queue	Distributed task queue (NATS/Redis/GCP)	Celery	✅ 95%
agent	Opinionated LLM agent framework (see below)	LangChain, PydanticAI, CrewAI	✅ 95%

Data Science

Module	Purpose	Replaces	Status
array	N-dimensional arrays	NumPy	✅ 95%
frame	DataFrame and Series	pandas	✅ 95%
sci	Stats, FFT, signal, interpolation, optimization	SciPy	✅ 95%
learn	Machine learning and deep learning	scikit-learn, PyTorch	✅ 90%
plot	Data visualization, SVG export	Matplotlib	✅ 85%
media	Image, video, and PDF processing	OpenCV, Pillow	✅ 90%
text	Text segmentation, search ranking, HTML/XML	jieba, rank-bm25, lxml	✅ 95%

Developer Utilities

Module	Purpose	Replaces	Status
log	Structured logging, async I/O, rotation	loguru	✅ 95%
tqdm	Progress bars, GIL-free rendering	tqdm	✅ 95%
typer	CLI framework backed by clap	typer	✅ 95%
cmd	CLI framework, decorator-based	typer/click	✅ 95%
util	Humanize, iteration utilities, LRU cache	humanize, more-itertools	✅ 95%

Testing

Module	Purpose	Replaces	Status
qc	Test discovery, parallel execution	pytest	✅ 95%

Quick Example

from cclab.schema import BaseModel
from cclab.api import App
from cclab.pg import Database
from cclab.agent import Agent

# Validation
class User(BaseModel):
    email: str
    name: str

# API
app = App()

@app.get("/users/{id}")
async def get_user(id: str) -> User:
    return await db.query_one(User, id=id)

# Database
db = Database("postgresql://localhost/mydb")
await db.connect()

# AI Agent
agent = Agent(model="claude-3-5-sonnet")
response = await agent.run("Summarize this document")

Data Flow

HTTP Request → api → schema (validate) → pg/mongo (DB) → schema (serialize) → Response

schema is the single source of truth for validation. ORMs trust validated data.

cclab.agent — Opinionated Agent Framework

Not just an engine — a framework with SDD best practices baked in.

Engine (generic):

Component	Description
LLM Providers	Claude, OpenAI, Gemini via unified LLMProvider trait
Tool System	ToolRegistry + ToolExecutor (validation, timeout, retry)
Context	Token counting (tiktoken BPE), smart auto-compact
Structured Output	JSON Schema enforced via complete_structured()
Streaming	StreamHandler + StreamEvent for real-time feedback
Integrations	GitHub, GitLab, Jira (issues, files, MR/PR, comments)

Opinionated Agents (SDD-informed):

Agent	Input → Output	Review
RestructureIssueAgent	Vague intent → structured issues	Human (Q&A)
ReferenceContextAgent	Issues → relevant spec context	CRR (auto)
ChangeSpecAgent	Issues + context → formal specs	CRR (auto)
ChangeImplAgent	Specs → code + PR/MR	CRR (auto)
ReviewAgent	Artifact → verdict (Approved/NeedsRevision/Rejected)	—
CRRCycle	Generic Create-Review-Revise orchestrator	—

cclab-sdd vs cclab-agent — same spec-driven philosophy, different design:

	cclab-sdd (local CLI)	cclab-agent (cloud)
Runs on	Developer's machine	Cloud server
Agents	CLI subprocess (gemini/codex/claude)	In-process LLMProvider API
State	STATE.yaml	Database
User interaction	Interactive terminal	Issue comments (async)
SDD phases	8 fine-grained phases	4 agents (merged phases)

Phases merge because cloud is async — no "restructure then clarify" boundary. The agent reads the issue, decides if info is sufficient, asks if not. One loop, not two steps.

SDD (8 phases)                    Agent (4 agents)
──────────────                    ────────────────
2. restructure input  ─┐
3. pre-clarification  ─┘────→    RestructureIssueAgent
4. reference-context  ─┐
5. post-clarification ─┘────→    ReferenceContextAgent
6. change spec        ──────→    ChangeSpecAgent + CRR
7. change impl        ──────→    ChangeImplAgent + CRR

---

Developer Tools (Rust CLI/MCP)

Command-line tools and MCP server. NOT exposed to Python.

Module	Purpose	Status
cli	Unified CLI (cclab command), routes to subcommands	✅ 90%
server	MCP server — HTTP endpoint for MCP tools + dashboard	✅ 75%
sdd	SDD orchestrator + spec generation (Plan → Implement → Archive)	⚠️ 70%
lens	Code analysis — LSP, linting, type checking (multi-lang)	⚠️ 60%

Dependency flow: sdd ← lens ← server ← cli

cclab --help              # Show all commands
cclab api serve           # Start API server
cclab pg migrate          # Run database migrations
cclab qc run              # Run tests
cclab server start        # Start MCP server
cclab gen plan-change     # Start SDD workflow
cclab lens check         # Run code analysis

MCP Server

47 tools organized by category:

Category	Tools	Description
SDD	33	Workflow, specs, knowledge base, diagrams, API specs
Lens Analysis	9	Types, symbols, diagnostics, references
Lens Advanced	5	State machines, code-to-diagram

cclab server start --port 3456

Configure in Claude Code:

{
  "mcpServers": {
    "cclab": { "url": "http://localhost:3456/mcp" }
  }
}

---

Specialized Domains (TypeScript/WASM)

Standalone products with Rust core and TypeScript/WASM bindings.

Grid (Spreadsheet Engine) — ✅ 95%

Module	Purpose
grid-core	Cell storage, ranges, formatting
grid-formula	Excel-compatible formula parsing and evaluation
grid-db	Save/load spreadsheets
grid-history	Undo/Redo with efficient change diffing
grid-server	Real-time collaboration sync with CRDT
grid-wasm	WebAssembly browser bindings

Replaces: SheetJS, Handsontable

Jet (Build Tool + Package Manager) — ✅ 80%

Single-crate architecture (cclab-jet):

Module	Purpose
bundler	Dependency graph, __jet__ runtime, single-file bundle
transform	JSX/TSX (Tree-sitter), TypeScript type stripping
resolver	Node.js module resolution with exports field
asset	Images, fonts, CSS processing
dev_server	Axum HTTP, /__jet_hmr WebSocket, file watching
pkg_manager	Parallel npm install, ~/.jet-store/, jet-lock.yaml v2, peer deps, bin scripts, lifecycle hooks, shasum verification

Replaces: Vite, Webpack, pnpm, npm

---

Foundation

Module	Purpose
core	Shared types, errors, traits — no business logic, no external deps

---

Install

curl -fsSL https://raw.githubusercontent.com/chrischeng-c4/cclab/main/install.sh | bash

Or clone and run locally:

git clone https://github.com/chrischeng-c4/cclab.git
cd cclab
./install.sh

Development

# Build Python extension
maturin develop

# Run tests
cargo test
python -m pytest

# Build CLI
cargo build -p cclab-cli

License

MIT