telo 🎨

telo is your design partner that never runs out of ideas—or ways to improve them. Built with LlamaIndex Workflows, it provides a sophisticated agentic system that deeply analyzes design screenshots, extracts real content, and generates syntactically-validated code alternatives.

🚀 Key Features

• Focused Refinement: Target a specific design iteration for precision feedback. Simply click "Refine this" to start a dedicated conversation on that specific version.
• Deep Visual Analysis: Beyond simple critique, telo analyzes page relationships, component structures, and information flow.
• Intent-Driven Workflow: Automatically detects if you want a complete redesign or iterative refinements.
• Real-Time Streaming: Watch the AI's reasoning and code generation unfold live with Server-Sent Events (SSE) streaming.
• Zero-Placeholder Policy: Automatically extracts all visible text, labels, and data from your images so the generated code uses real content instead of "Lorem Ipsum".
• Agentic Reflection & Self-Fixing: Includes a built-in compiler check. If the LLM generates buggy code, the agent sees the actual compiler error and fixes itself before delivery (up to 3 retries).
• Parallel Generation: Generates multiple design concepts concurrently using a fan-out/fan-in architecture.
• Comprehensive Traceability: Detailed reasoning logs for every step, including LLM prompts, extraction data, and compiler feedback.

🧠 The Agentic Workflow

telo uses a sophisticated Branching Architecture event-driven LlamaIndex Workflow. It intelligently routes request to specialized sub-agents based on user intent.

graph TD
    Start[Start Event] --> Analysis[Step 1: Intent Analysis]
    
    Analysis -->|Intent: REFINE| RefineBranch[Refinement Branch]
    Analysis -->|Intent: REDESIGN| CreativeBranch[Creative Branch]
    
    subgraph Refinement Branch
    RefineBranch --> ExRefine[Extract Content]
    ExRefine --> CritRefine[Step 2a: Refinement QA]
    CritRefine --> StratRefine[Step 3a: Generate Strategies]
    end
    
    subgraph Creative Branch
    CreativeBranch --> ExCreative[Extract Content]
    ExCreative --> CritCreative[Step 2b: Creative Critique]
    CritCreative --> ConceptCreative[Step 3b: Concept Generation]
    end
    
    StratRefine --> Merger[Step 4: Design Concepts Event]
    ConceptCreative --> Merger
    
    Merger --> Parallel[Step 5: Parallel Code Generation]
    
    Parallel --> Worker1[Worker 1]
    Parallel --> Worker2[Worker 2]
    Parallel --> Worker3[Worker 3]
    
    Worker1 --> Final[Step 6: Finalize & Export]
    Worker2 --> Final
    Worker3 --> Final
    
    Final --> End[Stop Event]
    
    style Start fill:#f9f,stroke:#333,stroke-width:2px
    style Analysis fill:#bbf,stroke:#333,stroke-width:2px
    style Merger fill:#fb7,stroke:#333,stroke-width:2px
    style Final fill:#9f9,stroke:#333,stroke-width:2px

Loading

1. Intent Analysis & Routing

The Vision LLM analyzes the user's request and images to determine the best path:

• Refinement Path: Triggered by requests like "clean this up," "fix spacing," or "make it professional."
• Creative Path: Triggered by requests like "redesign this," "give me a new vibe," or "brainstorm."

2. Specialized Processing Branches

• Refinement Branch:
  • Persona: "Senior Design QA & Lead Engineer"
  • Focus: Spacing consistency (8pt grid), alignment, typography hierarchy, and accessibility.
  • Output: 3 implementation-focused strategies (e.g., "The Cleanup", "Modern Polish").
• Creative Branch:
  • Persona: "Creative Director"
  • Focus: Visual metaphors, new color palettes, layout exploration.
  • Output: 3 radically distinct aesthetic concepts.

3. Unified Generation & Self-Correction

Regardless of the branch, all concepts converge at the Parallel Generation step.

• Intent-Aware Workers: The code generation workers receive the original intent.
  • If Refining, they strictly preserve brand colors and fonts.
  • If Redesigning, they are free to invent new visual systems.
• Self-Healing: Each worker runs a compiler check and auto-fixes syntax errors before delivery.

🛠 Technical Stack

• Orchestration: LlamaIndex Workflows (Event-driven async execution)
• Vision Analysis: Google Gemini 2.0 Flash (Multi-modal understanding)
• Code Generation: Google Gemini (React/CSS generation)
• Validation: Node.js + @babel/parser (Real-time syntax checking)
• Backend: FastAPI
• Logging: Custom reasoning-trace system with per-run log rotation

📁 Project Structure

telo/
├── backend/                 # Python/FastAPI Service
│   ├── design_critic/
│   │   ├── api.py           # FastAPI REST interface
│   │   ├── workflow.py      # LlamaIndex Workflow implementation
│   │   ├── models.py        # Pydantic models & Workflow Events
│   │   └── utils/
│   │       ├── runner.py    # Thread-safe Workflow runner
│   │       ├── logging_utils.py # Shared logging helpers
│   │       ├── image_utils.py   # Vision preprocessing
│   │       └── validate_jsx.js  # Node.js compiler bridge
│   ├── logs/                # Timestamped reasoning traces
│   ├── requirements.txt     # Python dependencies
│   └── .env                 # API Keys
├── frontend/                # React/Vite/Tailwind UI
├── Makefile                 # Orchestration for the whole repo
└── README.md

🚀 Getting Started

The easiest way to run everything is using the root Makefile.

1. Installation

Install all dependencies (backend & frontend) in one command:

make install

Note: This detects your root venv automatically or creates one in backend/.

2. Environment Setup

Create a .env file in the backend/ directory:

GOOGLE_API_KEY=your_gemini_api_key

3. Running the App

Open two terminal windows or use a process manager:

Terminal 1 (Backend):

make dev-backend

The API starts at http://localhost:8000.

Terminal 2 (Frontend):

make dev-frontend

The UI starts at http://localhost:5173.

🔍 Debugging & Reasoning Traces

telo is designed for transparency. Every time you run the backend, a new log file is created in backend/logs/ (format: workflow.log or specific run logs).

These logs capture:

• Step Inputs/Outputs: Full JSON data passed between workflow events.
• LLM Reasoning: Every prompt sent and response received.
• Compiler Feedback: The exact errors the self-fixing agent saw and corrected.
• State Changes: Every piece of information stored in the workflow's memory.

🎨 Design Constraints & Rules

• Strictly Typed: All internal models and events use strict Pydantic models for validation and better DX.
• No Gradients: The agent is strictly instructed to use flat, solid colors for a clean, modern aesthetic.
• Layout Safety (Hard Guardrail): The agent is forbidden from using absolute positioning for main layout containers. It must use Flexbox/Grid logic.
• Contrast & Visibility: The agent must explicitly pair background colors with contrasting text colors.
• Real Content: The agent priority is extracted text over placeholders.
• Accessibility First: All designs aim for WCAG 2.2 AA compliance.