Metadata-Version: 2.4
Name: cclab
Version: 0.3.47
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: pytest>=8.0.0 ; extra == 'comparison'
Requires-Dist: pytest-benchmark>=4.0.0 ; extra == 'comparison'
Requires-Dist: pytest-benchmark[histogram]>=4.0.0 ; extra == 'comparison'
Requires-Dist: maturin>=1.11.5 ; extra == 'dev'
Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
Requires-Dist: mypy>=1.8.0 ; extra == 'dev'
Requires-Dist: opentelemetry-api>=1.20.0 ; extra == 'observability'
Requires-Dist: opentelemetry-sdk>=1.20.0 ; extra == 'observability'
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0 ; extra == 'observability'
Provides-Extra: comparison
Provides-Extra: dev
Provides-Extra: mongodb
Provides-Extra: observability
Summary: High-performance Rust-powered Python platform: MongoDB/PostgreSQL ORM, HTTP client, task queue, KV store, and more
Keywords: rust,async,mongodb,postgres,orm,http,performance
Author-email: Chris Cheng <chris.cheng.c4@gmail.com>
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# 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

```python
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`

```bash
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 |

```bash
cclab server start --port 3456
```

Configure in Claude Code:
```json
{
  "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

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

Or clone and run locally:

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

## Development

```bash
# Build Python extension
maturin develop

# Run tests
cargo test
python -m pytest

# Build CLI
cargo build -p cclab-cli
```

## License

MIT

