grants/AI_INTEGRATION_GUIDE.md

# Atlas Green Morocco — AI / LLM Integration Guide
## Where & How to Use OpenAI Standard Endpoints to Generate Forms & Documentation

**Status:** Architecture specification — ready to implement
**Last updated:** 2026

---

## 1. Executive Summary

The Atlas Green framework already contains a complete, **structured knowledge base** (business models, 8 deployment phases, 8 grant programs, zones, advantages). This is the perfect *grounding context* for an LLM.

What's missing is a **document generation layer**. The playbook references 40+ templates and forms (pitch decks, Lean Canvas, founder agreements, grant applications, financial models, etc.) — but today these are only named, not produced.

**The LLM's job:** turn the founder's inputs + the framework's structured context into ready-to-use, personalized documents and guidance — via the **OpenAI standard REST endpoints**.

> ⚠️ **Critical architectural constraint:** This app builds to a single static `index.html` (via `vite-plugin-singlefile`) served by nginx. There is **no backend**. OpenAI calls require a **secret API key that must never ship to the browser**. You **must** add a thin server-side proxy (serverless function or small Node service). See §5.

---

## 2. The Document Catalog (What the LLM Will Generate)

These are extracted directly from the `resources[]` arrays in `src/data/deployment.ts` and `src/data/grants.ts`, grouped by phase.

