Spaces:
Paused
Paused
| # Felix Framework User Guide | |
| > **Complete guide to using Felix Framework's helix-based multi-agent system for blog writing and research analysis** | |
| ## Table of Contents | |
| - [Getting Started](#getting-started) | |
| - [Blog Writing Demo](#blog-writing-demo) | |
| - [Helix Visualization](#helix-visualization) | |
| - [Performance Metrics](#performance-metrics) | |
| - [Advanced Features](#advanced-features) | |
| - [Exporting and Sharing](#exporting-and-sharing) | |
| - [Troubleshooting](#troubleshooting) | |
| - [Tips and Best Practices](#tips-and-best-practices) | |
| ## Getting Started | |
| ### Accessing Felix Framework | |
| #### Option 1: Hugging Face Spaces (Recommended) | |
| **[🚀 Launch Felix Framework](https://huggingface.co/spaces/CalebisGross/felix-framework)** | |
| - ✅ No setup required | |
| - ✅ ZeroGPU acceleration | |
| - ✅ All features available | |
| - ✅ Real-time collaboration | |
| #### Option 2: Local Installation | |
| ```bash | |
| 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**: | |
| ```markdown | |
| # 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: | |
| ```python | |
| topics = [ | |
| "Quantum computing hardware", | |
| "Quantum algorithms", | |
| "Quantum applications" | |
| ] | |
| # Felix processes all topics with shared context | |
| ``` | |
| ### Custom Agent Configuration | |
| ```python | |
| 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** | |
| ```bibtex | |
| @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: | |
| ```python | |
| 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 | |
| ```python | |
| # 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 | |
| ```python | |
| # 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](https://github.com/CalebisGross/thefelix/discussions)**: Ask questions and share tips | |
| - **[Documentation](../README.md)**: Complete technical documentation | |
| - **[Examples](../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.* |