Skip to content
BranchesTags

Repository files navigation

πŸ—οΈ ARCH-IA: AI-Powered Presentation Generator for Architects

ARCH-IA Banner

Python 3.9+ LangGraph License: MIT

An agentic AI workflow system for generating professional architecture presentations using LangGraph orchestration with multi-LLM support (Gemini & SiliconFlow).

πŸ“‹ Table of Contents

🎯 Overview

ARCH-IA is an agentic AI system that automates the creation of professional presentations for architects. It uses a LangGraph-based workflow to orchestrate multiple AI agents that plan, generate, validate, and create presentation content.

Key Features

  • πŸ€– Multi-LLM Support: Choose between Google Gemini or SiliconFlow (free!) as your AI provider
  • πŸ”„ Agentic Workflow: LangGraph-orchestrated pipeline with automatic retry and quality validation
  • πŸ“Š Smart Content Generation: Context-aware slide content with speaker-specific focus
  • 🎨 Template System: Professional templates for architecture presentations
  • βœ… Quality Validation: Automated content accuracy and speaker balance checks
  • πŸ“„ Multi-Output: Google Slides API integration + PowerPoint fallback

🧠 Agentic AI Architecture

The system implements a linear agentic workflow with conditional retry logic:

flowchart TB
    subgraph "πŸš€ ARCH-IA Agentic Workflow"
        START((β–Ά START)) --> CP
        
        subgraph "πŸ“‹ Planning Phase"
            CP[🎯 Content Planner<br/>━━━━━━━━━━━━━<br/>β€’ Analyze topic & audience<br/>β€’ Create presentation structure<br/>β€’ Define speaker assignments<br/>β€’ Allocate timing per slide]
        end
        
        subgraph "οΏ½οΏ½ Generation Phase"
            SG[πŸ“ Slide Generator<br/>━━━━━━━━━━━━━<br/>β€’ Select LLM provider<br/>β€’ Generate slide content<br/>β€’ Apply speaker-specific prompts<br/>β€’ Create speaker notes]
        end
        
        subgraph "🎨 Formatting Phase"
            TF[πŸ–ŒοΈ Template Formatter<br/>━━━━━━━━━━━━━<br/>β€’ Apply JSON templates<br/>β€’ Format for Google Slides API<br/>β€’ Add design system styles<br/>β€’ Structure elements]
        end
        
        subgraph "βœ… Validation Phase"
            QV[πŸ” Quality Validator<br/>━━━━━━━━━━━━━<br/>β€’ Check content accuracy<br/>β€’ Validate speaker balance<br/>β€’ Verify timing consistency<br/>β€’ Ensure template compliance]
        end
        
        subgraph "πŸ“€ Creation Phase"
            SC[πŸš€ Slides Creator<br/>━━━━━━━━━━━━━<br/>β€’ Google Slides API<br/>β€’ OAuth2 authentication<br/>β€’ Batch API requests<br/>β€’ PowerPoint fallback]
        end
        
        CP --> SG
        SG --> TF
        TF --> QV
        QV --> DECISION{Quality<br/>Passed?}
        
        DECISION -->|βœ… Yes| SC
        DECISION -->|❌ No & Retries Left| SG
        DECISION -->|❌ No & Max Retries| FAIL((β›” FAIL))
        
        SC --> SUCCESS((βœ… DONE))
    end
    
    style START fill:#4CAF50,color:#fff
    style SUCCESS fill:#4CAF50,color:#fff
    style FAIL fill:#f44336,color:#fff
    style DECISION fill:#FF9800,color:#fff
    style CP fill:#2196F3,color:#fff
    style SG fill:#9C27B0,color:#fff
    style TF fill:#00BCD4,color:#fff
    style QV fill:#FF5722,color:#fff
    style SC fill:#8BC34A,color:#fff
Loading

πŸ”„ LLM Provider Architecture

