---
title: Digital Factory
emoji: 🏭
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
---

# 🏭 Digital Factory

AI-powered autonomous software development platform, controlled via Telegram.

The Digital Factory takes a natural-language project description and autonomously plans, codes, validates, and delivers complete software — powered by a team of specialised AI agents and deterministic validation tools.

## Architecture

```
User (Telegram) → Project Manager → SDLC Orchestrator → [Developer, Prompt Engineer]
                                         ↕                        ↕
                                   Memory System              Tool Registry
                                   (SQLite + STM)          (Linter, Validator, GitHub, Files)
```

### Agents (Phase 1 MVP)
| Agent | Role |
|-------|------|
| **SDLC Orchestrator** | Plans projects, dispatches tasks, validates outputs |
| **Project Manager** | Telegram interface, requirement clarification, progress tracking |
| **Software Developer** | Code generation, syntax checking, linting |
| **Prompt Engineer** | Crafts and optimises prompts for other agents |

### Deterministic Tools
- **Pydantic Validator** — Schema validation for all inter-agent contracts (replaces ZOD)
- **Python Linter** — Code quality via `ruff`
- **Syntax Checker** — `py_compile` validation
- **Code Executor** — Sandboxed Python execution
- **File Manager** — Project file I/O
- **GitHub Client** — Repository operations via REST API

### Memory System (4-tier)
| Tier | Implementation | Purpose |
|------|---------------|---------|
| Short-Term | In-memory dict + TTL | Session context, active conversations |
| Project | SQLite | Project specs, plans, code artifacts, task logs |
| Knowledge | (Phase 2) | Vector-based retrieval of best practices |
| User LTM | SQLite | User preferences and feedback |

### Communication
All inter-agent communication uses validated Pydantic models (`TaskRequest` / `TaskResponse`) dispatched through an async in-process message bus.

## Setup

Add these secrets in **Settings → Secrets** (HuggingFace Spaces) or as environment variables:

| Secret | Required | Description |
|--------|----------|-------------|
| `BOT_TOKEN` | Yes | Telegram bot token from @BotFather |
| `ADMIN_ID` | Yes | Your Telegram numeric ID |
| `GROQ_KEY` | Recommended | Groq API key (primary AI provider) |
| `DEEPSEEK_KEY` | Optional | DeepSeek API key (fallback) |
| `HF_TOKEN` | Optional | HuggingFace API token (fallback) |
| `MISTRAL_KEY` | Optional | Mistral API key (fallback) |
| `GH_TOKEN` | Optional | GitHub PAT for repo operations (scope: `repo`, `workflow`) |
| `GH_USER` | Optional | GitHub username |
| `GH_REPO` | Optional | Default repository name |

## Telegram Commands

| Command | Description |
|---------|-------------|
| `/start` | Main menu |
| `/factory` | Start a new project (guided flow) |
| `/projects` | List existing projects |
| `/help` | Feature documentation |
| `/cancel` | Cancel current operation |

Or just send a message — the AI chat mode responds to any text.

## How It Works

1. **You describe a project** — "Build a REST API with FastAPI and SQLite"
2. **Project Manager** clarifies requirements (asks questions if needed)
3. **SDLC Orchestrator** creates a structured plan with tasks
4. **Software Developer** generates and validates code for each task
5. **Files are delivered** as Telegram documents you can download

## Project Structure

```
digital_factory/
├── main.py              # Entry point, Telegram bot setup
├── config.py            # Environment & settings
├── models/              # Pydantic contracts (TaskRequest, ProjectSpec, etc.)
├── agents/              # AI agents (Orchestrator, Developer, PM, Prompt Engineer)
├── tools/               # Deterministic tools (linter, validator, GitHub, files)
├── memory/              # 4-tier memory (short-term, project, knowledge, user LTM)
├── bus/                 # Async message bus
├── telegram_ui/         # Telegram handlers & keyboards
└── utils/               # Helpers (safe_send, truncate)
```

## Legacy GitHub Manager

The original GitHub Manager bot is preserved in `githubbot.py` and includes:

### Repository Management
- 📁 Browse, view, edit, delete & download files
- 📋 View commits with diff details (files changed, additions/deletions)
- 🌿 Create & delete branches
- 🔀 Create PRs with branch selection & merge PRs
- 🔖 Create & close issues
- 🚀 Create releases
- 📊 Repository stats (stars, forks, traffic, clones)
- 🔍 Search across your repositories
- 📤 Upload multiple files via JSON
- ⚡ View GitHub Actions workflow runs & re-run failed workflows

### AI Assistant
- 🤖 Multi-provider AI: Groq, DeepSeek, HuggingFace, Mistral
- 💬 Chat in Arabic & English — just type your message
- 🎤 Voice messages with Whisper transcription + Arabic TTS
- 🛠️ AI can autonomously: read/create/delete files, create PRs, close issues, manage branches, search repos, view workflows

## Deployment

Runs on HuggingFace Spaces as a Docker container. Health check endpoint on port 7860.

```bash
# Local development
pip install -r requirements.txt
python -m digital_factory.main
```

## Roadmap

- **Phase 2**: Additional agents (ML Engineer, Data Analyst, Security, UI/UX Designer)
- **Phase 3**: RAG-based knowledge memory, external database support
- **Phase 4**: Self-Improvement cycle, Board of Directors governance
- **Phase 5**: Full 14-agent deployment with Kafka message bus