### Phase 0 — Foundation
- Business model comparison memo (scored to the founder's situation)
- Customer discovery **interview script** + question bank
- Competitive analysis worksheet
- Lean Canvas (1-page)
- Lean business plan (15–20 pages)
- Advisor outreach / recruitment messages

### Phase 1 — Legal & Incorporation
- SARL/SAS incorporation checklist + document list
- Foreign holding structure memo (UAE / NL / LUX / EE comparison)
- Founder agreement draft (roles, vesting, equity split)
- IP assignment agreement draft
- Advisor agreement draft

### Phase 2 — MVP
- Product roadmap (8-week sprint plan)
- Feature prioritization matrix
- Job descriptions (devs, PM, designer)
- Pilot customer agreement + feedback survey

### Phase 3 — Revenue
- Pricing strategy memo (SaaS / usage / services)
- Sales playbook (discovery → demo → close)
- Cold email sequences + LinkedIn outreach scripts
- Case study draft (from customer notes)
- SLA / contract templates

### Phase 4–5 — Scale & Seed
- **Investor pitch deck** (15–20 slide outline + copy)
- 3–5 year **financial model** assumptions + projections
- Cap table scenarios
- Investor shortlist + warm-intro request emails
- SAFE / term-sheet explainer

### Grants (cross-phase) — **highest unique value**
- **IRESEN / Horizon Europe / EBRD / AfDB grant applications** drafted to each program's eligibility & process
- Consortium partner outreach (academic + industrial)
- Impact & KPI narrative (carbon, jobs, MW, m³ water)
- Budget justification narrative

---

## 3. Recommended AI Features (Ranked by ROI)

| # | Feature | Endpoint pattern | Why it wins |
|---|---|---|---|
| 1 | **Grant Application Drafter** | Structured chat + JSON schema | Highest pain, highest value; framework already has exact eligibility/process per program |
| 2 | **Pitch Deck Generator** | Chat → structured slides JSON | Every founder needs it; reuse business model + traction inputs |
| 3 | **Financial Model Assistant** | Function calling → numeric JSON | Produces assumptions & projections the UI can render as tables/charts |
| 4 | **"Ask the Playbook" RAG chatbot** | Embeddings + chat | Answers "what do I do in Phase 3?" grounded in your docs |
| 5 | **Document Drafter** (legal/sales/HR) | Chat with template system prompt | One engine, many templates from the catalog above |
| 6 | **Readiness Diagnostic** | Structured outputs (scorecard) | Scores founder against phase checkpoints, recommends next actions |
| 7 | **Interview/Email co-pilot** | Lightweight chat | Fast, cheap, daily-use utility |

---

## 4. Which OpenAI Endpoints to Use

Use the **standard OpenAI REST API**. Three building blocks cover everything:

### 4.1 Chat / text generation — `POST /v1/chat/completions`
The workhorse for drafting documents.
- Models: `gpt-4o` (quality, long docs) / `gpt-4o-mini` (cheap, high-volume drafts & chat).
- Use `response_format: { type: "json_schema", ... }` (**Structured Outputs**) whenever the UI must render the result (decks, scorecards, financial rows).

### 4.2 Function / tool calling
For deterministic, typed outputs the app consumes programmatically (e.g., financial line items, a slide array, a grant-fit score). Define tools with a strict JSON schema and `strict: true`.

### 4.3 Embeddings — `POST /v1/embeddings`
For the "Ask the Playbook" RAG chatbot.
- Model: `text-embedding-3-small`.
- Embed your markdown docs + `data.ts`/`deployment.ts`/`grants.ts` content once, store vectors, retrieve top-k chunks per question, then pass to chat.

> The newer **Responses API** (`POST /v1/responses`) is also fine and is OpenAI's recommended default going forward — same concepts (structured outputs, tools). Chat Completions is shown here because it's the most widely documented "standard" surface.

---

## 5. Architecture (No Key in the Browser)

```
Browser (this React app, static)
        │  fetch('/api/ai/generate', { prompt, context })
        ▼
Thin Proxy  (serverless function OR small Node/Express service)
  - holds OPENAI_API_KEY (env var, server-side only)
  - injects framework context (system prompt)
  - rate-limits / authenticates the user
  - calls OpenAI
        │
        ▼
OpenAI API  (/v1/chat/completions, /v1/embeddings)
```

**Deployment options that fit your current setup:**
- **Vercel / Netlify Functions** — easiest; drop `/api/*.ts` handlers, set `OPENAI_API_KEY` in dashboard. (Note: you'd move off pure single-file build for these routes.)
- **Cloudflare Workers** — cheap, global, great for a proxy.
- **Small Node/Express container** behind the same nginx (`location /api/ { proxy_pass ... }`). Fits your existing Docker/nginx deployment cleanly.

**Never** put the key in `import.meta.env` that reaches the client. Anything prefixed for the client bundle is public.

---

## 6. Grounding the LLM in the Framework (Prompt Pattern)

The reason this works so well: you already have the context. Inject it.

**System prompt skeleton (server-side):**
```
You are the Atlas Green Morocco co-pilot. You help founders build renewable
energy / green-hydrogen businesses in Morocco.

GROUND TRUTH (do not contradict):
- Strategy: "Don't produce hydrogen; enable the hydrogen economy."
- Business models: {{businessModels}}
- Deployment phases 0–7: {{deploymentStages}}
- Grant programs: {{grantPrograms}}   // IRESEN, Horizon Europe, EBRD GEFF, AfDB SEFA, AECF, TAMWILCOM, Maroc PME

RULES:
- Use ONLY Morocco/EU/Africa facts present in the context for grants
  (amounts, eligibility, TRL). If unknown, say so — never invent figures.
- Match output to the founder's selected business model and phase.
- Output must follow the provided JSON schema exactly.
```

You can serialize the existing `data.ts`, `deployment.ts`, and `grants.ts` objects straight into `{{...}}`. That single move makes every generated document on-brand and consistent with the playbook.

---

## 7. Worked Example — Grant Application Drafter (Feature #1)

**Client request → proxy:**
```json
{
  "feature": "grant_drafter",
  "grantId": "iresen-innoboost",
  "founder": {
    "businessModel": "Energy Software / AI",
    "product": "AI predictive-maintenance platform for solar farms",
    "stage": "Phase 2 (MVP)",
    "team": "2 founders + 3 engineers",
    "academicPartner": "UM6P / Green Energy Park (in discussion)"
  }
}
```

**Proxy → OpenAI (`/v1/chat/completions`)** with Structured Outputs:
```jsonc
{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "<system prompt + grants.ts context>" },
    { "role": "user", "content": "Draft an IRESEN Green Inno-Boost application for this founder: {…}" }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "grant_application",
      "strict": true,
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "programName": { "type": "string" },
          "eligibilityCheck": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "criterion": { "type": "string" },
                "met": { "type": "boolean" },
                "note": { "type": "string" }
              },
              "required": ["criterion", "met", "note"]
            }
          },
          "projectSummary": { "type": "string" },
          "innovationStatement": { "type": "string" },
          "impactKpis": { "type": "array", "items": { "type": "string" } },
          "budgetNarrative": { "type": "string" },
          "consortiumPlan": { "type": "string" },
          "missingInfo": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["programName","eligibilityCheck","projectSummary",
          "innovationStatement","impactKpis","budgetNarrative",
          "consortiumPlan","missingInfo"]
      }
    }
  }
}
```

The UI renders `eligibilityCheck` as a ✅/❌ table, the narratives as editable text blocks, and `missingInfo` as a to-do list. Because grant facts come from `grants.ts`, amounts/TRL/eligibility stay accurate.

---

## 8. Worked Example — Pitch Deck Generator (Feature #2)

Return a typed slide array the app renders into a deck preview + export:
```jsonc
"schema": {
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "slides": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "title": { "type": "string" },
          "headline": { "type": "string" },
          "bullets": { "type": "array", "items": { "type": "string" } },
          "speakerNotes": { "type": "string" }
        },
        "required": ["title","headline","bullets","speakerNotes"]
      }
    }
  },
  "required": ["slides"]
}
```
Seed it with the canonical 11-slide order (Problem, Solution, Market, Product, Traction, Business Model, Grants/Non-dilutive, Competition, Team, Financials, Ask).

---

## 9. Cost & Performance Notes

- **Drafting one document** ≈ 2–8K output tokens. With `gpt-4o-mini` this is fractions of a cent; with `gpt-4o`, a few cents. Default to **mini for drafts**, offer **4o for the final polish**.
- **Stream** long documents (`stream: true`) so founders see text appear immediately.
- **Cache** the serialized framework context; it's the same on every call.
- **Embeddings** are one-time per doc change — embed the playbook once, store vectors (pgvector / SQLite / a hosted vector DB).
- Add server-side **rate limits** per user and a monthly token budget to avoid surprises.

---

## 10. Data Privacy & Compliance (matters for your EU audience)

- Founder business plans are sensitive. Use OpenAI's **API** (data not used for training by default) and state this in your privacy policy.
- For EU founders, document data flow for **GDPR**; consider EU data residency options.
- Let users **delete** generated documents and inputs.
- Never log raw API keys or full prompts containing secrets.

---

## 11. Suggested Implementation Roadmap

**Phase A — Proxy + 1 feature (1–2 weeks)**
1. Add `/api/ai/generate` serverless function holding `OPENAI_API_KEY`.
2. Serialize `data.ts` + `grants.ts` into the system prompt.
3. Ship **Grant Application Drafter** (Feature #1) with Structured Outputs.
4. New UI: a "✨ Draft with AI" button inside each card in `GrantsSection.tsx`.

**Phase B — Document engine (2–3 weeks)**
5. Generalize the proxy to a `feature` switch (grant, deck, doc, financial).
6. Add **Pitch Deck Generator** + **Document Drafter** (legal/sales/HR templates).
7. Add a "My Documents" area (localStorage first, then a DB).

**Phase C — RAG co-pilot (2–3 weeks)**
8. Embed all markdown + data files; store vectors.
9. Ship **"Ask the Playbook"** chat (floating widget) with retrieval + streaming.
10. Add **Readiness Diagnostic** scorecard against phase checkpoints.

---

## 12. Quick Reference — Endpoint Cheat Sheet

| Need | Endpoint | Model | Key option |
|---|---|---|---|
| Draft a document | `/v1/chat/completions` | `gpt-4o-mini` → `gpt-4o` | `response_format: json_schema` |
| Typed data (slides, finance rows, scores) | `/v1/chat/completions` | `gpt-4o` | tools / `strict: true` |
| Long doc UX | `/v1/chat/completions` | any | `stream: true` |
| RAG chatbot retrieval | `/v1/embeddings` | `text-embedding-3-small` | batch embed once |
| (Optional) modern default | `/v1/responses` | `gpt-4o` | structured outputs + tools |

---

### Bottom line
The framework is **content-complete** and already structured as ideal LLM grounding. To "build out the forms and documentation," add a **thin server proxy** + **Structured-Output generation**, and start with the **Grant Application Drafter** — the feature where your unique Morocco/EU/Africa grant data creates the biggest, hardest-to-copy advantage.