Agent Factory 🏭🤖

Building the engine that turns knowledge into autonomous content at scale

Agent Factory is not just a framework—it's the orchestration engine powering two ambitious platforms:

PLC Tutor / Industrial Skills Hub - AI-powered PLC programming education with autonomous YouTube content production
RIVET - Industrial maintenance knowledge platform with validated troubleshooting solutions

Vision: Build autonomous agent systems that create, distribute, and monetize educational content 24/7, while building the largest validated knowledge base in industrial automation.

Status: ✅ Week 2 Day 3 COMPLETE - All 9 ISH Agents Ready (100%)

📝 Latest Updates

2025-12-25 16:34:47 UTC

Fixed Add robust JSON extraction from LLM responses (handles markdown code blocks + better logging)
Metrics: Files: 1 | Lines: +24/-2 | KB Atoms: (unavailable)

2025-12-25 16:30:05 UTC

Fixed Gracefully degrade when source_fingerprints table missing (allows ingestion to continue)
Metrics: Files: 1 | Lines: +33/-15 | KB Atoms: (unavailable)

2025-12-25 14:45:51 UTC

Fixed Use %s placeholders for psycopg in immediate write query
Metrics: Files: 1 | Lines: +2/-2 | KB Atoms: (unavailable)

2025-12-25 14:42:06 UTC

Fixed Use plain text instead of Markdown for batch summaries (fixes 400 error)
Metrics: Files: 1 | Lines: +17/-14 | KB Atoms: (unavailable)

2025-12-25 14:30:36 UTC

Fixed Write ingestion metrics immediately instead of background queue
Add _write_metric_immediately() for synchronous DB writes
Prevents metrics loss when scripts exit before flush
Falls back to failover log if DB unavailable
Metrics: Files: 1 | Lines: +71/-3 | KB Atoms: (unavailable)

2025-12-25 14:22:18 UTC

Fixed Make batch notifications read from database not in-memory queue
Add db_manager param to TelegramNotifier
Query ingestion_metrics_realtime for last 5 min sessions
Mark sessions as notified to prevent duplicates
Works across all processes (CLI, Redis worker, bot)
Metrics: Files: 2 | Lines: +80/-13 | KB Atoms: (unavailable)

2025-12-25 14:10:35 UTC

Fixed Add persistent KB observability batch timer to orchestrator bot
Integrate batch notification timer into bot's event loop
Timer runs every 5 minutes for BATCH mode summaries
Survives bot restarts and keeps running 24/7
Graceful error handling if initialization fails
Metrics: Files: 1 | Lines: +34/-0 | KB Atoms: (unavailable)

2025-12-25 12:40:09 UTC

Added Integrate KB observability into ingestion pipeline
Add IngestionMonitor + TelegramNotifier to ingestion_chain.py
Background batch timer for 5-minute summaries
Session tracking through all 7 pipeline stages
Graceful degradation if monitoring fails
End-to-end test script for validation
Metrics: Files: 2 | Lines: +429/-40 | KB Atoms: (unavailable)

2025-12-25 11:50:33 UTC

Updated documentation for Add comprehensive Telegram Observability implementation guide
Basic integration (recommended)
BATCH mode with background timer
Error-only notifications
Multiple chat IDs (team notifications)
Step-by-step Telegram bot setup (2 minutes)
Quick start testing (5 minutes)
4 copy-paste implementation patterns
Production systemd service template
Comprehensive troubleshooting guide
Environment variable reference
Validation commands
docs/SYSTEM_MAP_OBSERVABILITY.md (technical architecture)
.claude/memory/CONTINUE_HERE_OBSERVABILITY.md (developer resume guide)
Metrics: Files: 1 | Lines: +956/-0 | KB Atoms: (unavailable)

2025-12-25 11:44:27 UTC

Updated documentation for Add KB Observability Platform system map and test files
docs/SYSTEM_MAP_OBSERVABILITY.md (25 KB)
Complete architecture documentation
Component specifications (IngestionMonitor, TelegramNotifier)
Data flow diagrams
Configuration guide
Performance characteristics
Testing & validation procedures
Production deployment guide
Troubleshooting reference
Security considerations
test_ingestion_monitor.py - Phase 2.1 integration test
Tests IngestionMonitor with real database
Validates failover logging
Verifies background writer queue
data/observability/failed_metrics.jsonl (3.2 KB)
Example failover log (database unavailable scenario)
Demonstrates graceful degradation
.claude/observability/metrics.json
Metrics configuration
Metrics: Files: 4 | Lines: +944/-0 | KB Atoms: (unavailable)

2025-12-25 11:42:04 UTC

Fixed Use temp file instead of pipe for hook reliability
Avoids stderr/stdout mixing in pipes on Windows
Metrics saved to temp JSON file
README script reads from file instead of stdin
More reliable cross-platform execution
Metrics: Files: 2 | Lines: +38/-4 | KB Atoms: (unavailable)

2025-12-25 08:45:00 UTC

Added README auto-update on git push
Automatic metrics extraction (git stats + DB atom count)
Plain English summaries from conventional commits
Reverse chronological updates in README.md
Dual-layer: local hook + GitHub Actions backup
Metrics: Files: 5 | Lines: +900/-0 | KB Atoms: 1,965

📊 Current Development Status (Week 2, Day 3 Complete)

ISH Swarm Progress: 9/9 Agents Complete (100%)

