Cella 🧬

Cella is a deterministic, safety-first food intelligence core for households, community kitchens, and food-aware applications.

It evaluates spoilage risk, inventory context, planning constraints, and safe action signals with explainable rules that downstream apps must preserve.

Cella powers:

• sNAKr: shared household inventory, spoilage prevention, restock, and planning support.
• Takia: community kitchens, crisis readiness, surplus routing, and kitchen planning support.

---

📑 Table of Contents

• 👀 What Cella Does
• 📸 Product screenshots
• 📂 Project Structure
• 📦 Prerequisites
• 🚀 Quick Start
• 🧱 Tech Stack
• ✨ Features
• 📌 Project Status
• 📚 Documentation
• ⚖️ License

---

👀 What Cella Does

Cella turns food data into safer, smarter decisions.

Cella provides a rules-first intelligence layer for food systems that need to operate:

• Safely
• Clearly
• Calmly
• Under both everyday and crisis conditions

It focuses on spoilage risk, inventory awareness, and decision support without drifting into medical claims, diet advice, or autonomous decision-making.

---

📸 Product screenshots

Inventory assessment shows the full workbench flow: editable JSON input, deterministic risk signals, applied intelligence, restock guidance, and review-only safety boundaries.

Single-item assessment keeps SafeKeep reasoning visible, including risk level, storage context, rule basis, shelf-life window, and offline-safe resilience.

Invalid payloads fail safely with a clear error message, field-level context, and raw envelope inspection for downstream debugging.

---

📂 Project Structure

cella/
  apps/
    web/                 Next.js Cella Workbench
    mobile/              Planned Expo app workspace
  backend/
    examples/            Example Cella JSON payloads
    src/cella/           Python package and deterministic core
    tests/               Backend test suite
  docs/
    product/             Vision, roadmap, tone, and experience docs
    technical/           Contract, design, integration, tasks, and changelog
  scripts/               Setup, test, Docker, and example helpers
  environment.yml        Local conda/mamba environment
  pyproject.toml         Python package and test configuration

📦 Prerequisites

• Python 3.10+; the local environment file currently uses Python 3.12.
• mamba or conda for the recommended local backend environment.
• Node.js 22 for the web Workbench.
• Docker, optional, for reproducible backend CLI and test runs.

---

🚀 Quick Start

Set up the backend environment:

scripts/setup_env.sh

Run backend tests:

scripts/test_backend.sh

Assess the default example payload:

scripts/assess_example.sh

Run the local HTTP adapter:

PYTHONPATH=backend/src python -m cella serve --port 8765

Run the web Workbench in another terminal:

cd apps/web
npm install
npm run dev

Then open the local Workbench at http://localhost:3000.

---

🧱 Tech Stack

Backend:

• Python
• Deterministic rules and dataclass models
• JSON, CLI, and local HTTP adapter boundaries
• Pytest
• Optional Docker runtime

Web Workbench:

• Next.js
• TypeScript
• React
• shadcn/ui-style primitives
• Framer Motion
• Playwright

Future mobile:

• React Native
• Expo
• iOS and Android
• Cella read-only assessment display before writeback

---

✨ Features

• Deterministic item and inventory assessment.
• Shelf-life and storage-aware risk levels: LOW, MEDIUM, HIGH, and CRITICAL.
• Explainable SafeKeep reasons, factors, and rule IDs.
• Inventory signals for missing staples, low quantities, duplicates, use-first items, and review items.
• Applied intelligence for use-first summaries, kitchen priorities, restock signals, and routing hints.
• Planning and simulation for household planning, community supply-demand checks, demand spikes, and donation drops.
• Resilience metadata for degraded-mode gaps and low-connectivity use.
• Optional extended intelligence for non-medical food-group, usage-pattern, and waste-reduction summaries.
• Workbench UI for inspecting payloads and backend envelopes.
• Read-only sNAKr and Takia integration examples.
• Future visual-evidence metadata shape for camera, barcode, and IoT signals.

---

📌 Project Status

Cella has completed the backend and Workbench baselines through:

• Phase 1: Core deterministic intelligence.
• Phase 1.5: Repo, docs, payload validation, examples, SafeKeep audit, and HTTP adapter hardening.
• Phase 2: Workbench UI and applied intelligence.
• Phase 3: Planning and simulation.
• Phase 4: Resilience and accessibility.
• Phase 5: Optional extended intelligence.

Current milestone:

sNAKr and Takia can each call Cella once from real app data and display the result without changing its meaning.

See the roadmap and task board for the active implementation sequence.

---

📚 Documentation

• Docs map
• Vision
• Roadmap
• Tone guidelines
• Experience guidelines
• System contract
• System design
• Requirements
• Integration guide
• SafeKeep rule audit
• Deployment
• Task board
• Changelog
• Backend README
• Web README
• Mobile README
• Contributing

---

⚖️ License

Cella is released under the MIT License.

---

Built with 💖 for households, kitchens, and communities working to waste less and care better.