# 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

```bash
pip install forge-ai
```

**Python 3.11+ required.**

---

## Onboarding (30 seconds)

First run automatically launches the setup wizard:

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

Or run setup directly:

```bash
forge config
```

You'll be guided to enter:
1. **Groq API key** — [console.groq.com](https://console.groq.com) (free)
2. **NVIDIA NIM key** — [build.nvidia.com](https://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:**
```bash
export GROQ_API_KEY=gsk_...
export NVIDIA_API_KEY=nvapi-...
forge generate "my app"
```

---

## Quick Start

```bash
# 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`

```bash
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:**

```bash
# 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`

```bash
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):

```bash
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:
```bash
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`

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

---

### `forge models`

```bash
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

```python
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](LICENSE)

---

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