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:

{
  "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:

{
  "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:

"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.