flowchart LR
    subgraph "πŸ€– LLM Provider Selection"
        CONFIG[πŸ“„ batch_config.yaml<br/>llm_provider: choice] --> SWITCH{Provider?}
        
        SWITCH -->|gemini| GEMINI[☁️ Google Gemini<br/>━━━━━━━━━━━━━<br/>β€’ gemini-2.5-flash<br/>β€’ 1M token context<br/>β€’ Structured JSON output<br/>β€’ GOOGLE_API_KEY]
        
        SWITCH -->|siliconflow| SILICON[πŸ†“ SiliconFlow<br/>━━━━━━━━━━━━━<br/>β€’ qwen3-8b FREE<br/>β€’ deepseek-r1-7b<br/>β€’ glm-4-9b<br/>β€’ SILICONFLOW_API_KEY]
        
        GEMINI --> PROMPT[πŸ“ Specialized Prompts<br/>━━━━━━━━━━━━━<br/>β€’ Speaker A: Theory<br/>β€’ Speaker B: Practice<br/>β€’ Layout-specific schemas]
        
        SILICON --> PROMPT
        
        PROMPT --> CONTENT[πŸ“Š Generated Content<br/>━━━━━━━━━━━━━<br/>β€’ Structured JSON<br/>β€’ Speaker notes<br/>β€’ Visual descriptions]
    end
    
    style GEMINI fill:#4285F4,color:#fff
    style SILICON fill:#00D4FF,color:#000
    style CONFIG fill:#FFC107,color:#000
Loading

πŸ“Š State Management Flow

stateDiagram-v2
    [*] --> INITIALIZED: Workflow Start
    INITIALIZED --> PLANNING: content_planner_node
    PLANNING --> GENERATING: slide_generator_node
    GENERATING --> FORMATTING: template_formatter_node
    FORMATTING --> VALIDATING: quality_validator_node
    
    VALIDATING --> GENERATING: Retry (quality failed)
    VALIDATING --> CREATING: Proceed (quality passed)
    VALIDATING --> FAILED: Max retries exceeded
    
    CREATING --> COMPLETED: Success
    CREATING --> COMPLETED: Fallback (PowerPoint)
    
    FAILED --> [*]
    COMPLETED --> [*]
Loading

πŸ’» System Requirements

  • Python: 3.9 or higher
  • Operating System: Linux, macOS, or Windows
  • Memory: 4GB RAM minimum (8GB recommended)
  • API Keys: At least one of:
    • GOOGLE_API_KEY for Gemini
    • SILICONFLOW_API_KEY for SiliconFlow (FREE!)

πŸ“¦ Installation

1. Clone the Repository

git clone https://github.com/your-username/iarch.git
cd iarch

2. Create Virtual Environment

python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
.\venv\Scripts\activate  # Windows

3. Install Dependencies

pip install -r requirements.txt

4. Set Up Environment Variables

Create a .env file in the project root:

# Choose ONE or BOTH providers:

# Option A: SiliconFlow (FREE - Recommended for testing)
SILICONFLOW_API_KEY=your_siliconflow_api_key_here

# Option B: Google Gemini
GOOGLE_API_KEY=your_google_api_key_here

Getting API Keys:

Provider Free Tier Get Key
πŸ†“ SiliconFlow βœ… Generous free tier cloud.siliconflow.cn
☁️ Google Gemini βœ… Free with limits makersuite.google.com

5. (Optional) Set Up Google Slides API

For Google Slides output, you need OAuth2 credentials:

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Enable the Google Slides API and Google Drive API
  4. Create OAuth 2.0 credentials (Desktop application)
  5. Download and save as credentials.json in project root

βš™οΈ Configuration

Configuration File: batch_config.yaml

# =============================================================================
# LLM Provider Configuration
# =============================================================================

# Choose your LLM provider: "siliconflow" (FREE) or "gemini"
llm_provider: "siliconflow"  # <-- Change this to switch providers

# SiliconFlow Settings (FREE models available)
siliconflow_model: "qwen3-8b"  # Options: qwen3-8b, deepseek-r1-7b, glm-4-9b
siliconflow_temperature: 0.3

# Gemini Settings
gemini_model: "gemini-2.5-flash"
gemini_temperature: 0.3

# =============================================================================
# Workflow Settings
# =============================================================================

max_retries: 5              # Max retry attempts for quality validation
min_accuracy_score: 0.3     # Minimum content accuracy (0-1)
min_speaker_balance: 0.4    # Speaker time balance threshold

# =============================================================================
# Output Configuration
# =============================================================================