Agent	Status	Location	Lines	Function
ResearchAgent	✅ Complete	main	450	Find trending PLC topics from Reddit
ScriptwriterAgent	✅ Complete	main	existing	Generate video scripts from atoms
VideoQualityReviewerAgent	✅ Complete	main	664	Score scripts 0-10, approve/flag/reject
VoiceProductionAgent	✅ Complete	main	existing	Generate narration (ElevenLabs/edge-tts)
VideoAssemblyAgent	✅ Complete	main	546	Render 1080p MP4 videos (FFmpeg)
MasterOrchestratorAgent	✅ Complete	main	920	Coordinate all 9 agents + approval gates
SEOAgent	✅ Complete	main	595	Optimize titles, descriptions, tags
ThumbnailAgent	✅ Complete	main	590	Generate eye-catching thumbnails
YouTubeUploaderAgent	✅ Complete	main	651	Publish videos to YouTube Data API

Day 3 Completion Summary

Merged to Main (Dec 15):

✅ SEOAgent (595 lines) - Keyword optimization, title generation, description writing
✅ ThumbnailAgent (590 lines) - Eye-catching thumbnail generation with A/B testing
✅ YouTubeUploaderAgent (651 lines) - OAuth2 authentication, resumable uploads, quota management

All agents validated:

✅ All 9 agents import successfully
✅ Pydantic models for type safety
✅ Comprehensive error handling
✅ Production-ready code quality

Knowledge Base Status

1,964 atoms in Supabase (Allen-Bradley + Siemens)
Vector search ready (<100ms semantic queries)
5 test scripts generated from real atoms
1 test video rendered (20s, 1080p @ 30fps)

🔧 Knowledge Base Ingestion Pipeline (LangGraph)

Status: ⚠️ Code Complete + Tested - Database Migration Required

7-Stage LangGraph Pipeline for Knowledge Base Growth:

Source Acquisition - PDF/YouTube/web download with SHA-256 deduplication
Content Extraction - Parse text, preserve structure, identify content types
Semantic Chunking - 200-400 word atom candidates (RecursiveCharacterTextSplitter)
Atom Generation - LLM extraction with GPT-4o-mini → Pydantic LearningObject models
Quality Validation - 5-dimension scoring (completeness, clarity, educational value, attribution, accuracy)
Embedding Generation - OpenAI text-embedding-3-small (1536-dim vectors)
Storage & Indexing - Supabase with deduplication + retry logic

Performance:

Sequential: 60 atoms/hour (10-15 sec/source)
Parallel (Phase 2): 600 atoms/hour (10 workers via asyncio.gather)
Cost: $0.18 per 1,000 sources (GPT-4o-mini + embeddings)

Impact on Quality:

Script quality: 55/100 → 75/100 (+36% improvement)
Script length: 262 words → 450+ words (+72% improvement)
Technical accuracy: 4.0/10 → 8.0/10 (+100% improvement)
KB growth: 1,965 atoms → 5,000+ atoms target (80% high-quality narrative)

Usage:

# Single source ingestion
poetry run python -c "from agent_factory.workflows.ingestion_chain import ingest_source; print(ingest_source('https://example.com/plc-tutorial.pdf'))"

# Batch ingestion from file
poetry run python scripts/ingest_batch.py --batch data/sources/urls.txt

# Parallel processing (Phase 2)
poetry run python scripts/ingest_batch.py --batch urls.txt --parallel 10

Files:

Pipeline: agent_factory/workflows/ingestion_chain.py (750 lines)
CLI: scripts/ingest_batch.py (150 lines)
Migration: docs/database/ingestion_chain_migration.sql (5 new tables)

Next Step: Deploy docs/database/ingestion_chain_migration.sql in Supabase SQL Editor (5 min)

See: ingestion_chain_results.md for test results and deployment instructions

Week 2 Timeline

✅ Day 1: ResearchAgent (Reddit topic discovery)
✅ Day 2: ScriptwriterAgent testing + VideoQualityReviewerAgent + VideoAssemblyAgent + MasterOrchestratorAgent (parallel)
✅ Day 3: ThumbnailAgent + SEOAgent + YouTubeUploaderAgent (COMPLETE - all merged to main)
🎯 Day 4-5: End-to-end pipeline testing (NEXT)
⏳ Day 6-7: Week 3 prep (video production)

Next Milestone: Day 4-5 - End-to-end pipeline validation (orchestrator → script → video → publish)

🔍 NEW: Perplexity Citation Format Integration

Critical Update (2025-12-12): All knowledge atoms now follow Perplexity-style citation format for maximum credibility and legal safety.

Why This Matters:

✅ Every claim has authoritative sources
✅ Footnote citations [^1][^2] preserved from research → atoms → scripts → videos
✅ YouTube descriptions include full "Sources:" section
✅ Prevents copyright issues (proper attribution)
✅ Builds viewer trust (verifiable claims)

Example Format (see CLAUDEUPDATE.md):

# What is 5S methodology?

5S is a lean workplace-organization system...[^1][^6]

- **Sort**: Remove unnecessary items...[^5]
- **Set in Order**: Arrange with defined places...[^6]

[^1]: https://worktrek.com/blog/what-is-5s-principal-for-maintenance/
[^5]: https://business.adobe.com/blog/basics/the-5s-methodology

Implementation:

ResearchAgent now outputs Perplexity-format research
AtomBuilderAgent parses footnote citations → JSONB storage
ScriptwriterAgent includes inline citations in scripts
YouTubeUploaderAgent adds "Sources:" section to descriptions

See: docs/PERPLEXITY_INTEGRATION.md for complete integration guide

🎯 What We're Building

The Triune Vision

┌─────────────────────────────────────────────────────┐
│          Agent Factory (Orchestration Engine)        │
│  Multi-agent coordination • Knowledge management     │
│  Content production • Distribution automation        │
└─────────────────────────────────────────────────────┘
                         ↓
         ┌───────────────┴───────────────┐
         ↓                               ↓
