How darkshapes/zodiac works
Project type and purpose
• Zodiac is a local-first, privacy-oriented Python application that runs on CLI, TUI, smartphone and browser environments. Its goal is to let artists and researchers visually compose and execute generative-AI “action chains” without writing code.
High-level architecture from the file tree and README
• Two main Python packages:
• astra/ – a lightweight theming & widget CSS (TUI/CSS) library (.tcss) plus entrypoint.
• zodiac/ – the core app: UI screens (main_screen.py), widget modules (carousel.py, flip.py, display_bar.py, etc.), a graph-based workflow engine (graph.py, combo.tcss), and a model-registry for plugging in local LLM runtimes.
• No external server or datastore; everything runs locally and interacts with local model runtimes (Ollama, VLLM, LMStudio, etc.) via plugin connectors.
Main components
A. UI Layer (frontend)
• CLI / Terminal UI with astra theming (astra/__main__.py + .tcss)
• Smartphone UI (same codebase, adaptive TUI/CSS)
• Browser UI (served locally by the app if used in web mode)
B. Core Engine (backend)
1. Workflow Manager – constructs and sequences action chains
2. Graph Manager – maintains the directed graph data structure (zodiac/graph.py)
3. Model Registry – discovers and registers local model providers (zodiac/token_counters.py, model_register tests)
4. Widget Manager – mounts and lays out widgets (carousel, flip, panels) via astra
C. Plugin Connectors (local services)
• Ollama, Llamafile, VLLM, LMStudio, etc. – each accessed through a small adapter layer in zodiac/
D. Local File System
• Configuration files (pyproject.toml, .python-version)
• Optional workflow persistence (if extended)
E. Tests & CI
• pytest suite (tests/)
• GitHub Actions (python-app.yml)
Relationships and data flows
1. User → UI Layer: enters text/audio/files.
2. UI → Core Engine: user commands invoke the Workflow Manager.
3. Workflow Manager ↔ Graph Manager: build or modify the node/edge graph.
4. Core Engine → Model Registry: find the right local model adapter.
5. Core Engine → Plugin Connector → Local Model Runtime: send prompts, receive results.
6. Core Engine → Widget Manager → UI: render outputs to screen.
7. Optionally Core Engine → File System: read/write workflow definitions or caches.
Architectural patterns & design principles
• MVC-style separation: UI layer (View) is decoupled from business logic (Controller = Core Engine) and data (Model = Graph Manager + Model Registry).
• Plugin-based extensibility: new local model runtimes or UI widgets can be dropped in without touching core.
• Graph data structure for workflow orchestration (adds/removes nodes & edges at runtime).
• Theming layer (astra) isolates CSS/TUI styling from widget implementations.