FORGE AI v2.0

  ███████╗ ██████╗ ██████╗  ██████╗ ███████╗
  ██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
  █████╗  ██║   ██║██████╔╝██║  ███╗█████╗
  ██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝
  ██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗
  ╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝

Production-grade AI mobile app generator. One prompt → complete React Native + Expo project.

Powered by Groq LLaMA 3.3 70B (planning) + NVIDIA NIM CodeLlama 70B (code generation) + Telegram delivery.

---

What This Is

FORGE is a 6-agent autonomous pipeline that takes a plain-English app description and produces a complete, runnable React Native + Expo codebase — TypeScript throughout, real AsyncStorage persistence, real navigation, real UI, Jest tests, GitHub Actions CI/CD.

This is not:

• A demo with hardcoded screens
• A prototype with placeholder text
• A scaffolding tool that gives you boilerplate

This is:

• A Manus-level agentic system that reasons about your app holistically
• A code generator that writes real business logic, not TODO stubs
• A full-stack mobile dev teammate that outputs ship-ready code

---

Install

pip install forge-ai

Python 3.11+ required.

---

Onboarding (30 seconds)

First run automatically launches the setup wizard:

forge generate "my app idea"
# → Detects no API keys → Launches wizard

Or run setup directly:

forge config

You'll be guided to enter:

1. Groq API key — console.groq.com (free)
2. NVIDIA NIM key — build.nvidia.com (free credits)
3. Telegram bot (optional) — generate from your phone
4. Preferences — complexity, output dir

Keys are stored in ~/.forge/config.json (chmod 600).

Alternative — env vars:

export GROQ_API_KEY=gsk_...
export NVIDIA_API_KEY=nvapi-...
forge generate "my app"

---

Quick Start

# Generate a standard app (7 screens)
forge generate "A habit tracker with daily streaks, reminders, and analytics"

# Run it
cd habit-tracker
npm install
npx expo start

Scan the QR code with Expo Go on your phone. That's it.

---

Commands

forge generate

forge generate [PROMPT] [OPTIONS]

Options:
  --output, -o PATH        Output directory (default: .)
  --complexity, -c TEXT    minimal|standard|full|enterprise
  --typescript/--javascript
  --tests/--no-tests       Generate Jest test suite (default: yes)
  --ci/--no-ci             Generate GitHub Actions CI (default: yes)
  --skip-validation        Skip Agent 4 (faster, less reliable)
  --dry-run                Plan only, no code generation
  --plan-model TEXT        Groq model override
  --code-model TEXT        NVIDIA NIM model override
  --groq-key TEXT          Override Groq API key
  --nvidia-key TEXT        Override NVIDIA key
  --yes, -y                Skip confirmation
  --debug                  Show full tracebacks

Examples:

# Minimal (4 screens) - fastest
forge generate "Simple todo app" -c minimal

# Full (12 screens) - feature-rich
forge generate "Fitness app with workouts, nutrition, and social features" -c full

# Enterprise (18 screens)
forge generate "B2B SaaS project management platform" -c enterprise

# Dry run - see the plan without spending API credits
forge generate "My app" --dry-run

# Skip tests and CI for speed
forge generate "Quick prototype" --no-tests --no-ci --skip-validation

# Custom output
forge generate "Recipe app" -o ~/projects/my-apps

# Inline API keys (CI/CD)
forge generate "App" --groq-key gsk_... --nvidia-key nvapi-...

---

forge config

forge config              # Full interactive setup wizard
forge config --show       # Show current config (masks keys)
forge config --reset      # Reset to defaults

# Non-interactive key updates
forge config --groq-key gsk_...
forge config --nvidia-key nvapi-...
forge config --tg-token 123:ABC...
forge config --tg-chat-id 987654321

---

forge telegram

Start the Telegram bot (interactive generation from your phone):

forge telegram
# → Bot starts polling
# → Open Telegram, send /start to your bot
# → Send /generate <your app idea>
# → Receive live progress updates
# → Receive the .zip when done

Env vars:

export TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
export TELEGRAM_CHAT_ID=987654321
forge telegram

Telegram Bot Commands:

• /generate <prompt> — Start generation
• /status — Check active session
• /cancel — Cancel generation
• /config — View settings
• /doctor — Test API connections
• /help — Full help

---

forge doctor

forge doctor
# Tests: Groq API, NVIDIA NIM, Telegram bot
# Shows pass/fail for each

---

forge models

forge models
# Lists all available models and which are currently active

---

The 6-Agent Pipeline

