Spaces:

jkbennitt
/

felix-framework

Paused

git clone https://github.com/CalebisGross/thefelix.git
cd thefelix
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python examples/blog_writer.py "Your topic here"

Interface Overview

When you open Felix Framework, you'll see:

🌪️ Felix Framework - Helix-Based Multi-Agent System
┌─────────────────────────────────────────────────────┐
│ 📝 Blog Topic Input                                │
│ [Enter your blog topic here...]                    │
│                                                     │
│ ⚙️ Settings                                        │
│ Complexity: ●────○────● (1-10)                     │
│ Agent Count: ●───○────● (3-20)                     │
│ Creativity: ●────○────● (0.1-0.9)                  │
│                                                     │
│ [🚀 Generate Blog] [📊 Show Metrics] [🌀 Visualize]│
└─────────────────────────────────────────────────────┘

Blog Writing Demo

Understanding Multi-Agent Coordination

Felix Framework uses helix-based cognitive architecture where different agent types collaborate:

🔍 Research Agents (Top of Helix)

Position: High helix (broad radius, early spawn)
Role: Explore topic, gather information, brainstorm ideas
Characteristics: High creativity (temperature=0.9), divergent thinking
Output: Research findings, topic exploration, initial concepts

🧠 Analysis Agents (Middle Helix)

Position: Mid-helix (balanced position)
Role: Structure information, identify patterns, validate claims
Characteristics: Balanced reasoning (temperature=0.5), critical thinking
Output: Structured analysis, logical organization, fact verification

🎨 Synthesis Agents (Bottom of Helix)

Position: Low helix (narrow radius, late spawn)
Role: Create polished content, ensure coherence, final editing
Characteristics: High precision (temperature=0.1), focused output
Output: Final blog post, polished prose, coherent narrative

🔎 Critic Agents (On-Demand)

Position: Variable (spawned as needed)
Role: Quality assurance, fact-checking, improvement suggestions
Characteristics: Validation focus, error detection
Output: Quality feedback, corrections, enhancement suggestions

Step-by-Step Blog Writing

1. Enter Your Topic

Good Topics:
✅ "Quantum computing applications in healthcare"
✅ "The future of renewable energy storage"
✅ "AI ethics in autonomous vehicles"
✅ "Blockchain technology for supply chain transparency"

Topics to Avoid:
❌ "Hello" (too simple)
❌ "Everything about AI" (too broad)
❌ "Write me a blog" (no specific topic)

2. Configure Settings

Complexity Level (1-10)

1-3: Simple explanation, basic concepts, short paragraphs
4-6: Moderate depth, some technical details, balanced approach
7-10: Advanced analysis, technical depth, comprehensive coverage

Agent Count (3-20)

3-5 agents: Fast processing, basic collaboration
6-10 agents: Balanced quality and speed
11-20 agents: Maximum quality, slower processing

Creativity Level (0.1-0.9)

0.1-0.3: Factual, conservative, technical writing
0.4-0.6: Balanced creativity and accuracy
0.7-0.9: Creative, innovative, exploratory writing

3. Watch the Process

As Felix generates your blog, you'll see:

🔄 Agent Activity Monitor
┌─────────────────────────────────────────┐
│ Research Agent Alpha    [████████░░] 80% │
│ → Exploring quantum computing history    │
│                                         │
│ Analysis Agent Beta     [██████░░░░] 60% │
│ → Structuring healthcare applications   │
│                                         │
│ Synthesis Agent Gamma   [██░░░░░░░░] 20% │
│ → Preparing final draft                 │
└─────────────────────────────────────────┘

🌀 Helix Status: 15 agents active, convergence 67%

4. Review Generated Content

Your output will include:

Main Blog Post: Polished, multi-perspective content
Research Sources: Citations and references discovered
Agent Contributions: Individual agent insights
Quality Metrics: Coherence scores, fact-checking results

Blog Writing Examples

Example 1: Technical Blog

Input: "Explain neural network architectures" Output Structure:

# Understanding Neural Network Architectures: A Comprehensive Guide

## Introduction
*[Synthesis agent creates engaging introduction]*

