Cranberrry

The AI Agentic UI Framework that simplifies building intelligent, interactive applications. Create AI agents, manage their tasks, and render rich UI components from text responses with unprecedented ease.

Overview

Cranberrry is a comprehensive framework designed to eliminate the complexity of building AI-powered user interfaces. It provides developers with a unified system for creating AI agents, managing their tasks, and converting structured text responses into rich, interactive React components.

What Cranberrry Solves

Traditional AI application development requires managing multiple complex systems:

• AI Agent Orchestration: Creating, configuring, and managing multiple AI agents
• Task Management: Handling complex, multi-step tasks with real-time updates
• State Management: Coordinating agent states, task progress, and UI updates
• Text-to-UI Conversion: Manually parsing responses and rendering components

Cranberrry abstracts all of this complexity into a simple, developer-friendly API that handles the entire lifecycle of AI-powered applications.

AI Agents & Task Management

Creating AI Agents

Cranberrry makes it incredibly simple to create and manage AI agents. Define your agents with clear, structured configurations:

// Define AI agents with specific capabilities
const codeAssistant: CBAgent = {
  id: "code-assistant",
  name: "Code Assistant",
  description: "Specialized in code review and development",
  isActive: true,
  isBusy: false
}

const dataAnalyst: CBAgent = {
  id: "data-analyst", 
  name: "Data Analyst",
  description: "Handles data analysis and visualization",
  isActive: true,
  isBusy: false
}

Task Management Made Simple

Cranberrry's task management system handles the entire lifecycle of AI operations:

Automatic Task Creation

Tasks are automatically created when you start an agent operation, with built-in status tracking and progress monitoring.

Real-Time Task Updates

Tasks update in real-time as AI responses stream in, providing immediate feedback to users about progress and completion status.

Error Handling & Recovery

Built-in error handling ensures tasks can be retried, paused, or resumed without manual intervention.

Task Coordination

Multiple agents can work on related tasks simultaneously, with Cranberrry coordinating their interactions and state management.

State Management Simplified

Cranberrry eliminates the need for complex state management by providing:

• Agent State Management: Track active, busy, and available states automatically
• Task State Tracking: Monitor pending, running, completed, and failed states
• UI State Coordination: Handle loading, streaming, and interactive states seamlessly
• User Interaction States: Manage input, confirmation, and feedback states

Text-to-UI Conversion

The Power of Structured Responses

Cranberrry's core innovation is its ability to convert structured text responses into rich UI components automatically. Your AI agents generate responses with custom tags that define UI elements:

<conversation>I'll help you build a React component!</conversation>
<code-analysis>{"language": "javascript", "issues": ["missing semicolon"], "suggestions": ["Add semicolon"]}</code-analysis>
<progress-update>{"step": 1, "total": 3, "message": "Analyzing code...", "percentage": 33}</progress-update>

Automatic Component Rendering

Cranberrry automatically maps these structured responses to React components:

• Conversation Components: Natural language interactions with proper styling
• Analysis Components: Code review cards with issues and suggestions
• Progress Components: Real-time progress bars and status updates
• Interactive Components: Forms, buttons, and user input elements

Custom Component Mapping

Define your own custom tags and map them to specific React components:

// Define custom UI components
const CodeAnalysisBlock = ({ ai }: { ai: any }) => (
  <div className="bg-red-50 border border-red-200 rounded-lg p-4">
    <h3>Code Analysis</h3>
    <ul>
      {ai.issues.map((issue: string) => (
        <li key={issue}>⚠ {issue}</li>
      ))}
    </ul>
  </div>
);

// Map tags to components
const tagConfigs: CBTagConfig[] = [
  { tag: "conversation", processor: "TEXT", component: ConversationBlock },
  { tag: "code-analysis", processor: "JSON", component: CodeAnalysisBlock },
  { tag: "progress-update", processor: "JSON", component: ProgressBlock },
];

Real-Time UI Updates

Components update automatically as responses stream in, creating dynamic user experiences without manual state management:

• Streaming Updates: UI components update in real-time as text streams in
• Interactive Elements: Users can interact with AI-generated components immediately
• State Synchronization: All component states are automatically synchronized
• Performance Optimized: Efficient rendering with minimal re-renders

Key Features

🚀 Lightning-Fast SSE Parsing

Parse streaming responses with custom tag detection and real-time component updates.

🤖 Simple AI Agent Creation

Create and manage AI agents with minimal configuration and automatic state handling.

📋 Intelligent Task Management

Handle complex, multi-step tasks with built-in progress tracking and error recovery.

🎨 Unlimited Custom Components

Create as many custom tags and React components as you need for your domain.

🔄 Real-Time UI Updates

Components update automatically as responses stream in, no manual state management needed.

🛡️ Type-Safe Development

Full TypeScript support with comprehensive type definitions for better developer experience.

🎯 Domain-Specific Solutions

Tailor the system to e-commerce, code review, project management, or any domain.

⚡ Lightweight & Performant

Minimal bundle size with optimized parsing and rendering algorithms.

🔧 Easy Integration

Simple hooks and components that work with any React application.

The Complexity Problem

Building AI-powered user interfaces traditionally requires managing multiple complex systems simultaneously:

Traditional Approach Challenges

AI Agent Management

// Complex state management for multiple agents
const [agents, setAgents] = useState([]);
const [agentStates, setAgentStates] = useState({});
const [agentCapabilities, setAgentCapabilities] = useState({});

// Manual agent initialization and status tracking
useEffect(() => {
  // Handle agent creation
  // Track agent status
  // Manage agent capabilities
  // Handle agent interactions
}, []);

Task Management Overhead

// Manual task state management
const [tasks, setTasks] = useState([]);

const [taskErrors, setTaskErrors] = useState({});

// Complex task lifecycle management
const handleTaskUpdate = (taskId, update) => {
  // Update task status
  // Handle task progress
  // Manage task errors
  // Update UI accordingly
};

Text-to-UI Conversion Complexity

// Manual parsing and rendering
const parseResponse = (text) => {
  // Custom parsing logic
  // Manual component rendering
  // Complex state updates
  // Error handling
};

// Manual UI updates
useEffect(() => {
  // Handle streaming
  // Update components
  // Manage multiple states
  // Handle user interactions
}, []);

With Cranberrry

// Simple agent and task management
const { startAgentTask, parseChunk } = useCBController({
  agentId: agent.id,
  tagConfigs,
  callbacks: {
    onBlockProcessed: (block) => console.log('New UI component:', block)
  }
});

// That's it! Everything else is handled automatically

Use Cases

🤖 AI Code Assistants

• Code review with real-time feedback
• Automated refactoring suggestions
• Security vulnerability detection
• Performance optimization tips

🛒 E-commerce AI

• Product recommendations
• Shopping cart updates
• Order status tracking
• Personalized offers

📊 Data Analysis

• Interactive charts and graphs
• Real-time metrics dashboards
• Automated report generation
• Data visualization components

📋 Project Management

• Task assignment workflows
• Milestone progress tracking
• Team collaboration tools
• Automated status updates