Skip to content

README.md

Latest commit

 

History

History
245 lines (184 loc) · 7.32 KB

README.md

File metadata and controls

245 lines (184 loc) · 7.32 KB
Raw

CellularAI

License: MIT Python 3.10+ Tests CI

A modular AI runtime where intelligence is split into replaceable, testable cells.

10-second explanation: CellularAI lets AI systems upgrade one part at a time instead of retraining or breaking the whole model.

Explain it like a Framework laptop

A normal LLM is like a sealed laptop. If one part needs an upgrade, you usually have to rebuild or retrain a huge system.

CellularAI is like a Framework laptop. The AI is split into replaceable cells. If the math cell is outdated, upgrade only the math cell. If the new math cell breaks old behavior, quarantine it and keep the old one.

That is the core idea: upgrade one cell, test it, promote it if safe, rollback if broken.

What This Project Is

CellularAI is not a production LLM and not a full transformer. It is a small research POC for safe AI upgrades, modular AI systems, and AI CI/CD.

Current LLM systems are mostly monolithic. Updating prompts, tools, memory, RAG data, or model versions can accidentally break old behavior. CellularAI explores a simpler pattern:

upgrade one cell -> run tests -> promote if safe -> quarantine if broken

Architecture

User Input
    ↓
RouterCell
    ↓
MemoryCell / MathCell / CodeCell / SafetyCell / VerifyCell
    ↓
CoordinatorCell
    ↓
Response

Each cell is like a replaceable laptop part:

  • MathCell: like swapping a faster chip for arithmetic.
  • MemoryCell: like replacing or expanding storage.
  • RouterCell: like the main board deciding where signals go.
  • SafetyCell: like a fuse that blocks risky output.
  • VerifyCell: like a diagnostic check before shipping the answer.

30-Second Demo

Run:

make build
make showcase

You should see:

  • Old MathCell v1 supports addition.
  • Multiplication fails.
  • New MathCell v2 is installed.
  • Tests pass.
  • MathCell v2 gets promoted.
  • Multiplication works.
  • MemoryCell v1 finds an exact fact query.
  • A paraphrased memory query fails.
  • MemoryCell v2 gets promoted.
  • The paraphrased query now retrieves the fact.
  • RouterCell v1 only partially routes a mixed code+math prompt.
  • RouterCell v2 routes that prompt to both CodeCell and MathCell.
  • VerifyCell v1 misses a bad multiplication answer.
  • VerifyCell v2 catches the bad answer.
  • SafetyCell v1 misses a dangerous command variant.
  • SafetyCell v2 blocks it.
  • Other cells stay unchanged during each upgrade.
  • Bad MathCell v3, bad MemoryCell v3, bad RouterCell v3, bad VerifyCell v3, and bad SafetyCell v3 get quarantined.

The showcase also writes:

  • reports/showcase_report.json
  • reports/showcase_report.md

Every report answers:

  1. What changed?
  2. What stayed the same?
  3. Did tests pass?
  4. Was the new cell promoted or quarantined?

Installation

For local development, no editable install is required. Use the repo-root launcher:

python3 -m venv .venv
source .venv/bin/activate
make build
pytest
./cellai --help

If the launcher is not available, this fallback also works:

python -m cellular_ai.cli --help

CLI Usage

Human-friendly output is the default for upgrade commands. Use --format json when you want automation-safe JSON.

./cellai ask "what is 3 + 4?"
./cellai memory add "Tangible Research mission is Make AI Tangible."
./cellai memory search "Tangible Research"
./cellai cells list
./cellai cells health
./cellai cells upgrade math --to v2
./cellai cells rollback math
./cellai cells mutate math --to v2 --examples examples/cell_training/math_multiply.jsonl
./cellai cells mutate math --to v3 --examples examples/cell_training/math_bad.jsonl
./cellai cells mutate memory --to v2 --examples examples/cell_training/memory_fuzzy.jsonl
./cellai cells mutate memory --to v3 --examples examples/cell_training/memory_bad.jsonl
./cellai cells mutate router --to v2 --examples examples/cell_training/router_mixed.jsonl
./cellai cells mutate router --to v3 --examples examples/cell_training/router_bad.jsonl
./cellai cells mutate verify --to v2 --examples examples/cell_training/verify_strict.jsonl
./cellai cells mutate verify --to v3 --examples examples/cell_training/verify_bad.jsonl
./cellai cells mutate safety --to v2 --examples examples/cell_training/safety_strict.jsonl
./cellai cells mutate safety --to v3 --examples examples/cell_training/safety_bad.jsonl
./cellai cells quarantine list
./cellai report --format json
./cellai report --format md --out reports/latest_report.md
./cellai eval
./cellai demo

Create a New Cell in Under 60 Seconds

CellularAI includes scaffolding for new cells. Think Framework laptop: snap in a new module, test it, then wire it into the organism.

Start a tiny organism:

./cellai init my-organism

Create a Python cell inside this repo:

./cellai cell create WeatherCell --type python
./cellai cell status WeatherCell
./cellai cell test WeatherCell
./cellai cell install WeatherCell
./cellai cell activate WeatherCell
./cellai cells list

Create a C-backed cell template:

./cellai cell create FastMathCell --type c

Then check what exists and run tests:

./cellai cells list
pytest
./cellai eval

Generated cells are marked as scaffolded until you wire them into the registry and add replay examples.

Cell lifecycle:

scaffolded -> tested -> installed -> active -> promoted/quarantined

Useful lifecycle commands:

./cellai cell status WeatherCell
./cellai cell test WeatherCell
./cellai cell install WeatherCell
./cellai cell activate WeatherCell
./cellai cell deactivate WeatherCell
./cellai cells list

Features

  • Cell Protocol
  • Cell Registry
  • Versioned cells
  • C-backed MathCell
  • JSONL MemoryCell
  • Memory retrieval upgrade from exact search to fuzzy search
  • Rule-based RouterCell
  • Router upgrade for mixed code+math and paraphrased knowledge prompts
  • Simple SafetyCell
  • Safety upgrade for stricter shell-command guardrails
  • Simple VerifyCell
  • Verify upgrade for stricter math and memory grounding checks
  • Cell upgrades
  • Regression tests
  • Quarantine for bad cells
  • Rollback support
  • Behavior diff reports
  • One-command showcase
  • GitHub Actions CI
  • ./cellai init and ./cellai cell create scaffolding

Research Roadmap

  • Phase 1: Toy cells and deterministic routing
  • Phase 2: Cell mutation and replay learning
  • Phase 3: Neural cells and embedding-based routing
  • Phase 4: Agent/tool cells
  • Phase 5: Dashboard and hosted evals
  • Phase 6: Paid cloud product

See ROADMAP.md.

Future Product Ideas

The MIT core stays free. A future paid product could add hosted dashboards, team workspaces, private cell registries, large-scale regression tests, audit logs, cloud evals, deployment monitoring, rollback history, and compliance reports.

These are future possibilities, not current paid features.

See BUSINESS.md.

Contributing

Contributions are welcome. Keep cells small, testable, versioned, and safe. New cells should include tests, health checks, and documentation.

See CONTRIBUTING.md.

License

MIT