┌──────────────────────┐      ┌──────────────────────┐
│  PLC Tutor           │      │  RIVET               │
│  (Education-driven)  │      │  (Community-driven)  │
├──────────────────────┤      ├──────────────────────┤
│ • YouTube A-to-Z     │      │ • Reddit monitoring  │
│ • Voice clone 24/7   │      │ • Validated answers  │
│ • 100+ video series  │      │ • B2B integrations   │
│ • Courses + certs    │      │ • Premium calls      │
│ • B2B training       │      │ • CMMS platforms     │
├──────────────────────┤      ├──────────────────────┤
│ Year 1: $35K ARR     │      │ Year 1: $80K ARR     │
│ Year 3: $2.5M ARR    │      │ Year 3: $2.5M ARR    │
└──────────────────────┘      └──────────────────────┘
         ↓                               ↓
         └───────────────┬───────────────┘
                         ↓
           ┌─────────────────────────┐
           │  Data-as-a-Service       │
           │  (License knowledge)     │
           └─────────────────────────┘
                         ↓
           ┌─────────────────────────┐
           │  Robot Licensing         │
           │  (Humanoid robots)       │
           └─────────────────────────┘

🚀 Current Focus: PLC Tutor Launch (Week 1-12)

✅ Infrastructure Complete (Dec 9-10)

Recently Built:

Supabase Memory System - <1 second session loading (60-120x faster than files)
FREE LLM Integration - $0/month costs via Ollama (DeepSeek Coder 6.7B)
Settings Service - Runtime configuration without code deployments
Core Pydantic Models - 600+ lines production schemas
GitHub Automation - Webhooks, auto-sync, orchestrator integration
Complete Documentation - 7 strategy docs (142KB), implementation roadmap

Cost Savings: $200-500/month in LLM costs → $0/month Performance: Session loading 30-60s → <1 second

✅ Voice System: Generic TTS Active (Blocker Removed!)

Hybrid Voice System - Edge-TTS (FREE), OpenAI TTS (PAID), ElevenLabs (custom)
Current Mode: Edge-TTS (Microsoft neural voices, $0/month)
Upgrade Path: Switch to custom voice Saturday (one env variable change)
Status: Can produce professional narration NOW

🔴 Remaining User Tasks (Non-blocking for agents)

First 10 Atoms - Create electrical + PLC basics knowledge atoms
Supabase Schema - Deploy docs/supabase_migrations.sql
Voice Training (Saturday) - Record samples, upload to ElevenLabs (optional upgrade)

📅 Next: Week 2 Agent Development

Once user tasks complete, build:

Research Agent (web scraping, YouTube transcripts)
Scriptwriter Agent (atoms → video scripts)
Atom Builder Agent (raw data → structured atoms)

🚀 The YouTube-Wiki Strategy (Week 1-12 Roadmap)

The YouTube-Wiki Strategy

Core Insight: "YouTube IS the knowledge base"

Instead of scraping content then making videos, we build the knowledge base BY creating original educational content.

The Pipeline:

YOU learn concept → Research Agent compiles sources
    ↓
Scriptwriter Agent drafts teaching script (atom-backed, no hallucination)
    ↓
Voice Production Agent generates narration (ElevenLabs voice clone)
    ↓
Video Assembly Agent combines audio + visuals + captions
    ↓
YouTube Uploader Agent publishes (SEO-optimized)
    ↓
Atom Builder Agent extracts knowledge atom from video
    ↓
Social Amplifier Agent creates clips for TikTok/Instagram/LinkedIn

18 Autonomous Agents

Executive Team (2):

AI CEO Agent - Strategy, metrics, resource allocation
AI Chief of Staff Agent - Project management, issue tracking

Research & Knowledge Base Team (4):

Research Agent - Web scraping, YouTube transcripts, PDFs
Atom Builder Agent - Convert raw data → structured atoms
Atom Librarian Agent - Organize atoms, build prerequisite chains
Quality Checker Agent - Validate accuracy, safety, citations

Content Production Team (5):

Master Curriculum Agent - 100+ video roadmap, sequencing
Content Strategy Agent - Keyword research, SEO
Scriptwriter Agent - Transform atoms → engaging scripts
SEO Agent - Optimize titles, descriptions, tags
Thumbnail Agent - Generate thumbnails, A/B testing

Media & Publishing Team (4):

Voice Production Agent - ElevenLabs narration
Video Assembly Agent - MoviePy + FFmpeg rendering
Publishing Strategy Agent - Optimal timing, scheduling
YouTube Uploader Agent - Execute uploads, handle errors

Engagement & Analytics Team (3):

Community Agent - Respond to comments, moderate
Analytics Agent - Track metrics, detect trends
Social Amplifier Agent - TikTok/Instagram clips

See: docs/AGENT_ORGANIZATION.md for complete specifications

📊 Milestones & Success Metrics

Week 4 (Public Launch)

✅ 3 videos live on YouTube
✅ Voice clone validated (< 10% robotic artifacts)
✅ CTR > 2%, AVD > 40%
✅ 100+ subscribers

Week 12 (Autonomous Operations)

✅ 30 videos published
✅ 1,000+ subscribers
✅ $500+ revenue (courses + ads)
✅ Agents 80% autonomous (you review exceptions only)
✅ YouTube Partner Program applied

Month 12 (Scale Achieved)

✅ 100+ videos published
✅ 20,000+ subscribers
✅ $5,000+/month revenue
✅ 100+ validated knowledge atoms
✅ Agents fully autonomous (99% without human intervention)

See: docs/IMPLEMENTATION_ROADMAP.md for week-by-week plan

📚 Documentation (Strategy Suite)

Essential Reading (Start Here)