## Historical Development
*[Research agent explores the evolution of neural networks]*

## Core Architecture Types
### Feedforward Networks
*[Analysis agent explains structure and function]*

### Convolutional Neural Networks (CNNs)
*[Multiple agents collaborate on technical details]*

### Recurrent Neural Networks (RNNs)
*[Research findings structured by analysis agents]*

## Modern Innovations
*[Research agents explore latest developments]*

## Practical Applications
*[Synthesis agents create real-world examples]*

## Conclusion
*[Critic agents ensure comprehensive coverage]*

Example 2: Creative Blog

Input: "Write about the future of space exploration" Output Style:

Research agents explore current space missions
Analysis agents identify technological trends
Synthesis agents craft narrative around human expansion
Critic agents ensure scientific accuracy

Helix Visualization

Understanding the 3D Helix Model

The helix visualization shows Felix Framework's unique architecture:

Visual Elements

     🌪️ Felix Helix (33 turns, 133 nodes)
         ○ ← Research Agent (r=33, t=0.1)
        ╱ ╲
       ○   ○ ← Analysis Agents (r=20, t=0.5)
      ╱     ╲
     ○   ○   ○ ← Synthesis Agents (r=5, t=0.8)
    ╱         ╲
   ●───────────● ← Central Post (r=0.001, t=1.0)

Helix Parameters

33 Turns: Complete spiral rotations from top to bottom
133 Nodes: Available positions for agent placement
Radius Tapering: 33.0 → 0.001 (4,119x concentration ratio)
Height Scaling: 10 units total height

Interactive Features

1. Real-Time Agent Tracking

Watch agents move through the helix as they process your request:

Blue dots: Research agents exploring
Green dots: Analysis agents organizing
Purple dots: Synthesis agents creating
Red lines: Communication spokes to central post

2. Communication Visualization

See O(N) spoke-based communication in action:

Spokes: Direct lines from agents to central coordination
Message flow: Animated data transmission
Bandwidth usage: Real-time communication metrics

3. Performance Analytics

Monitor system efficiency:

Agent utilization: Percentage of active agents
Memory usage: Current and peak memory consumption
Processing speed: Tokens per second across all agents
Convergence rate: Progress toward final output

Customizing the Visualization

Camera Controls

Rotate: Drag to rotate the 3D helix
Zoom: Mouse wheel or pinch to zoom in/out
Pan: Right-click drag to pan view
Reset: Double-click to return to default view

Display Options

⚙️ Visualization Settings
┌─────────────────────────────┐
│ ☑️ Show agent trails        │
│ ☑️ Display communication    │
│ ☑️ Animate agent movement   │
│ ☑️ Show performance overlay │
│                             │
│ Speed: ●───○───● (0.5x-3x)  │
│ Quality: ●────○─● (Low-High)│
└─────────────────────────────┘

Performance Metrics

Understanding Felix Metrics

Processing Statistics

📊 Performance Dashboard
┌─────────────────────────────────────┐
│ Total Processing Time: 12.3s        │
│ Average Response Latency: 1.8s      │
│ Peak Memory Usage: 3.2GB            │
│ Agent Efficiency: 87%               │
│                                     │
│ Tokens Generated: 1,247             │
│ Words per Minute: 156               │
│ Coherence Score: 0.94               │
│ Fact Accuracy: 96%                  │
└─────────────────────────────────────┘

Agent Performance Breakdown

🔍 Agent Analysis
┌─────────────────────────────────────┐
│ Research Agents (3 active)          │
│ ├─ Ideas Generated: 23              │
│ ├─ Sources Found: 12                │
│ └─ Time to Convergence: 4.2s        │
│                                     │
│ Analysis Agents (2 active)          │
│ ├─ Structures Created: 7            │
│ ├─ Facts Verified: 18               │
│ └─ Logic Score: 0.91                │
│                                     │
│ Synthesis Agents (2 active)         │
│ ├─ Paragraphs Written: 8            │
│ ├─ Coherence Maintained: 94%        │
│ └─ Final Quality: 0.96              │
└─────────────────────────────────────┘