Your Prompt
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent 1: PLANNER  [Groq → LLaMA 3.3 70B]                 │
│  • Parses prompt → full structured app specification        │
│  • Defines: screens, data models, user stories, features    │
│  • Chooses: navigation, storage, auth, colors, deps         │
│  • Identifies clarifying questions if prompt is ambiguous   │
│  • Outputs: typed AppPlan dataclass                         │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent 2: ARCHITECT  [Groq → LLaMA 3.3 70B]               │
│  • Designs professional src/ directory layout               │
│  • Maps imports/exports between all files                   │
│  • Plans: screens, components, hooks, services, types       │
│  • Outputs: file manifest with types, purposes, deps        │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent 3: CODE GEN  [NVIDIA NIM → CodeLlama 70B]           │
│  • Generates every file individually with full context      │
│  • Real TypeScript: no any, proper interfaces, generics     │
│  • Real persistence: AsyncStorage CRUD operations           │
│  • Real navigation: typed useNavigation, route params       │
│  • Real UI: StyleSheet, FlatList, SafeAreaView, animations  │
│  • Real states: loading, error, empty handled everywhere    │
│  • Auto-falls back to Groq if NVIDIA unavailable           │
│  • Static generators for config files (100% correct)        │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent 4: VALIDATOR  [Groq → LLaMA 3.3 70B]               │
│  • Reviews entry point, navigation, context, services       │
│  • Fixes: wrong imports, broken navigation, type errors     │
│  • Detects placeholder content that slipped through         │
│  • Ensures consistent imports across the codebase           │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent 5: TESTER  [Groq → LLaMA 3.3 70B]                  │
│  • Writes Jest + React Native Testing Library test suites   │
│  • Tests: happy path, empty state, error, user interactions │
│  • Mocks: AsyncStorage, Navigation, Expo modules            │
│  • Adds jest.setup.ts with global mocks                     │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent 6: PACKAGER  [local]                                │
│  • Writes all files to disk under project directory         │
│  • Creates .zip archive for download/Telegram delivery      │
│  • Generates GitHub Actions CI/CD workflow                  │
│  • Generates EAS Build config for app store submission      │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
             📦 project.zip → Telegram → You

---

Output Structure

my-app/
├── App.tsx                         ← Entry + navigation setup
├── app.json                        ← Expo config (name, bundle ID, icons)
├── package.json                    ← All dependencies with correct versions
├── tsconfig.json                   ← TypeScript strict config
├── babel.config.js                 ← Babel + module-resolver
├── eas.json                        ← EAS Build profiles (dev/preview/prod)
├── .gitignore
├── .env.example
├── README.md
├── .github/workflows/ci.yml        ← GitHub Actions (test + lint + EAS build)
├── __tests__/
│   ├── HomeScreen.test.tsx
│   ├── AppContext.test.tsx
│   └── ...
├── jest.setup.ts
└── src/
    ├── navigation/
    │   └── AppNavigator.tsx        ← Typed Stack/Tab/Drawer navigator
    ├── screens/
    │   ├── HomeScreen.tsx
    │   ├── DetailScreen.tsx
    │   └── ... (all screens)
    ├── components/
    │   ├── ui/
    │   │   ├── Button.tsx
    │   │   ├── Card.tsx
    │   │   ├── EmptyState.tsx
    │   │   ├── LoadingSpinner.tsx
    │   │   ├── Header.tsx
    │   │   └── Modal.tsx
    │   └── [feature]/
    ├── context/
    │   └── AppContext.tsx           ← Global state (useReducer + AsyncStorage)
    ├── hooks/
    │   ├── useApp.ts
    │   └── useStorage.ts
    ├── services/
    │   └── storage.ts               ← AsyncStorage CRUD abstraction
    ├── utils/
    │   └── helpers.ts
    ├── constants/
    │   ├── theme.ts                 ← Colors, spacing, typography
    │   └── index.ts
    └── types/
        └── index.ts                 ← All TypeScript interfaces

---

Python API

import asyncio
from forge import Pipeline
from forge.settings import Settings

settings = Settings.load()
pipeline = Pipeline(settings)

async def main():
    session = await pipeline.run(
        prompt="A workout tracker with exercises, sets, reps, and history",
        on_log=lambda entry: print(f"[{entry.agent}] {entry.message}"),
    )

    print(f"Generated: {session.total_files} files, {session.total_lines:,} lines")
    print(f"Location: {session.project_dir}")
    print(f"Zip: {session.zip_path}")
    print(f"Time: {session.elapsed:.1f}s")

asyncio.run(main())

---

Complexity Levels

Level	Screens	Time	Best For
minimal	4	~2 min	Quick prototypes
standard	7	~4 min	Solid apps (default)
full	12	~7 min	Feature-rich products
enterprise	18	~12 min	Full products

---

What Makes the Code "Real"

✅ Production	❌ Demo/Prototype
AsyncStorage CRUD with error handling	Hardcoded data arrays
Typed useNavigation with route params	Alert("navigate")
FlatList with real data	ScrollView + static items
Loading states (ActivityIndicator)	Instant renders
Empty states (EmptyState component)	Hidden when empty
Form validation with inline errors	Console.log on submit
useReducer global state	useState everywhere
TypeScript strict (no any)	Plain JavaScript
Platform.OS differences handled	iOS-only style
Haptic feedback on actions	No feedback
date-fns for dates	new Date().toString()
Jest test suite	No tests
GitHub Actions CI	No CI

---

Requirements

• Python 3.11+
• Groq API key (free at console.groq.com)
• NVIDIA NIM API key (free credits at build.nvidia.com)
• Node.js 18+ (to run generated apps)
• Expo Go app (to preview on device)

---

License

MIT — see LICENSE

---

FORGE AI — because building mobile apps should be fast, not tedious.