Document	Purpose	Size
TRIUNE_STRATEGY.md	Master integration document (RIVET + PLC + Agent Factory)	32KB
YOUTUBE_WIKI_STRATEGY.md	YouTube-first approach, voice clone, monetization	17KB
AGENT_ORGANIZATION.md	All 18 agents with complete specs	26KB
IMPLEMENTATION_ROADMAP.md	Week-by-week implementation plan (12 weeks)	22KB
CONTENT_ROADMAP_AtoZ.md	100+ video topics sequenced (electricity → AI)	24KB
ATOM_SPEC_UNIVERSAL.md	Universal knowledge atom schema (IEEE LOM)	21KB
CLAUDE.md	AI agent context (how to work with this project)	-
TASK.md	Current tasks, priorities, progress tracking	-

Technical Documentation

Document	Purpose
cole_medin_patterns.md	Production patterns from Archon (13.4k⭐)
archon_architecture_analysis.md	Microservices architecture deep dive
integration_recommendations.md	Prioritized roadmap for Agent Factory
GIT_WORKTREE_GUIDE.md	Multi-agent development workflow
SECURITY_STANDARDS.md	Compliance patterns & checklists

GitHub Issues

Issue	Title	Status
#44	Week 1 Foundation - System Setup & Voice Training	🔴 CRITICAL
#45	Create First 10 Knowledge Atoms	🟡 HIGH
#46	Implement Core Pydantic Models	✅ COMPLETED
#47	Build Research Agent	📅 Week 2
#48	Build Scriptwriter Agent	📅 Week 2
#49	Week 1 Complete Checklist (Master)	🔴 TRACKING

📖 User Guides

Complete setup and deployment guides → See Guides for Users/

Quick Start

QUICKSTART.md - First-time setup (15 minutes)
QUICK_START_24_7.md - 24/7 autonomous operations

Deployment

PRODUCTION_DEPLOYMENT.md - Cloud deployment (Railway, Supabase)
BOT_DEPLOYMENT_GUIDE.md - Telegram bot deployment
TELEGRAM_AUTO_START_GUIDE.md - Windows auto-start
TELEGRAM_BOT_100_PERCENT_RELIABLE.md - 24/7 reliability

Integration

TELEGRAM_KB_INTEGRATION.md - Knowledge base integration
CLAUDEUPDATE_APPLIED.md - Perplexity citation format

Development

POETRY_GUIDE.md - Dependency management
OLLAMA_SETUP_COMPLETE.md - FREE local LLMs (saves $200-500/month)
AGENT_EDITING_GUIDE.md - Create and modify agents

All guides: See Guides for Users/README.md for complete index

🤖 GitHub Issue Automation (NEW!)

Automatically solve GitHub issues with FREE local LLMs

Quick Start

# Solve a single issue
poetry run python solve_github_issues.py --issue 52

# Solve all "agent-task" labeled issues
poetry run python solve_github_issues.py --label "agent-task"

# See what would be solved (dry run)
poetry run python solve_github_issues.py --label "agent-task" --dry-run

How It Works