Comparing Architectures

Felix automatically compares its helix approach against traditional methods:

Efficiency Comparison

Metric	Helix	Linear Pipeline	Mesh Network
Processing Time	12.3s	18.7s (+52%)	28.4s (+131%)
Memory Usage	1,200 units	2,400 units	4,800 units
Communication Overhead	O(N)	O(N×M)	O(N²)
Quality Score	0.94	0.89	0.91
Scalability	Linear	Exponential	Quadratic

Statistical Significance

H1 (Task Distribution): p=0.0441 ✅ SUPPORTED
H2 (Communication Efficiency): p=0.0892 🔍 INVESTIGATING
H3 (Attention Focusing): p<0.001 ✅ STRONGLY SUPPORTED

Advanced Features

Multi-Topic Analysis

Process multiple related topics simultaneously:

topics = [
    "Quantum computing hardware",
    "Quantum algorithms",
    "Quantum applications"
]
# Felix processes all topics with shared context

Custom Agent Configuration

agent_config = {
    "research_agents": {
        "count": 3,
        "creativity": 0.8,
        "spawn_delay": 0.1
    },
    "analysis_agents": {
        "count": 2,
        "reasoning_depth": "high",
        "fact_checking": True
    },
    "synthesis_agents": {
        "count": 2,
        "precision": 0.9,
        "style": "academic"
    }
}

Export Formats

Felix supports multiple output formats:

Markdown: Standard blog format with headers
JSON: Structured data with agent contributions
PDF: Formatted document ready for publication
LaTeX: Academic paper format with citations
HTML: Web-ready content with styling

Real-Time Collaboration

Share your Felix session with others:

Live sharing: Real-time collaborative editing
Version history: Track changes and iterations
Comment system: Feedback on specific sections
Role-based access: Different permission levels

Exporting and Sharing

Exporting Your Blog

1. Download Options

📥 Export Menu
┌─────────────────────────────┐
│ 📄 Markdown (.md)          │
│ 📋 Plain Text (.txt)       │
│ 📊 JSON Data (.json)       │
│ 📑 PDF Document (.pdf)     │
│ 🌐 HTML Page (.html)       │
│ 📝 LaTeX Source (.tex)     │
└─────────────────────────────┘

2. Sharing Features

Direct link: Share your Felix session URL
Social media: Pre-formatted posts for Twitter, LinkedIn
Email: Send blog with performance metrics
Embed: Iframe code for websites

3. Citation Format

@misc{felix_blog_2025,
  title={Your Blog Title},
  author={Generated by Felix Framework},
  howpublished={Felix Helix-Based Multi-Agent System},
  year={2025},
  note={Generated using geometric multi-agent coordination}
}

API Integration

Integrate Felix into your workflow:

import felix_framework

# Generate blog programmatically
blog = felix_framework.generate_blog(
    topic="Your topic",
    complexity=7,
    export_format="markdown"
)

# Access individual agent contributions
research_insights = blog.research_agent_outputs
analysis_structure = blog.analysis_agent_outputs
final_content = blog.synthesis_agent_outputs

Troubleshooting

Common Issues

1. Slow Processing

Problem: Blog generation takes longer than expected Solutions:

Reduce agent count (try 5-8 instead of 15-20)
Lower complexity level (try 5-6 instead of 8-10)
Simplify topic (be more specific)
Check internet connection for ZeroGPU

2. Poor Quality Output

Problem: Generated content lacks depth or coherence Solutions:

Increase complexity level (try 7-8)
Add more analysis agents (increase from 2 to 3-4)
Use more specific topic prompts
Enable fact-checking in advanced settings

3. Visualization Issues

Problem: 3D helix not displaying properly Solutions:

Enable WebGL in your browser
Try different browser (Chrome/Firefox recommended)
Reduce visualization quality in settings
Refresh the page and try again

4. Agent Coordination Problems

Problem: Agents not collaborating effectively Solutions:

Check spoke communication (ensure O(N) not O(N²))
Verify central post is functioning
Restart the helix computation
Review agent spawn timing

Error Messages