output_directory: "output"
template_directory: "templates"
google_credentials_path: "credentials.json"

πŸš€ Usage Guide

Basic Usage

# Run with default settings (90-minute architecture presentation)
python main.py

Custom Presentation

# Custom topic and duration
python main.py --topic "AI in Urban Design" --duration 60

# Specify audience
python main.py --audience "Architecture Students" --duration 45

CLI Options

python main.py --help

Options:
  --topic TEXT            Presentation topic (default: ARCH-IA standard)
  --audience TEXT         Target audience (default: Professional architects)
  --duration INT          Duration in minutes (default: 90)
  --config TEXT           Configuration file path (default: batch_config.yaml)
  --log-level TEXT        Logging level: DEBUG, INFO, WARNING, ERROR
  --validate-config       Only validate configuration without running
  --output-format TEXT    Output: google_slides, powerpoint, or both

Validate Configuration

# Check configuration without running workflow
python main.py --validate-config

Debug Mode

# Run with detailed logging
python main.py --log-level DEBUG

πŸ€– LLM Provider Selection

Option 1: SiliconFlow (Recommended - FREE)

SiliconFlow offers free access to high-quality open-source models:

# In batch_config.yaml
llm_provider: "siliconflow"
siliconflow_model: "qwen3-8b"  # Best free option

Available Free Models:

Model Description Best For
qwen3-8b Qwen3 8B parameters General content
deepseek-r1-7b DeepSeek reasoning model Technical content
glm-4-9b GLM-4 vision-thinking Complex reasoning
glm-z1-9b GLM-Z1 model Balanced performance
hunyuan-7b Tencent Hunyuan Chinese-English

Option 2: Google Gemini

Google Gemini offers excellent performance with a generous free tier:

# In batch_config.yaml
llm_provider: "gemini"
gemini_model: "gemini-2.5-flash"

Available Models:

Model Context Best For
gemini-2.5-flash 1M tokens Fast, cost-effective
gemini-1.5-pro 2M tokens Complex tasks

Switching Providers

Simply change the llm_provider value in batch_config.yaml:

# Use SiliconFlow (free)
llm_provider: "siliconflow"

# Or use Gemini
llm_provider: "gemini"

πŸ“ Project Structure

iarch/
β”œβ”€β”€ main.py                     # οΏ½οΏ½ Entry point & CLI interface
β”œβ”€β”€ batch_config.yaml           # βš™οΈ Main configuration file
β”œβ”€β”€ requirements.txt            # πŸ“¦ Python dependencies
β”œβ”€β”€ .env                        # πŸ” API keys (create this)
β”‚
β”œβ”€β”€ src/                        # πŸ“‚ Source code
β”‚   β”œβ”€β”€ __init__.py
β”‚   β”œβ”€β”€ models.py               # πŸ“Š Pydantic models & state definitions
β”‚   β”œβ”€β”€ workflow.py             # πŸ”„ LangGraph workflow orchestration
β”‚   β”œβ”€β”€ gemini_client.py        # ☁️ Google Gemini API client
β”‚   β”œβ”€β”€ siliconflow_client.py   # πŸ†“ SiliconFlow API client
β”‚   β”œβ”€β”€ template_formatter.py   # 🎨 Slide template formatting
β”‚   β”œβ”€β”€ quality_validator.py    # βœ… Content quality validation
β”‚   β”œβ”€β”€ slides_creator.py       # πŸ“Š Google Slides & PPTX creation
β”‚   └── retry_utils.py          # πŸ”„ Retry logic & rate limiting
β”‚
β”œβ”€β”€ templates/                  # πŸ–ΌοΈ Slide templates
β”‚   β”œβ”€β”€ title_slide_template.json
β”‚   β”œβ”€β”€ content_slide_template.json
β”‚   β”œβ”€β”€ quote_slide_template.json
β”‚   └── ...
β”‚
β”œβ”€β”€ output/                     # πŸ“€ Generated presentations
β”œβ”€β”€ logs/                       # πŸ“ Execution logs
└── temp/                       # πŸ—‘οΈ Temporary files

πŸ”§ Workflow Details

Node 1: Content Planner 🎯

Purpose: Creates the presentation structure based on ARCH-IA requirements.