Fetch issue from GitHub (via gh CLI)
Generate solution with OpenHands + FREE Ollama (DeepSeek Coder)
Review code - you approve before committing
Auto-commit with message: feat: <title> (closes #N)
Push to GitHub - issue auto-closes!

Cost Savings

Manual coding: 2-4 hours, $100-600 per issue
Claude API: 5 mins, $0.15-0.50 per issue
Ollama (this): 5 mins, $0.00 per issue

Annual savings: $780-2,600 for 10 issues/week

Features

✅ $0.00 cost - Uses FREE Ollama (DeepSeek Coder 6.7B)
✅ 5-15 min per issue - vs 2-4 hours manual
✅ 80% GPT-4 quality - Production-ready code
✅ Safe by default - Requires approval before committing
✅ Batch processing - Solve multiple issues at once
✅ Auto-closes issues - Via commit message

Requirements

Ollama installed with model:

winget install Ollama.Ollama
ollama pull deepseek-coder:6.7b

GitHub CLI authenticated:
```
gh auth login
```

Environment configured:

# In .env
USE_OLLAMA=true
OLLAMA_MODEL=deepseek-coder:6.7b

Documentation

Complete Guide: docs/GITHUB_ISSUE_AUTOMATION.md
Demo Script: examples/solve_issue_demo.py
Ollama Setup: docs/OPENHANDS_FREE_LLM_GUIDE.md

Example Output

[1/7] Fetching issue #52...
  Title: Implement webhook handler
  Labels: agent-task, enhancement

[2/7] Creating OpenHands task...
  Task created (450 characters)

[3/7] Solving with OpenHands (FREE Ollama)...
  SUCCESS in 12.3s

[4/7] Validating...
  [OK] Syntax valid
  [OK] No security issues

[5/7] Generated solution:
  (Shows code preview)

[6/7] Apply? yes

[7/7] Committed and pushed
  Issue #52 will auto-close!

Cost: $0.00 | Time: 12.3s | Savings vs Claude: $0.25

See full guide: docs/GITHUB_ISSUE_AUTOMATION.md

🛠️ Technology Stack

Core Infrastructure

Python 3.10+ - Primary language
Pydantic v2 - Data validation & schemas
Supabase + pgvector - Database with vector search
LangChain - Agent orchestration framework
APScheduler - Task scheduling (cron-like)

AI & ML

Claude API (Anthropic) - Agent intelligence, scripting
OpenAI API - Embeddings, GPT-4 for specialized tasks
ElevenLabs Pro - Voice cloning & TTS ($30/mo)

Media Production

FFmpeg - Video rendering, clip extraction
MoviePy - Video assembly, timeline sync
Pydub - Audio processing
Pillow - Image processing, thumbnails
OpenAI Whisper - Caption generation

Platforms & APIs

YouTube Data API - Upload, metadata, analytics
TikTok API - Post videos
Instagram Graph API - Post reels
Reddit API - Community engagement
Twitter/X API - Social distribution

Development Tools

Poetry - Dependency management
Pytest - Testing
Git Worktrees - Multi-agent development

📦 Installation & Setup

Prerequisites

Python 3.10 or 3.11 (required)
Poetry (recommended) or pip
Git (for version control)

Quick Start

# 1. Clone the repository
git clone https://github.com/your-username/agent-factory.git
cd agent-factory

# 2. Install dependencies (Poetry 2.x)
poetry install

# 3. Copy environment template
cp .env.example .env

# 4. Add API keys to .env
# - OPENAI_API_KEY
# - ANTHROPIC_API_KEY
# - SUPABASE_URL
# - SUPABASE_KEY
# - ELEVENLABS_API_KEY (for voice clone)

# 5. Test installation
poetry run python -c "from core.models import PLCAtom; print('✓ Installation successful')"
poetry run python test_models.py  # All 6 tests should pass

Week 1 Setup (Human Tasks)

See: Issue #44 for complete checklist

Monday-Tuesday (3-4 hours):

Record 10-15 min voice samples (teaching mode, varied emotion)
Upload to ElevenLabs Professional Voice Cloning
Create Supabase project (enable pgvector extension)
Run schema migrations (docs/supabase_migrations.sql)
Test voice clone (generate 30s sample, verify quality < 10% robotic)

Wednesday-Thursday (4-6 hours):

Manually create 10 knowledge atoms (5 electrical, 5 PLC basics)
Insert into Supabase knowledge_atoms table
Generate embeddings (OpenAI text-embedding-3-small)
Test vector search (query "what is voltage" → correct atom returned)

Friday (2-3 hours):

Implement Core Pydantic Models (core/models.py) ✅ COMPLETED
Validate all models with test suite ✅ COMPLETED

🏗️ Project Structure

agent-factory/
├── core/                          # Core data models
│   ├── models.py                  # Pydantic schemas (600+ lines) ✅
│   ├── agent_factory.py           # Main factory class
│   └── settings_service.py        # Runtime configuration
├── docs/                          # Strategy & technical docs
│   ├── TRIUNE_STRATEGY.md         # Master vision (32KB) ✅
│   ├── YOUTUBE_WIKI_STRATEGY.md   # Content strategy (17KB) ✅
│   ├── AGENT_ORGANIZATION.md      # 18 agents specs (26KB) ✅
│   ├── IMPLEMENTATION_ROADMAP.md  # Week-by-week plan (22KB) ✅
│   ├── ATOM_SPEC_UNIVERSAL.md     # Knowledge atom schema (21KB) ✅
│   └── *.md                       # Technical documentation
├── plc/                           # PLC Tutor vertical
│   ├── content/
│   │   └── CONTENT_ROADMAP_AtoZ.md  # 100+ videos (24KB) ✅
│   ├── agents/                    # PLC-specific agents (Week 2+)
│   └── atoms/                     # Knowledge atoms (Week 1)
├── agents/                        # Agent implementations (Week 2+)
│   ├── research/                  # Research & KB agents
│   ├── content/                   # Content production agents
│   ├── media/                     # Media & publishing agents
│   ├── engagement/                # Community & analytics agents
│   └── executive/                 # AI CEO & Chief of Staff
├── tests/                         # Test suites
│   └── test_models.py             # Pydantic model tests ✅
├── examples/                      # Demo scripts
├── CLAUDE.md                      # AI agent context ✅
├── TASK.md                        # Current tasks ✅
└── README.md                      # This file ✅

Legend:

✅ Completed (Week 0)
📅 Upcoming (Week 1-2)
🔜 Planned (Week 3+)

🤖 Core Data Models (Pydantic v2)

All data types are defined in core/models.py using Pydantic v2 with full validation.

Knowledge Atoms

from core.models import PLCAtom, RIVETAtom, EducationalLevel

# PLC programming knowledge atom
plc_atom = PLCAtom(
    id="plc:ab:timer-on-delay",
    title="Timer On-Delay (TON) - Allen-Bradley",
    description="TON timer delays output by preset time when input goes true",
    domain="plc",
    vendor="allen_bradley",
    plc_language="ladder",
    educational_level=EducationalLevel.INTRO,
    typical_learning_time_minutes=15,
    code_snippet="...",  # Ladder logic example
    prerequisites=["plc:generic:io-basics", "plc:generic:ladder-fundamentals"]
)

# Industrial maintenance troubleshooting atom
rivet_atom = RIVETAtom(
    id="rivet:motor:won-t-start",
    title="3-Phase Motor Won't Start",
    equipment_class="ac_induction_motor",
    symptoms=["Motor hums but doesn't rotate"],
    root_causes=[...],
    diagnostic_steps=[...],
    corrective_actions=[...],
    safety_level="danger",
    lockout_tagout_required=True
)

Content Production

from core.models import VideoScript, UploadJob

# Video script generated by Scriptwriter Agent
script = VideoScript(
    id="script:ohms-law-video",
    title="Ohm's Law - The Foundation of Electrical Engineering (#3)",
    outline=["Hook", "Explanation", "Example", "Recap"],
    script_text="[enthusiastic] This one equation...",
    atom_ids=["plc:generic:ohms-law"],
    duration_minutes=8,
    keywords=["ohms law", "V=IR", "electrical calculations"]
)

# YouTube upload job
upload = UploadJob(
    channel="industrial_skills_hub",
    video_script_id="script:ohms-law-video",
    audio_path="/media/ohms-law-audio.mp3",
    video_path="/media/ohms-law-video.mp4",
    thumbnail_path="/media/ohms-law-thumb.jpg",
    youtube_title="Ohm's Law - Tutorial (#3)",
    visibility="public",
    scheduled_time=None  # Publish immediately
)

Curriculum Organization

from core.models import Module, Course

# Module: Collection of related atoms
module = Module(
    id="module:electrical-fundamentals",
    title="Electrical Fundamentals",
    atom_ids=["plc:generic:voltage", "plc:generic:current", ...],
    estimated_hours=2.5
)

# Course: Collection of modules
course = Course(
    id="course:intro-to-plc",
    title="Introduction to PLC Programming",
    module_ids=["module:electrical-fundamentals", "module:plc-basics"],
    estimated_hours=10.0,
    price_usd=49.99
)

See: docs/ATOM_SPEC_UNIVERSAL.md for complete specification

🎓 Content Roadmap: 100+ Videos

Complete A-to-Z curriculum from electricity basics to AI-augmented automation.

Track A: Electrical Fundamentals (Videos 1-20)

What is Electricity?
Voltage, Current, Resistance
Ohm's Law (V=I×R)
Electrical Power & Safety
Sensors, Actuators, Motors

Track B: PLC Fundamentals (Videos 21-40)

What is a PLC?
PLC Scan Cycle
Ladder Logic Basics
Timers & Counters
Your First PLC Program

Track C: Structured Text & Advanced (Videos 41-60)

Introduction to Structured Text
HMI Integration
Data Logging & Trending
Industrial Networks

Track D: Vendor-Specific (Videos 61-80)

Allen-Bradley ControlLogix
Siemens S7-1200/1500
Studio 5000 & TIA Portal

Track E: AI & Automation (Videos 81-100)

AI for PLC Programming
Autonomous PLC Code Generation
Predictive Maintenance
The Future of Automation

See: plc/content/CONTENT_ROADMAP_AtoZ.md for all 100+ topics with keywords, hooks, examples, and quizzes

💰 Business Model & Monetization

Multi-Stream Revenue (PLC Tutor)

Free Tier:

YouTube channel (ads, organic growth)
Core lessons (electricity basics, PLC fundamentals)
Community engagement

Paid Tier:

Structured courses ($49-$299): "Electricity Fundamentals to PLC Expert"
Premium membership ($29/mo): Interactive AI tutor, personalized exercises
Lab kits: Factory I/O project templates, simulation scenarios

B2B (Later):

Corporate training licenses ($10K-$20K/org)
White-label tutor for trade schools, OEMs
API access to knowledge base + agents

Revenue Targets

Milestone	Subscribers	Revenue/Month	Key Metrics
Week 12	1,000	$500	First course sales, YPP application
Month 6	5,000	$2,000	YouTube Partner active, course bundles
Month 12	20,000	$5,000	Premium tier, B2B inquiries
Year 3	100,000+	$200,000+ ($2.5M ARR)	Sustainable business, multiple revenue streams

See: docs/TRIUNE_STRATEGY.md for complete financial model

🔐 Security & Compliance

Agent Factory is built with enterprise-grade security from inception.

Security by Design

Before Writing Code:

Input: Validate + sanitize all user input
Data: Encrypt sensitive data + log access
Access: Add auth + rate limits
Output: Filter PII + validate safety
Abuse: Add monitoring + circuit breakers

Before Marking Complete:

Security implications documented
Audit logging implemented (who, what, when)
Error messages don't leak sensitive data
Rate limits exist (if user-facing)
Input validation with allow-lists

Core Principles:

Principle of Least Privilege (default deny, explicit allow)
Defense in Depth (multiple security layers)
Fail Secure (errors block, not allow)
Audit Everything (log all privileged operations)
Assume Breach (limit blast radius)

See: docs/SECURITY_STANDARDS.md for complete guidelines

🤝 Contributing

We welcome contributions! Here's how:

For Contributors

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Work in a git worktree (see docs/GIT_WORKTREE_GUIDE.md)
Follow security standards (see docs/SECURITY_STANDARDS.md)
Write tests for new features
Commit with conventional commits (feat:, fix:, docs:, etc.)
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Install dev dependencies
poetry install --with dev

# Run tests
poetry run pytest

# Validate models
poetry run python test_models.py

# Format code (if configured)
poetry run black .
poetry run isort .

For AI Agents

If you're an AI agent working on this project:

Read CLAUDE.md for complete context
Check TASK.md before starting work
Use git worktrees for isolation (required by pre-commit hook)
Follow security checklist before marking features complete
Update documentation as you build

📞 Support & Community

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: [email protected]

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

This project incorporates patterns from:

LangChain Crash Course (MIT License)
Archon by Cole Medin (13.4k⭐)
context-engineering-intro (11.8k⭐)

🙏 Acknowledgments

LangChain - Agent orchestration framework
Cole Medin - Production patterns (Archon, context engineering, settings service)
Anthropic - Claude API for agent intelligence
OpenAI - Embeddings & GPT-4
ElevenLabs - Voice cloning technology
Supabase - Database & vector search infrastructure

🗺️ Roadmap

Phase 1: Foundation (Weeks 1-4) - INFRASTRUCTURE COMPLETE

Complete strategy documentation (TRIUNE, YOUTUBE_WIKI, AGENT_ORG, ROADMAP, CONTENT)
Implement Pydantic models (LearningObject, PLCAtom, RIVETAtom, VideoScript, etc.)
Supabase memory system (<1s session loading)
FREE LLM integration (Ollama, $0/month costs)
Settings service (runtime configuration)
GitHub automation (webhooks, auto-sync)
Voice training & ElevenLabs setup (Issue #44) - USER TASK
Create first 10 knowledge atoms (Issue #45) - USER TASK
Public launch: 3 videos live (Week 4)

Phase 2: Agent Implementation (Weeks 5-8)

Research Agent + Atom Builder (Week 2)
Scriptwriter Agent (Week 2)
Video Production Pipeline (Voice, Assembly, Thumbnail) (Week 3)
Publishing Pipeline (Strategy, Uploader) (Week 3)
Community & Analytics Agents (Week 6)
Executive Agents (AI CEO, Chief of Staff) (Week 7)
Quality Checker + Atom Librarian (Week 7)
All 18 agents operational (Week 8)

Phase 3: Autonomous Operations (Weeks 9-12)

Agents produce 80% autonomously (Week 9)
30 videos published, 1K subs, $500 revenue (Week 12)
YouTube Partner Program approved
First B2B inquiry

Phase 4: Scale (Months 4-12)

100 videos published
20K subscribers, $5K/mo revenue
Multi-platform presence (TikTok, Instagram)
Agents fully autonomous (99% without human intervention)

Phase 5: RIVET Launch (Year 1-2)

Industrial maintenance vertical
Reddit monitoring + validation pipeline
B2B integrations (CMMS platforms)

Phase 6: DAAS & Robot Licensing (Year 3-5)

License knowledge bases to enterprises
Humanoid robot training datasets
$10-50M ARR target

See: docs/IMPLEMENTATION_ROADMAP.md for detailed timeline

⭐ Star History

If you find this project useful, please consider giving it a star! ⭐

This helps others discover the project and shows your support for autonomous AI systems.

📊 Project Statistics

Metric	Value
Strategy Docs	7 documents (142KB total)
Code Models	600+ lines (Pydantic v2)
Infrastructure Status	✅ COMPLETE (memory, FREE LLMs, settings)
Session Load Time	<1 second (Supabase)
LLM Costs	$0/month (Ollama integration)
Planned Videos	100+ (sequenced A-to-Z)
Planned Agents	18 (5 teams)
Implementation Timeline	12 weeks to autonomous operations
Revenue Target (Year 3)	$5M ARR (both verticals)
Cost Savings	$2,400-6,000/year (FREE LLMs)

Made with ❤️ and 🤖 by humans and AI agents working together

"The best way to predict the future is to build it autonomously."

Name		Name	Last commit message	Last commit date
Latest commit History 304 Commits
.agent_factory/agents		.agent_factory/agents
.claude		.claude
.githooks		.githooks
.github		.github
.memory		.memory
.scaffold/sessions		.scaffold/sessions
Guides for Users		Guides for Users
agent_factory		agent_factory
agents		agents
backlog		backlog
bin		bin
core		core
data		data
deploy/vps		deploy/vps
docs		docs
examples		examples
factory_templates		factory_templates
migrations		migrations
output/voice_tests		output/voice_tests
plc		plc
scripts		scripts
specs		specs
tests		tests
# AGENTS.md - The Agent Factory Con.txt		# AGENTS.md - The Agent Factory Con.txt
.coderabbit.yaml		.coderabbit.yaml
.env.example		.env.example
.env.production		.env.production
.gitattributes		.gitattributes
.gitignore		.gitignore
ADD_CITATIONS_COLUMN.sql		ADD_CITATIONS_COLUMN.sql
AUTONOMOUS_PLAN.md		AUTONOMOUS_PLAN.md
AUTONOMOUS_SESSION_DEC19.md		AUTONOMOUS_SESSION_DEC19.md
CHANGELOG.md		CHANGELOG.md
CLAUDEUPDATE.md		CLAUDEUPDATE.md
CLAUDEUPDATE_APPLIED.md		CLAUDEUPDATE_APPLIED.md
CLAUDE_START_HERE_UPDATED.md		CLAUDE_START_HERE_UPDATED.md
CONTEXT_HANDOFF_DEC15.md		CONTEXT_HANDOFF_DEC15.md
CONTRIBUTING.md		CONTRIBUTING.md
CURRENT_STATE.md		CURRENT_STATE.md
Claude_12.20.md		Claude_12.20.md
DATABASE_FIXES_COMPLETE.md		DATABASE_FIXES_COMPLETE.md
DECISIONS_LOG.md		DECISIONS_LOG.md
DEPLOYMENT_CHECKLIST.md		DEPLOYMENT_CHECKLIST.md
DEPLOYMENT_COMPLETE_FINAL.md		DEPLOYMENT_COMPLETE_FINAL.md
DEPLOYMENT_COMPLETE_README.md		DEPLOYMENT_COMPLETE_README.md
DEPLOYMENT_QUICK_START.md		DEPLOYMENT_QUICK_START.md
DEPLOYMENT_TODO.md		DEPLOYMENT_TODO.md
DEVELOPMENT_LOG.md		DEVELOPMENT_LOG.md
DEV_OPS_SUMMARY.md		DEV_OPS_SUMMARY.md
DUAL_DATABASE_STATUS.md		DUAL_DATABASE_STATUS.md
Dockerfile		Dockerfile
E2E_TEST_RESULTS.md		E2E_TEST_RESULTS.md
ENV_FILES_GUIDE.md		ENV_FILES_GUIDE.md
EXEC_SUMMARY_DATABASE_FIXES.md		EXEC_SUMMARY_DATABASE_FIXES.md
GITHUB_SECRETS_SETUP.md		GITHUB_SECRETS_SETUP.md
HOSTINGER_VPS_DEPLOYMENT.md		HOSTINGER_VPS_DEPLOYMENT.md
ISSUES_LOG.md		ISSUES_LOG.md
LANGGRAPH_UPGRADE_COMPLETE.md		LANGGRAPH_UPGRADE_COMPLETE.md
LIBRARIES.md		LIBRARIES.md
LICENSE		LICENSE
MANAGEMENT_DASHBOARD_COMPLETE.md		MANAGEMENT_DASHBOARD_COMPLETE.md
NEXT_ACTIONS.md		NEXT_ACTIONS.md
PHASE1_SPEC.md.txt		PHASE1_SPEC.md.txt
PHASE_1_CONVERSATION_MEMORY_COMPLETE.md		PHASE_1_CONVERSATION_MEMORY_COMPLETE.md
PORTFOLIO_INVENTORY.md		PORTFOLIO_INVENTORY.md
PRODUCTION_DEPLOYMENT_COMPLETE.md		PRODUCTION_DEPLOYMENT_COMPLETE.md
PRODUCTS.md		PRODUCTS.md
PROJECT_CONTEXT.md		PROJECT_CONTEXT.md
PROJECT_STRUCTURE.md		PROJECT_STRUCTURE.md
Procfile		Procfile
QUICK_DEPLOY.md		QUICK_DEPLOY.md
RAILWAY_QUICKSTART.md		RAILWAY_QUICKSTART.md
README.md		README.md
README_SEO_AGENT.md		README_SEO_AGENT.md
README_START_HERE.md		README_START_HERE.md
README_YOUTUBE_UPLOADER.md		README_YOUTUBE_UPLOADER.md
RENDER_DEPLOYMENT_FIXES.md		RENDER_DEPLOYMENT_FIXES.md
RENDER_DEPLOYMENT_STATUS.md		RENDER_DEPLOYMENT_STATUS.md
RIVET_PRO_STATUS.md		RIVET_PRO_STATUS.md
SCRIPTWRITER_TEST_FINDINGS.md		SCRIPTWRITER_TEST_FINDINGS.md
SCRIPT_QUALITY_IMPROVEMENTS.md		SCRIPT_QUALITY_IMPROVEMENTS.md
SESSION_HANDOFF_DEC15.md		SESSION_HANDOFF_DEC15.md
SESSION_HANDOFF_DEC16.md		SESSION_HANDOFF_DEC16.md
SESSION_SUMMARY_2025-12-15.md		SESSION_SUMMARY_2025-12-15.md
SESSION_SUMMARY_2025-12-15_INGESTION_CHAIN.md		SESSION_SUMMARY_2025-12-15_INGESTION_CHAIN.md
SESSION_SUMMARY_DEC15_QUALITY_FIX.md		SESSION_SUMMARY_DEC15_QUALITY_FIX.md
SESSION_SUMMARY_DEC15_SCRIPTWRITER.md		SESSION_SUMMARY_DEC15_SCRIPTWRITER.md
STRANGLER_RULES.md		STRANGLER_RULES.md
SUPABASE_COMPLETE_FIX.md		SUPABASE_COMPLETE_FIX.md
SUPABASE_FIX_ACTION_PLAN.md		SUPABASE_FIX_ACTION_PLAN.md
SUPABASE_FIX_INSTRUCTIONS.md		SUPABASE_FIX_INSTRUCTIONS.md
SYSTEM_MANIFEST.md		SYSTEM_MANIFEST.md
SYSTEM_MAP.md		SYSTEM_MAP.md
TASK.md		TASK.md
TELEGRAM_ADMIN_COMPLETE.md		TELEGRAM_ADMIN_COMPLETE.md
WORKTREE_ORGANIZATION_COMPLETE.md		WORKTREE_ORGANIZATION_COMPLETE.md
agentcli.py		agentcli.py
apply_schema_fix.py		apply_schema_fix.py
check_memory.py		check_memory.py
check_tables.py		check_tables.py

License

Mikecranesync/Agent-Factory

Folders and files

Latest commit

History

Repository files navigation

Agent Factory 🏭🤖

📝 Latest Updates

📊 Current Development Status (Week 2, Day 3 Complete)

ISH Swarm Progress: 9/9 Agents Complete (100%)

Day 3 Completion Summary

Knowledge Base Status

🔧 Knowledge Base Ingestion Pipeline (LangGraph)

Week 2 Timeline

🔍 NEW: Perplexity Citation Format Integration

🎯 What We're Building

The Triune Vision

🚀 Current Focus: PLC Tutor Launch (Week 1-12)

✅ Infrastructure Complete (Dec 9-10)

✅ Voice System: Generic TTS Active (Blocker Removed!)

🔴 Remaining User Tasks (Non-blocking for agents)

📅 Next: Week 2 Agent Development

🚀 The YouTube-Wiki Strategy (Week 1-12 Roadmap)

The YouTube-Wiki Strategy

18 Autonomous Agents

📊 Milestones & Success Metrics

Week 4 (Public Launch)

Week 12 (Autonomous Operations)

Month 12 (Scale Achieved)

📚 Documentation (Strategy Suite)

Essential Reading (Start Here)

Technical Documentation

GitHub Issues

📖 User Guides

Quick Start

Deployment

Integration

Development

🤖 GitHub Issue Automation (NEW!)

Quick Start

How It Works

Cost Savings

Features

Requirements

Documentation

Example Output

🛠️ Technology Stack

Core Infrastructure

AI & ML

Media Production

Platforms & APIs

Development Tools

📦 Installation & Setup

Prerequisites

Quick Start

Week 1 Setup (Human Tasks)

🏗️ Project Structure

🤖 Core Data Models (Pydantic v2)

Knowledge Atoms

Content Production

Curriculum Organization

🎓 Content Roadmap: 100+ Videos

Track A: Electrical Fundamentals (Videos 1-20)

Track B: PLC Fundamentals (Videos 21-40)

Track C: Structured Text & Advanced (Videos 41-60)

Track D: Vendor-Specific (Videos 61-80)

Track E: AI & Automation (Videos 81-100)

💰 Business Model & Monetization

Multi-Stream Revenue (PLC Tutor)

Revenue Targets

🔐 Security & Compliance

Security by Design

🤝 Contributing

For Contributors

Development Setup

For AI Agents

📞 Support & Community

📜 License

🙏 Acknowledgments

🗺️ Roadmap

Packages