"GPU Memory Exceeded"

⚠️ ZeroGPU memory limit reached
Solution: Reduce agent count or complexity level

"Helix Computation Failed"

⚠️ Mathematical precision error
Solution: Refresh page and try again

"Agent Spawn Timeout"

⚠️ Agents failed to initialize
Solution: Check network connection and retry

Performance Optimization

For Faster Results

Use 3-5 agents instead of 10-20
Set complexity to 4-6 instead of 8-10
Choose focused topics over broad ones
Enable "Quick Mode" in advanced settings

For Higher Quality

Use 10-15 agents for complex topics
Set complexity to 7-9 for detailed analysis
Enable all agent types (research, analysis, synthesis, critic)
Allow longer processing time (30-60 seconds)

Tips and Best Practices

Writing Effective Prompts

✅ Good Prompts

Specific topics: "AI applications in medical diagnosis"
Clear scope: "Environmental impact of electric vehicles"
Actionable subjects: "Strategies for remote team management"
Current relevance: "2024 developments in quantum computing"

❌ Avoid These Prompts

Too vague: "Technology" or "Business"
Too personal: "My thoughts on..." or "I think..."
Too broad: "Everything about AI"
Commands: "Write me a blog" (specify the topic)

Optimizing Agent Performance

Research Agents

Give them broad, exploratory topics
Allow high creativity settings (0.7-0.9)
Use them for initial ideation and fact-finding
Let them spawn early in the process

Analysis Agents

Focus them on structure and organization
Use moderate creativity (0.4-0.6)
Employ for fact-checking and logical flow
Position them in mid-helix for balanced perspective

Synthesis Agents

Task them with final content creation
Set low creativity (0.1-0.3) for precision
Use for polishing and coherence
Let them work with analyzed, structured input

Understanding the Helix Advantage

Why Helix > Linear Pipeline

Natural convergence: Agents naturally focus as they progress
Parallel processing: Multiple agents work simultaneously
Emergent coordination: No explicit state management needed
Scalable communication: O(N) spoke pattern vs O(N²) mesh

When to Use Traditional Methods

Simple, single-step tasks: Basic text generation
Highly structured processes: Form filling, templates
Resource-constrained environments: Limited GPU/memory
Deterministic outputs: When consistency is critical

Research Applications

Academic Writing

Set complexity to 8-10 for detailed analysis
Enable citation tracking
Use multiple critic agents for peer review
Export to LaTeX for publication

Business Analysis

Focus on data-driven insights
Use analysis agents heavily
Enable fact-checking features
Export to PDF for presentations

Creative Writing

Increase research agent creativity (0.8-0.9)
Allow longer processing time
Use story structure templates
Enable narrative coherence checking

Advanced Configurations

Custom Helix Parameters

# Advanced users can modify helix geometry
helix_config = {
    "turns": 33,        # Spiral rotations
    "nodes": 133,       # Agent positions
    "radius_start": 33, # Top radius
    "radius_end": 0.001,# Bottom radius
    "height": 10        # Total height
}

Performance Tuning

# Optimize for your use case
performance_config = {
    "gpu_memory_limit": "20GB",
    "max_parallel_agents": 10,
    "timeout_per_agent": 30,
    "enable_mixed_precision": True
}

Getting Help

Community Resources

GitHub Discussions: Ask questions and share tips
Documentation: Complete technical documentation
Examples: Sample code and use cases

Support Channels

Issues: Report bugs on GitHub
Feature Requests: Suggest improvements
Academic Collaboration: Contact for research partnerships

Stay Updated

GitHub: Watch the repository for updates
Release Notes: Check version history
Research Papers: Follow our publications

Ready to create amazing content with Felix Framework? Start with a simple topic and experiment with different settings!

Remember: Felix Framework represents a new paradigm in multi-agent coordination. The helix architecture creates emergent behaviors that often surprise even experienced users. Embrace the spiral, and discover what geometric intelligence can create.

Felix Framework User Guide

Table of Contents

Getting Started

Accessing Felix Framework

Option 1: Hugging Face Spaces (Recommended)

Option 2: Local Installation