Input:

  • Topic, audience, duration
  • Speaker configuration (Data Scientist vs Fullstack Dev)

Output:

  • PresentationPlan with slide structure
  • Speaker assignments per slide
  • Timing allocations

Node 2: Slide Generator πŸ“

Purpose: Generates content for each slide using the selected LLM.

Process:

  1. Selects LLM client (Gemini or SiliconFlow)
  2. Creates speaker-specific prompts
  3. Generates structured JSON content
  4. Includes speaker notes and visual descriptions

Prompt Structure:

Speaker A (Data Scientist) β†’ Theory, math, history, ANI/AGI concepts
Speaker B (Fullstack Dev)  β†’ Practice, tools, prompting, workflows

Node 3: Template Formatter 🎨

Purpose: Applies ARCH-IA design system to generated content.

Process:

  1. Loads JSON templates from templates/
  2. Formats content for Google Slides API
  3. Applies colors, typography, positioning
  4. Adds branding elements

Node 4: Quality Validator πŸ”

Purpose: Ensures content meets quality thresholds.

Metrics Validated:

Metric Description Threshold
Content Accuracy Technical correctness 0.3
Speaker Balance A/B time distribution 0.4
Timing Consistency Adds up to target duration βœ“/βœ—
Template Compliance Required fields present βœ“/βœ—
Concept Coverage ARCH-IA topics covered 0.3

Retry Logic:

  • If validation fails β†’ Retry slide generation (up to 5x)
  • If max retries exceeded β†’ Workflow fails

Node 5: Slides Creator πŸš€

Purpose: Creates the final presentation.

Primary: Google Slides API

  • OAuth2 authentication
  • Batch API requests
  • Rate limiting (300 req/min)

Fallback: PowerPoint (python-pptx)

  • Used when Google API unavailable
  • Full feature parity

πŸ“Š Data Flow Diagram

flowchart TD
    subgraph "πŸ“₯ Input"
        IN1[Topic]
        IN2[Audience]
        IN3[Duration]
        IN4[Config YAML]
    end
    
    subgraph "πŸ”„ Processing"
        STATE[(PresentationState<br/>TypedDict)]
        
        STATE --> |topic, audience| PLAN[Create Plan]
        PLAN --> |presentation_plan| GEN[Generate Content]
        GEN --> |slides_data| FMT[Format Slides]
        FMT --> |formatted_slides| VAL[Validate Quality]
        VAL --> |quality_metrics| CREATE[Create Output]
    end
    
    subgraph "πŸ“€ Output"
        OUT1[Google Slides URL]
        OUT2[PowerPoint File]
        OUT3[Execution Logs]
    end
    
    IN1 & IN2 & IN3 --> STATE
    IN4 --> |WorkflowConfig| STATE
    
    CREATE --> OUT1
    CREATE --> OUT2
    STATE --> OUT3
    
    style STATE fill:#E1BEE7,color:#000
Loading

πŸ› Troubleshooting

Common Issues

1. "SILICONFLOW_API_KEY not found"

# Solution: Add to .env file
echo "SILICONFLOW_API_KEY=your_key_here" >> .env

2. "GOOGLE_API_KEY not found" (when using Gemini)

# Solution: Add to .env file
echo "GOOGLE_API_KEY=your_key_here" >> .env

3. Google Slides API Authentication Failed

# Solution: Delete token and re-authenticate
rm token.json
python main.py
# Follow OAuth flow in browser

4. Rate Limit Exceeded

The system has built-in retry with exponential backoff. If persistent:

# In batch_config.yaml
max_retries: 10
retry_base_delay: 2.0
retry_max_delay: 128.0

5. Quality Validation Always Fails

Lower the thresholds for testing:

# In batch_config.yaml
min_accuracy_score: 0.2
min_speaker_balance: 0.3

Debug Mode

# Enable detailed logging
python main.py --log-level DEBUG

# Check logs
tail -f logs/arch_ia_*.log

πŸ“ License

MIT License - See LICENSE for details.

🀝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Built with ❀️ using LangGraph + Gemini/SiliconFlow

Report Bug Β· Request Feature

About

ARCH-IA: Automated AI-powered slide generation system for architects using LangGraph and SiliconFlow

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages