Sync from GitHub · 2026-06-25 17:24 UTC

.env.example

@@ -0,0 +1,12 @@
+# VenThrive FastAPI Backend — Environment Variables
+# Copy to .env and fill in values (same source as frontend .env.local)
+
+GROQ_API_KEY=
+FIREBASE_SERVICE_ACCOUNT=   # JSON string from Firebase Console → Project Settings → Service Accounts
+
+# CORS: comma-separated list of allowed origins
+ALLOWED_ORIGINS=http://localhost:3000,https://venthrive.com
+
+# Optional: Pinecone (used in Stage 6 when AI Chat is built)
+PINECONE_API_KEY=
+PINECONE_INDEX_NAME=venthrive-bff

.gitattributes

@@ -1,35 +0,0 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies first (cached layer)
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy source
+COPY . .
+
+# HF Spaces routes traffic to port 7860.
+# Cloud Run uses $PORT (default 8080). Both work via the PORT env var.
+ENV PORT=7860
+EXPOSE 7860
+
+CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port ${PORT}"]

README.md

@@ -1,10 +1,16 @@
 ---
-title: Venthrive Api
-emoji: 🌖
-colorFrom: green
+title: VenThrive API
+emoji: 🟠
+colorFrom: red
 colorTo: yellow
 sdk: docker
+app_port: 7860
 pinned: false
+short_description: FastAPI backend for VenThrive business platform
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# VenThrive API
+
+FastAPI backend for the VenThrive AI-powered business operating system.
+
+All endpoints require a valid Firebase ID token (`Authorization: Bearer <token>`).

auth.py

@@ -0,0 +1,31 @@
+from fastapi import Header, HTTPException, Depends
+from firebase_admin import auth as firebase_auth
+
+
+async def verify_firebase_token(authorization: str = Header(...)) -> dict:
+    """
+    FastAPI dependency that verifies a Firebase ID token from the
+    Authorization: Bearer <token> header.
+
+    Returns the decoded token payload (contains uid, email, etc.).
+    Raises 401 if the token is missing, malformed, or expired.
+
+    All protected routes must declare:  user = Depends(verify_firebase_token)
+    """
+    if not authorization.startswith("Bearer "):
+        raise HTTPException(
+            status_code=401,
+            detail="Authorization header must be 'Bearer <token>'",
+        )
+
+    id_token = authorization.removeprefix("Bearer ").strip()
+
+    try:
+        decoded = firebase_auth.verify_id_token(id_token)
+        return decoded
+    except firebase_auth.ExpiredIdTokenError:
+        raise HTTPException(status_code=401, detail="Token has expired. Please sign in again.")
+    except firebase_auth.InvalidIdTokenError:
+        raise HTTPException(status_code=401, detail="Invalid token.")
+    except Exception:
+        raise HTTPException(status_code=401, detail="Authentication failed.")

main.py

@@ -0,0 +1,108 @@
+import os
+import json
+from contextlib import asynccontextmanager
+
+# ─── Load environment FIRST — before any local imports that read env vars ─────
+# Routes instantiate Groq/Firebase clients at module level, so env vars must
+# be present before those modules are imported.
+from dotenv import load_dotenv
+load_dotenv()
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+import firebase_admin
+from firebase_admin import credentials
+
+from routes import bff, chat, transcribe, documents, consultation, planning, admin
+
+
+# ─── Firebase Admin SDK initialisation ───────────────────────────────────────
+def _init_firebase():
+    if firebase_admin._apps:
+        return  # already initialised (e.g. during hot-reload)
+
+    sa_json = os.environ.get("FIREBASE_SERVICE_ACCOUNT")
+    if sa_json:
+        try:
+            cred_dict = json.loads(sa_json)
+            cred = credentials.Certificate(cred_dict)
+        except json.JSONDecodeError as e:
+            raise RuntimeError(f"FIREBASE_SERVICE_ACCOUNT is not valid JSON: {e}")
+    else:
+        # Fall back to application default credentials (GCP environment)
+        cred = credentials.ApplicationDefault()
+
+    firebase_admin.initialize_app(cred)
+
+
+_init_firebase()
+
+
+# ─── Rate limiter ─────────────────────────────────────────────────────────────
+limiter = Limiter(key_func=get_remote_address, default_limits=["60/minute"])
+
+
+# ─── App lifecycle ────────────────────────────────────────────────────────────
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    print("VenThrive API starting up...")
+    yield
+    print("VenThrive API shutting down.")
+
+
+# ─── FastAPI app ──────────────────────────────────────────────────────────────
+app = FastAPI(
+    title="VenThrive API",
+    version="1.0.0",
+    description="AI backend for VenThrive — Nigerian business operating system",
+    # Disable auto-generated docs in production
+    docs_url="/docs" if os.environ.get("ENV") != "production" else None,
+    redoc_url=None,
+    lifespan=lifespan,
+)
+
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+
+# ─── CORS ─────────────────────────────────────────────────────────────────────
+allowed_origins_str = os.environ.get("ALLOWED_ORIGINS", "http://localhost:3000")
+allowed_origins = [o.strip() for o in allowed_origins_str.split(",")]
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=allowed_origins,
+    allow_credentials=True,
+    allow_methods=["GET", "POST"],
+    allow_headers=["Authorization", "Content-Type"],
+)
+
+
+# ─── Global error handler ─────────────────────────────────────────────────────
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    # Never expose internal error details to the client in production
+    return JSONResponse(
+        status_code=500,
+        content={"detail": "An unexpected error occurred. Please try again."},
+    )
+
+
+# ─── Routes ───────────────────────────────────────────────────────────────────
+app.include_router(bff.router,        prefix="/api/bff",       tags=["BFF"])
+app.include_router(chat.router,       prefix="/api/chat",      tags=["Chat"])
+app.include_router(transcribe.router, prefix="/api",           tags=["Transcribe"])
+app.include_router(documents.router,     prefix="/api/documents",    tags=["Documents"])
+app.include_router(consultation.router, prefix="/api/consultation", tags=["Consultation"])
+app.include_router(planning.router,     prefix="/api/planning",     tags=["Planning"])
+app.include_router(admin.router,        prefix="/api/admin",        tags=["Admin"])
+
+
+# ─── Health check (unauthenticated) ──────────────────────────────────────────
+@app.get("/health", tags=["System"])
+def health_check():
+    return {"status": "ok", "service": "venthrive-api"}

requirements.txt

@@ -0,0 +1,13 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.6
+python-dotenv==1.0.1
+firebase-admin==6.5.0
+groq==0.11.0
+slowapi==0.1.9
+python-multipart==0.0.12
+pydantic==2.9.2
+httpx==0.27.2
+# Pinecone vector database (v9+ includes built-in Inference API — no local ML needed)
+pinecone>=9.0.0
+# PDF text extraction for book ingestion script (pure Python, Windows-compatible)
+pypdf>=4.0.0

routes/admin.py

@@ -0,0 +1,136 @@
+"""
+Admin Routes — Protected by admin role verification
+──────────────────────────────────────────────────────────────────────────────
+All admin actions use Firebase Admin SDK (bypasses Firestore rules).
+The requesting user must have role: 'admin' in their Firestore document.
+
+Routes:
+  GET  /api/admin/users           → list all users (paginated)
+  PUT  /api/admin/users/{uid}     → update locked fields (fullName, phone, role)
+  DELETE /api/admin/users/{uid}   → delete user account + Firestore data
+  GET  /api/admin/stats           → platform overview stats
+"""
+
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel
+from firebase_admin import auth as fb_auth, firestore
+from auth import verify_firebase_token
+
+router = APIRouter()
+
+
+def _verify_admin(user: dict) -> str:
+    """Verifies the requesting user has role: 'admin'. Returns their UID."""
+    uid = user.get("uid")
+    if not uid:
+        raise HTTPException(status_code=401, detail="Unauthorized.")
+    db   = firestore.client()
+    doc  = db.collection("user_data").document(uid).get()
+    role = doc.to_dict().get("role", "user") if doc.exists else "user"
+    if role != "admin":
+        raise HTTPException(status_code=403, detail="Admin access required.")
+    return uid
+
+
+class UpdateUserRequest(BaseModel):
+    fullName: str | None = None
+    phone:    str | None = None
+    role:     str | None = None  # only 'user' or 'admin'
+
+
+@router.get("/users")
+def list_users(
+    limit: int = 50,
+    user: dict = Depends(verify_firebase_token),
+):
+    _verify_admin(user)
+    db   = firestore.client()
+    docs = db.collection("user_data").limit(limit).stream()
+    users = []
+    for doc in docs:
+        d = doc.to_dict()
+        users.append({
+            "uid":       doc.id,
+            "fullName":  d.get("fullName", ""),
+            "email":     d.get("email", ""),
+            "phone":     d.get("phone", ""),
+            "role":      d.get("role", "user"),
+            "xpTotal":   d.get("xpTotal", 0),
+            "createdAt": str(d.get("createdAt", "")),
+        })
+    return {"users": users, "count": len(users)}
+
+
+@router.put("/users/{target_uid}")
+def update_user(
+    target_uid: str,
+    body: UpdateUserRequest,
+    user: dict = Depends(verify_firebase_token),
+):
+    _verify_admin(user)
+
+    if body.role and body.role not in ("user", "admin"):
+        raise HTTPException(status_code=400, detail="role must be 'user' or 'admin'")
+
+    db      = firestore.client()
+    updates = {}
+    if body.fullName is not None: updates["fullName"] = body.fullName
+    if body.phone    is not None: updates["phone"]    = body.phone
+    if body.role     is not None: updates["role"]     = body.role
+
+    if not updates:
+        raise HTTPException(status_code=400, detail="Nothing to update.")
+
+    db.collection("user_data").document(target_uid).update(updates)
+
+    # Sync display name to Firebase Auth if fullName changed
+    if body.fullName:
+        try:
+            fb_auth.update_user(target_uid, display_name=body.fullName)
+        except Exception:
+            pass  # non-critical
+
+    return {"success": True, "updated": list(updates.keys())}
+
+
+@router.delete("/users/{target_uid}")
+def delete_user(
+    target_uid: str,
+    user: dict = Depends(verify_firebase_token),
+):
+    admin_uid = _verify_admin(user)
+    if target_uid == admin_uid:
+        raise HTTPException(status_code=400, detail="Admins cannot delete their own account.")
+
+    db = firestore.client()
+
+    # Delete Firestore user data (businesses subcollection + root doc)
+    user_ref = db.collection("user_data").document(target_uid)
+    biz_docs = user_ref.collection("businesses").stream()
+    for biz in biz_docs:
+        # Delete nested subcollections of each business
+        for sub in ["bff", "profile_output", "documents", "kanban", "milestones", "sessions", "team"]:
+            for sdoc in biz.reference.collection(sub).stream():
+                sdoc.reference.delete()
+        biz.reference.delete()
+    user_ref.delete()
+
+    # Delete Firebase Auth account
+    try:
+        fb_auth.delete_user(target_uid)
+    except fb_auth.UserNotFoundError:
+        pass  # already deleted
+
+    return {"success": True, "deleted": target_uid}
+
+
+@router.get("/stats")
+def platform_stats(user: dict = Depends(verify_firebase_token)):
+    _verify_admin(user)
+    db         = firestore.client()
+    user_count = len(list(db.collection("user_data").stream()))
+    # Count businesses across all users (approximate - stream limit applies)
+    return {
+        "totalUsers":   user_count,
+        "note": "Deep counts require Cloud Functions — this shows top-level totals only."
+    }

routes/bff.py

@@ -0,0 +1,323 @@
+import json
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel
+from firebase_admin import firestore
+from auth import verify_firebase_token
+from utils.groq_client import call_groq_json, HEAVY_MODEL
+from utils.pinecone_client import query_book_context
+
+router = APIRouter()
+
+
+# ─── Request schemas ──────────────────────────────────────────────────────────
+
+class GenerateFollowupsRequest(BaseModel):
+    businessId: str
+    section: int          # 1, 2, or 3
+    sectionData: dict
+
+
+class GenerateProfileRequest(BaseModel):
+    userId: str
+    businessId: str
+
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+def _db():
+    return firestore.client()
+
+
+def _get_bff_data(user_id: str, business_id: str) -> dict:
+    """Reads all BFF sections from Firestore for a given business."""
+    db = _db()
+    biz_ref = (
+        db.collection("user_data")
+        .document(user_id)
+        .collection("businesses")
+        .document(business_id)
+    )
+    sections = {}
+    for section_id in [
+        "section1", "section1_followups",
+        "section2", "section2_followups",
+        "section3", "section3_followups",
+    ]:
+        doc = biz_ref.collection("bff").document(section_id).get()
+        if doc.exists:
+            sections[section_id] = doc.to_dict()
+    return sections
+
+
+def _call_groq_json(system_prompt: str, user_prompt: str) -> dict:
+    """Thin wrapper — delegates to the key-rotating Groq client utility."""
+    return call_groq_json(system_prompt, user_prompt, model=HEAVY_MODEL, max_tokens=1500)
+
+
+# ─── Route: Generate follow-up questions ─────────────────────────────────────
+
+@router.post("/generate-followups")
+def generate_followups(
+    body: GenerateFollowupsRequest,
+    user: dict = Depends(verify_firebase_token),
+):
+    """
+    After each BFF section is submitted, generates 3–5 personalized
+    follow-up questions specific to the user's sector and answers.
+    Questions use plain English — no business jargon.
+    """
+    if body.section not in (1, 2, 3):
+        raise HTTPException(status_code=400, detail="section must be 1, 2, or 3.")
+
+    section_names = {1: "WHAT (identity)", 2: "WHY (purpose)", 3: "HOW (operations)"}
+
+    # Fetch relevant BFF philosophy passages from "Built on Rock"
+    bff_query = f"Business Footing Framework section {body.section} {json.dumps(body.sectionData)[:200]}"
+    book_ctx   = query_book_context(bff_query, top_k=2)
+
+    system_prompt = (
+        "You are a business consultant helping a Nigerian entrepreneur understand their business better. "
+        "Generate follow-up questions based on what they have already shared. "
+        "Questions MUST use simple, everyday English — no business jargon. "
+        "Think: how would a friendly, experienced mentor ask? "
+        "Return ONLY valid JSON."
+        + (f"\n\n{book_ctx}" if book_ctx else "")
+    )
+
+    user_prompt = f"""
+The entrepreneur just completed Section {body.section} ({section_names[body.section]}) of their Business Footing Framework.
+
+Their answers:
+{json.dumps(body.sectionData, indent=2)}
+
+Generate 3-5 follow-up questions to deepen understanding of their business.
+Make each question specific to what they shared — do not ask generic questions.
+
+Return JSON in this exact format:
+{{
+  "questions": [
+    {{
+      "id": "q1",
+      "question": "...",
+      "type": "text",
+      "placeholder": "..."
+    }}
+  ]
+}}
+
+Question types:
+- "text"        → free-text answer (use for open questions)
+- "select"      → single choice, add "options": ["Option A", "Option B", ...]
+- "multiselect" → multiple choice, add "options": [...]
+- "boolean"     → yes/no question
+"""
+
+    try:
+        data = _call_groq_json(system_prompt, user_prompt)
+        return data
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Follow-up generation failed: {str(e)}")
+
+
+# ─── Route: Generate full business profile ────────────────────────────────────
+
+@router.post("/generate-profile")
+def generate_profile(
+    body: GenerateProfileRequest,
+    user: dict = Depends(verify_firebase_token),
+):
+    """
+    Reads all completed BFF sections from Firestore and generates all 4
+    profile outputs in parallel (Business Identity, Customer Profile,
+    Market Data, Business Model). Saves results back to Firestore and
+    marks bffCompleted = True on the business document.
+    """
+    # Only the document owner can trigger their own profile generation
+    if user.get("uid") != body.userId:
+        raise HTTPException(status_code=403, detail="Forbidden.")
+
+    bff = _get_bff_data(body.userId, body.businessId)
+    if not bff:
+        raise HTTPException(status_code=404, detail="BFF data not found.")
+
+    bff_summary = json.dumps(bff, indent=2)
+
+    # ── Retrieve relevant passages from "Built on Rock" via Pinecone ─────────
+    sector = bff.get("section1", {}).get("sectorId", "")
+    niche  = bff.get("section1", {}).get("nicheId", "")
+    book_ctx = query_book_context(
+        f"Business Footing Framework WHAT WHY HOW {sector} {niche} Nigerian entrepreneur",
+        top_k=3,
+    )
+
+    # ── System prompt used for all 4 calls ───────────────────────────────────
+    base_system = (
+        "You are an expert business consultant specializing in Nigerian MSMEs, "
+        "trained in the Business Footing Framework (BFF) from 'Built on Rock' "
+        "by Iyanuoluwa Joseph Akinnusi. "
+        "Analyze the BFF data and produce professional, structured profile components. "
+        "Write in plain English that ANY entrepreneur can understand. "
+        "Ground all analysis in the Nigerian market context. "
+        "Return ONLY valid JSON."
+        + (f"\n\n{book_ctx}" if book_ctx else "")
+    )
+
+    # ── Prompt builders ───────────────────────────────────────────────────────
+    def prompt_identity():
+        return f"""
+BFF Data:
+{bff_summary}
+
+Generate the Business Identity profile. Return JSON:
+{{
+  "businessName": "string",
+  "sector": "string",
+  "subsector": "string",
+  "niche": "string",
+  "summary": "2-3 sentence plain-English description of what this business does",
+  "valueProposition": "one clear sentence: what the business promises customers",
+  "brandVoice": "2-3 adjectives describing how the brand should communicate (e.g. warm, direct, trustworthy)",
+  "tagline": "a short, memorable tagline for this business"
+}}"""
+
+    def prompt_customer():
+        return f"""
+BFF Data:
+{bff_summary}
+
+Generate the Customer Profile. Return JSON:
+{{
+  "demographics": {{
+    "ageRange": "primary age range",
+    "gender": "primary gender",
+    "location": "primary location(s)",
+    "incomeLevel": "low / middle / high / mixed",
+    "educationLevel": "brief description",
+    "employmentStatus": "brief description"
+  }},
+  "psychographics": {{
+    "values": ["list of 3-5 values the customer likely holds"],
+    "lifestyle": "brief lifestyle description",
+    "painPoints": ["3-5 main pain points this business solves for them"],
+    "motivations": ["3-5 reasons they would buy from this business"]
+  }},
+  "buyerPersona": "A 3-4 sentence narrative describing the typical customer as a named person (e.g. Meet Amaka...). Make it specific and relatable for Nigerian context."
+}}"""
+
+    def prompt_market():
+        return f"""
+BFF Data:
+{bff_summary}
+
+Generate the Market Data analysis. Return JSON:
+{{
+  "tam": "Total Addressable Market — brief estimate for Nigeria",
+  "sam": "Serviceable Addressable Market — realistic target market segment",
+  "som": "Serviceable Obtainable Market — what this business can realistically capture",
+  "swot": {{
+    "strengths": ["3-4 key strengths based on BFF data"],
+    "weaknesses": ["3-4 potential weaknesses to address"],
+    "opportunities": ["3-4 market opportunities in Nigeria right now"],
+    "threats": ["3-4 threats or risks to watch out for"]
+  }},
+  "pestle": {{
+    "political": "brief note on political factors relevant to this sector in Nigeria",
+    "economic": "brief note on economic factors",
+    "social": "brief note on social/cultural factors",
+    "technological": "brief note on tech trends",
+    "legal": "brief note on legal/regulatory considerations",
+    "environmental": "brief note if applicable"
+  }},
+  "competitiveLandscape": "2-3 sentences describing who else competes in this space in Nigeria and how this business can differentiate"
+}}"""
+
+    def prompt_bmc():
+        return f"""
+BFF Data:
+{bff_summary}
+
+Generate the Business Model Canvas. Return JSON with exactly these 9 keys,
+each containing a list of 2-4 concise bullet points:
+{{
+  "keyPartners": [...],
+  "keyActivities": [...],
+  "keyResources": [...],
+  "valuePropositions": [...],
+  "customerRelationships": [...],
+  "channels": [...],
+  "customerSegments": [...],
+  "costStructure": [...],
+  "revenueStreams": [...]
+}}"""
+
+    # ── Build the call plan — skip outputs already in Firestore ─────────────
+    # On retry after a partial failure, this avoids regenerating completed
+    # outputs and wasting tokens on the Groq free-tier TPM limit.
+    import time
+    db_check = _db()
+    biz_ref_check = (
+        db_check.collection("user_data")
+        .document(body.userId)
+        .collection("businesses")
+        .document(body.businessId)
+    )
+
+    all_outputs = {
+        "businessIdentity": prompt_identity,
+        "customerProfile":  prompt_customer,
+        "marketData":       prompt_market,
+        "businessModel":    prompt_bmc,
+    }
+
+    call_plan = []
+    for key, prompt_fn in all_outputs.items():
+        existing = biz_ref_check.collection("profile_output").document(key).get()
+        if existing.exists:
+            print(f"[bff] Skipping {key} — already exists in Firestore")
+        else:
+            call_plan.append((key, prompt_fn))
+
+    results: dict = {}
+    errors: list = []
+
+    # Sequential calls with 15s gap to stay within 12,000 TPM free-tier limit.
+    # With 1,500 max_tokens per call: ~2,500 tokens/call × 4 = ~10,000 total.
+    # 15s gap × 200 tokens/sec refill = 3,000 tokens recovered between calls.
+    for i, (key, prompt_fn) in enumerate(call_plan):
+        if i > 0:
+            time.sleep(15)  # 15s gap: ~3,000 tokens recovered at 200 tok/s
+        try:
+            results[key] = _call_groq_json(base_system, prompt_fn())
+        except Exception as e:
+            errors.append(f"{key}: {str(e)}")
+            print(f"[bff] Failed to generate {key}: {e}")
+
+    # Fail only if we had work to do and ALL of it failed
+    if call_plan and len(errors) == len(call_plan):
+        raise HTTPException(
+            status_code=500,
+            detail=f"Profile generation failed: {'; '.join(errors)}",
+        )
+
+    # ── Save to Firestore ─────────────────────────────────────────────────────
+    db = _db()
+    biz_ref = (
+        db.collection("user_data")
+        .document(body.userId)
+        .collection("businesses")
+        .document(body.businessId)
+    )
+
+    from google.cloud.firestore_v1 import SERVER_TIMESTAMP
+    for key, data in results.items():
+        biz_ref.collection("profile_output").document(key).set(
+            {**data, "generatedAt": SERVER_TIMESTAMP}
+        )
+
+    # Mark BFF as complete
+    biz_ref.update({"bffCompleted": True})
+
+    return {
+        "success": True,
+        "outputs": list(results.keys()),
+    }

routes/chat.py

@@ -0,0 +1,127 @@
+import json
+from fastapi import APIRouter, HTTPException, Depends
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+from firebase_admin import firestore
+from auth import verify_firebase_token
+from utils.groq_client import call_groq_stream, LIGHT_MODEL, HEAVY_MODEL
+from utils.pinecone_client import query_book_context
+
+router = APIRouter()
+
+
+# ─── Schemas ──────────────────────────────────────────────────────────────────
+
+class Message(BaseModel):
+    role: str    # "user" or "assistant"
+    content: str
+
+
+class ChatRequest(BaseModel):
+    businessId: str
+    sessionId: str
+    message: str
+    history: list[Message] = []
+    useHeavyModel: bool = False   # True for AI Consultation sessions
+
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+def _get_business_context(user_id: str, business_id: str) -> str:
+    """Builds a system context string from BFF + profile_output in Firestore."""
+    db = firestore.client()
+    biz_ref = (
+        db.collection("user_data")
+        .document(user_id)
+        .collection("businesses")
+        .document(business_id)
+    )
+
+    # Fetch BFF section 1 (WHAT) for quick context
+    s1 = biz_ref.collection("bff").document("section1").get()
+    # Fetch business identity if generated
+    identity = biz_ref.collection("profile_output").document("businessIdentity").get()
+
+    ctx_parts = []
+
+    if s1.exists:
+        d = s1.to_dict()
+        ctx_parts.append(
+            f"Business: {d.get('businessName', 'Unknown')}, "
+            f"Sector: {d.get('sector', '')}, "
+            f"Niche: {d.get('niche', '')}"
+        )
+
+    if identity.exists:
+        d = identity.to_dict()
+        ctx_parts.append(f"Summary: {d.get('summary', '')}")
+        ctx_parts.append(f"Value Proposition: {d.get('valueProposition', '')}")
+
+    return "\n".join(ctx_parts) if ctx_parts else "Business profile not yet generated."
+
+
+# ─── Route: Chat message (streaming SSE) ─────────────────────────────────────
+
+@router.post("/message")
+def chat_message(
+    body: ChatRequest,
+    user: dict = Depends(verify_firebase_token),
+):
+    """
+    Accepts a user message and returns a streaming SSE response.
+    For passive AI Chat: uses light model (llama-3.1-8b-instant).
+    For AI Consultation: uses heavy model (llama-3.3-70b-versatile).
+
+    Stream format (SSE):
+      data: {"type": "thinking", "token": "..."}   ← reasoning (heavy model only)
+      data: {"type": "response", "token": "..."}   ← main response
+      data: {"type": "done"}                        ← stream end
+    """
+    user_id = user.get("uid")
+    model   = HEAVY_MODEL if body.useHeavyModel else LIGHT_MODEL
+
+    business_context = _get_business_context(user_id, body.businessId)
+
+    # Retrieve relevant passages from "Built on Rock" based on user's message
+    book_ctx = query_book_context(body.message, top_k=2)
+
+    system_prompt = f"""You are the VenThrive Business Assistant — a business consultant trained in the Business Footing Framework (BFF) from "Built on Rock" by Iyanuoluwa Joseph Akinnusi. You help Nigerian entrepreneurs build successful businesses using the WHAT-WHY-HOW philosophy.
+
+BUSINESS CONTEXT:
+{business_context}
+{f"{chr(10)}RELEVANT BFF GUIDANCE FROM 'BUILT ON ROCK':{chr(10)}{book_ctx}" if book_ctx else ""}
+
+RULES:
+1. STRICTLY BUSINESS: Stay focused on the entrepreneur's business. If asked personal questions, redirect warmly.
+2. NIGERIAN CONTEXT: Reference real Nigerian examples — banks (GTBank, First Bank, Moniepoint), platforms (Jumia, Konga, Flutterwave), markets (Balogun, Alaba), cities and states.
+3. BFF PHILOSOPHY: When relevant, ground advice in the WHAT-WHY-HOW framework from "Built on Rock".
+4. PLAIN ENGLISH: No business jargon without explanation. Write like you're talking to a smart friend.
+5. CONCISE: 5-6 sentences max per response. Use bullet points for lists.
+5. ACTIONABLE: Every response should tell the entrepreneur what to DO next, not just what things mean.
+"""
+
+    messages = [{"role": "system", "content": system_prompt}]
+    for msg in body.history[-10:]:  # last 10 messages for context window efficiency
+        messages.append({"role": msg.role, "content": msg.content})
+    messages.append({"role": "user", "content": body.message})
+
+    def stream():
+        try:
+            # call_groq_stream handles key rotation on 429
+            stream_response = call_groq_stream(
+                system_prompt=system_prompt,
+                user_prompt=body.message,
+                model=model,
+                max_tokens=512,
+            )
+            for chunk in stream_response:
+                token = chunk.choices[0].delta.content
+                if token:
+                    yield f"data: {json.dumps({'type': 'response', 'token': token})}\n\n"
+
+            yield f"data: {json.dumps({'type': 'done'})}\n\n"
+
+        except Exception as e:
+            yield f"data: {json.dumps({'type': 'error', 'message': 'Something went wrong. Please try again.'})}\n\n"
+
+    return StreamingResponse(stream(), media_type="text/event-stream")

routes/consultation.py

@@ -0,0 +1,186 @@
+"""
+AI Consultation Session Routes
+──────────────────────────────────────────────────────────────────────────────
+Manages proactive AI Consultation sessions distinct from passive AI Chat.
+
+AI Chat:    passive — waits for user questions
+Consultation: proactive — AI opens with agenda, leads through structured phases
+              (Discovery → Analysis → Prescription) and produces a written report
+
+Routes:
+  POST /api/consultation/start  → AI reads profile, generates opening message
+  POST /api/consultation/report → AI generates structured report from session
+"""
+
+import json
+from datetime import datetime
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel
+from firebase_admin import firestore
+from auth import verify_firebase_token
+from utils.groq_client import call_groq_json, HEAVY_MODEL
+from utils.pinecone_client import query_book_context
+
+router = APIRouter()
+
+
+class StartRequest(BaseModel):
+    userId:     str
+    businessId: str
+
+
+class ReportRequest(BaseModel):
+    userId:     str
+    businessId: str
+    messages:   list[dict]  # [{"role": "user"|"assistant", "content": "..."}]
+
+
+def _read_profile(user_id: str, business_id: str) -> dict:
+    db  = firestore.client()
+    biz = (
+        db.collection("user_data").document(user_id)
+        .collection("businesses").document(business_id)
+    )
+    ctx: dict = {}
+    for key in ["businessIdentity", "customerProfile", "marketData"]:
+        doc = biz.collection("profile_output").document(key).get()
+        if doc.exists:
+            ctx[key] = doc.to_dict()
+    return ctx
+
+
+@router.post("/start")
+def start_consultation(
+    body: StartRequest,
+    user: dict = Depends(verify_firebase_token),
+):
+    """
+    Reads the entrepreneur's business profile and generates a warm, structured
+    opening message with 5 focus areas. The AI has already 'read the brief'
+    so the session starts with context rather than from scratch.
+    """
+    profile = _read_profile(body.userId, body.businessId)
+    identity = profile.get("businessIdentity", {})
+
+    biz_name  = identity.get("businessName",    "your business")
+    sector    = identity.get("sector",           "")
+    value_prop = identity.get("valueProposition", "")
+    summary   = identity.get("summary",          "")
+
+    book_ctx = query_book_context(
+        "business consultation strategy discovery analysis Nigerian entrepreneur",
+        top_k=2,
+    )
+
+    system = (
+        "You are a senior business consultant at VenThrive, trained in the "
+        "Business Footing Framework from 'Built on Rock' by Iyanuoluwa Joseph Akinnusi. "
+        "You are warm, direct, and speak in plain everyday English. "
+        "You do NOT use business jargon. You speak like a trusted advisor, not a textbook. "
+        "Return ONLY valid JSON."
+        + (f"\n\n{book_ctx}" if book_ctx else "")
+    )
+
+    prompt = f"""
+You are starting a consultation session with the founder of "{biz_name}"
+({sector}). Their value proposition is: "{value_prop}".
+Brief summary: {summary[:300]}
+
+Generate a warm, professional opening message that:
+1. Greets them by referencing their specific business (not generic)
+2. Mentions you've reviewed their Business Footing Framework profile
+3. Presents exactly 5 focus areas as a numbered list
+4. Asks them to pick the one they want to focus on today
+
+The 5 focus areas should be:
+1. Strategy & Market Position
+2. Customer Acquisition & Retention
+3. Financial Planning & Pricing
+4. Operations & Standard Processes
+5. Investor Readiness & Growth
+
+Return JSON:
+{{
+  "openingMessage": "<your full opening message here>",
+  "focusAreas": ["Strategy & Market Position", "Customer Acquisition & Retention", "Financial Planning & Pricing", "Operations & Standard Processes", "Investor Readiness & Growth"]
+}}"""
+
+    try:
+        result = call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=800)
+        return {
+            "openingMessage": result.get("openingMessage", ""),
+            "focusAreas":     result.get("focusAreas", []),
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Could not start consultation: {str(e)}")
+
+
+@router.post("/report")
+def generate_report(
+    body: ReportRequest,
+    user: dict = Depends(verify_firebase_token),
+):
+    """
+    Takes the full session transcript and generates a structured consultation
+    report with findings, specific recommendations, and next steps.
+    """
+    if user.get("uid") != body.userId:
+        raise HTTPException(status_code=403, detail="Forbidden.")
+
+    if len(body.messages) < 2:
+        raise HTTPException(status_code=400, detail="Session too short to generate a report.")
+
+    transcript = "\n".join([
+        f"{'CONSULTANT' if m['role'] == 'assistant' else 'ENTREPRENEUR'}: {m['content']}"
+        for m in body.messages
+    ])
+
+    book_ctx = query_book_context(
+        "consultation findings recommendations action plan Nigerian business",
+        top_k=2,
+    )
+
+    system = (
+        "You are a business consultant writing a formal post-consultation report. "
+        "Analyze the conversation and produce a structured, actionable document. "
+        "Be specific to what was actually discussed — no generic advice. "
+        "Write in clear, plain English. "
+        "Return ONLY valid JSON."
+        + (f"\n\n{book_ctx}" if book_ctx else "")
+    )
+
+    prompt = f"""
+Consultation transcript:
+{transcript[:4000]}
+
+Today's date: {datetime.now().strftime('%B %d, %Y')}
+
+Write a formal consultation report. Return JSON:
+{{
+  "date": "{datetime.now().strftime('%B %d, %Y')}",
+  "sessionSummary": "2-3 sentences summarising what was discussed and the main concern addressed",
+  "keyFindings": [
+    "Specific finding 1 from the conversation",
+    "Specific finding 2",
+    "Specific finding 3"
+  ],
+  "recommendations": [
+    {{
+      "action": "What to do",
+      "rationale": "Why this matters for their specific business",
+      "timeline": "When to do it (e.g. This week / Within 30 days)"
+    }}
+  ],
+  "nextSteps": [
+    "Concrete action step 1",
+    "Concrete action step 2",
+    "Concrete action step 3"
+  ],
+  "closingNote": "A personalised, encouraging closing sentence referencing their business."
+}}"""
+
+    try:
+        result = call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=2000)
+        return {"report": result}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Report generation failed: {str(e)}")

routes/documents.py

@@ -0,0 +1,202 @@
+"""
+Document Content Generation Route
+──────────────────────────────────────────────────────────────────────────────
+Generates structured content for Business Plan and Pitch Deck using Groq
+with full key rotation. The generated content is saved to Firestore and
+returned to the frontend for client-side PDF rendering via jsPDF.
+
+Profile-based documents (BMC, Identity, Customer, Market) do NOT use this
+endpoint — they generate PDF directly from profile_output in the frontend.
+
+This endpoint handles only the documents that require AI narrative generation:
+  - business_plan  → 9-section written plan
+  - pitch_deck     → 7-slide pitch outline
+"""
+
+import json
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel
+from firebase_admin import firestore
+from auth import verify_firebase_token
+from utils.groq_client import call_groq_json, HEAVY_MODEL
+from utils.pinecone_client import query_book_context
+
+router = APIRouter()
+
+
+class GenerateDocRequest(BaseModel):
+    userId:     str
+    businessId: str
+    docType:    str  # "business_plan" | "pitch_deck"
+
+
+def _get_bff_and_profile(user_id: str, business_id: str) -> dict:
+    """Reads BFF sections + profile_output from Firestore into one context dict."""
+    db  = firestore.client()
+    biz = (
+        db.collection("user_data")
+        .document(user_id)
+        .collection("businesses")
+        .document(business_id)
+    )
+
+    context: dict = {}
+
+    # BFF sections
+    for section in ["section1", "section2", "section3"]:
+        doc = biz.collection("bff").document(section).get()
+        if doc.exists:
+            context[section] = doc.to_dict()
+
+    # Profile outputs
+    for key in ["businessIdentity", "customerProfile", "marketData", "businessModel"]:
+        doc = biz.collection("profile_output").document(key).get()
+        if doc.exists:
+            context[key] = doc.to_dict()
+
+    return context
+
+
+# ─── Business Plan ────────────────────────────────────────────────────────────
+def _generate_business_plan(ctx: dict, book_context: str) -> dict:
+    system = (
+        "You are a professional business consultant specializing in Nigerian MSMEs. "
+        "Write a complete, practical Business Plan for this entrepreneur. "
+        "Use plain English — no jargon. Every section must be actionable and specific "
+        "to the Nigerian market. Return ONLY valid JSON.\n\n"
+        + (book_context or "")
+    )
+    prompt = f"""
+Business context:
+{json.dumps(ctx, indent=2)[:3000]}
+
+Generate a comprehensive Business Plan. Return JSON:
+{{
+  "executiveSummary": "2-3 paragraphs summarizing the business, opportunity, and goals",
+  "businessOpportunity": "The problem being solved and why now",
+  "companyDescription": "What the business does, its mission, and legal structure",
+  "targetMarket": "Detailed description of the target market in Nigeria",
+  "productsServices": "What is being sold, key features, pricing approach",
+  "marketingStrategy": "How the business will reach and retain customers",
+  "operationsPlan": "Day-to-day operations, location, equipment, team",
+  "financialSummary": "Startup costs, expected revenue, break-even estimate",
+  "implementationTimeline": "Key milestones for the first 12 months"
+}}"""
+    return call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=2500)
+
+
+# ─── Pitch Deck ────────────────────────────────────────────────────────────────
+def _generate_pitch_deck(ctx: dict, book_context: str) -> dict:
+    system = (
+        "You are a venture capital pitch consultant. "
+        "Create a compelling 7-slide investor pitch deck for this Nigerian entrepreneur. "
+        "Be concise — each slide has 3-4 punchy bullet points. "
+        "Ground everything in real Nigerian market data where possible. "
+        "Return ONLY valid JSON.\n\n"
+        + (book_context or "")
+    )
+    prompt = f"""
+Business context:
+{json.dumps(ctx, indent=2)[:3000]}
+
+Generate a 7-slide Pitch Deck. Return JSON where each key is a slide:
+{{
+  "slide1_problem": {{
+    "title": "The Problem",
+    "bullets": ["...", "...", "..."]
+  }},
+  "slide2_solution": {{
+    "title": "Our Solution",
+    "bullets": ["...", "...", "..."]
+  }},
+  "slide3_market": {{
+    "title": "Market Opportunity",
+    "bullets": ["TAM...", "SAM...", "SOM..."]
+  }},
+  "slide4_business_model": {{
+    "title": "How We Make Money",
+    "bullets": ["...", "...", "..."]
+  }},
+  "slide5_traction": {{
+    "title": "Traction & Milestones",
+    "bullets": ["...", "...", "..."]
+  }},
+  "slide6_strategy": {{
+    "title": "Go-To-Market Strategy",
+    "bullets": ["...", "...", "..."]
+  }},
+  "slide7_ask": {{
+    "title": "The Ask",
+    "bullets": ["Seeking: ...", "Use of funds: ...", "Expected outcome: ..."]
+  }}
+}}"""
+    return call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=2000)
+
+
+# ─── Route ────────────────────────────────────────────────────────────────────
+@router.post("/generate-content")
+def generate_document_content(
+    body: GenerateDocRequest,
+    user: dict = Depends(verify_firebase_token),
+):
+    """
+    Generates AI content for Business Plan or Pitch Deck.
+    Saves the result to Firestore and returns the document ID.
+    PDF rendering happens client-side in the browser.
+    """
+    if user.get("uid") != body.userId:
+        raise HTTPException(status_code=403, detail="Forbidden.")
+
+    if body.docType not in ("business_plan", "pitch_deck"):
+        raise HTTPException(
+            status_code=400,
+            detail="docType must be 'business_plan' or 'pitch_deck'",
+        )
+
+    # ── Read context ─────────────────────────────────────────────────────────
+    ctx = _get_bff_and_profile(body.userId, body.businessId)
+    if not ctx:
+        raise HTTPException(status_code=404, detail="Business profile not found.")
+
+    # ── BFF Philosophy context from Pinecone ──────────────────────────────────
+    query = (
+        f"business plan entrepreneurship Nigeria "
+        f"{ctx.get('businessIdentity', {}).get('sector', '')} "
+        f"{ctx.get('section1', {}).get('niche', '')}"
+    )
+    book_context = query_book_context(query, top_k=3)
+
+    # ── Generate ──────────────────────────────────────────────────────────────
+    try:
+        if body.docType == "business_plan":
+            content = _generate_business_plan(ctx, book_context)
+            doc_name = f"{ctx.get('businessIdentity', {}).get('businessName', 'Business')}_Plan"
+        else:
+            content = _generate_pitch_deck(ctx, book_context)
+            doc_name = f"{ctx.get('businessIdentity', {}).get('businessName', 'Business')}_PitchDeck"
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Generation failed: {str(e)}")
+
+    # ── Save to Firestore ─────────────────────────────────────────────────────
+    from google.cloud.firestore_v1 import SERVER_TIMESTAMP
+    db  = firestore.client()
+    biz = (
+        db.collection("user_data")
+        .document(body.userId)
+        .collection("businesses")
+        .document(body.businessId)
+    )
+    doc_ref = biz.collection("documents").add({
+        "name":         doc_name,
+        "type":         body.docType,
+        "dataSnapshot": content,
+        "createdAt":    SERVER_TIMESTAMP,
+        "status":       "ready",
+    })
+    doc_id = doc_ref[1].id
+
+    return {
+        "success":      True,
+        "docId":        doc_id,
+        "dataSnapshot": content,
+    }

routes/planning.py

@@ -0,0 +1,139 @@
+"""
+Planning AI Suggestions
+──────────────────────────────────────────────────────────────────────────────
+Reads the business profile and generates actionable task / milestone suggestions
+grounded in the BFF data and "Built on Rock" philosophy.
+
+Routes:
+  POST /api/planning/suggest  →  task or milestone suggestions
+"""
+
+import json
+from datetime import datetime, timedelta
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel
+from firebase_admin import firestore
+from auth import verify_firebase_token
+from utils.groq_client import call_groq_json, HEAVY_MODEL
+from utils.pinecone_client import query_book_context
+
+router = APIRouter()
+
+
+class SuggestRequest(BaseModel):
+    userId:     str
+    businessId: str
+    type:       str          # "tasks" | "milestones"
+    existing:   list[str] = []  # existing task/milestone titles (to avoid duplicates)
+
+
+def _read_context(user_id: str, business_id: str) -> dict:
+    db  = firestore.client()
+    biz = (
+        db.collection("user_data").document(user_id)
+        .collection("businesses").document(business_id)
+    )
+    ctx: dict = {}
+    for key in ["businessIdentity", "marketData", "businessModel"]:
+        doc = biz.collection("profile_output").document(key).get()
+        if doc.exists:
+            ctx[key] = doc.to_dict()
+    s1 = biz.collection("bff").document("section1").get()
+    if s1.exists:
+        ctx["section1"] = s1.to_dict()
+    return ctx
+
+
+@router.post("/suggest")
+def suggest_planning_items(
+    body: SuggestRequest,
+    user: dict = Depends(verify_firebase_token),
+):
+    if body.type not in ("tasks", "milestones"):
+        raise HTTPException(status_code=400, detail="type must be 'tasks' or 'milestones'")
+
+    ctx  = _read_context(body.userId, body.businessId)
+    biz_name  = ctx.get("businessIdentity", {}).get("businessName", "this business")
+    sector    = ctx.get("businessIdentity", {}).get("sector", "")
+    value_prop = ctx.get("businessIdentity", {}).get("valueProposition", "")
+    summary   = ctx.get("businessIdentity", {}).get("summary", "")
+
+    book_ctx = query_book_context(
+        f"action plan milestones tasks Nigerian entrepreneur {sector}", top_k=2
+    )
+
+    existing_str = (
+        f"\nDo NOT duplicate any of these existing items: {body.existing}"
+        if body.existing else ""
+    )
+
+    system = (
+        "You are a business consultant helping a Nigerian entrepreneur plan their next steps. "
+        "Suggest practical, specific, achievable actions grounded in the Business Footing Framework. "
+        "All suggestions must be relevant to their specific business — no generic advice. "
+        "Write in plain English. Return ONLY valid JSON."
+        + (f"\n\n{book_ctx}" if book_ctx else "")
+    )
+
+    if body.type == "tasks":
+        prompt = f"""
+Business: {biz_name} ({sector})
+Value proposition: {value_prop}
+Summary: {summary[:400]}
+{existing_str}
+
+Generate exactly 5 actionable Kanban tasks for this business right now.
+Tasks should be specific, achievable within 2 weeks, and move the business forward.
+Spread them across different priorities: some for this week, some for next week.
+
+Return JSON:
+{{
+  "suggestions": [
+    {{
+      "title": "specific task title",
+      "description": "why this matters for {biz_name}",
+      "column": "todo"
+    }},
+    ...
+  ]
+}}
+
+column must be one of: "todo", "in_progress", "done"
+Most tasks should be "todo" unless clearly already started.
+"""
+    else:  # milestones
+        today = datetime.now()
+        dates = [(today + timedelta(days=d)).strftime("%Y-%m-%d") for d in [30, 60, 90, 180, 365]]
+        prompt = f"""
+Business: {biz_name} ({sector})
+Value proposition: {value_prop}
+Summary: {summary[:400]}
+{existing_str}
+
+Generate exactly 5 business milestones for the next 12 months.
+Milestones should be measurable achievements that mark significant progress.
+Space them across different timeframes.
+
+Available target dates to choose from: {dates}
+(Choose the most appropriate date for each milestone)
+
+Return JSON:
+{{
+  "suggestions": [
+    {{
+      "title": "milestone title (specific and measurable)",
+      "targetDate": "YYYY-MM-DD"
+    }},
+    ...
+  ]
+}}
+"""
+
+    try:
+        result = call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=800)
+        suggestions = result.get("suggestions", [])
+        if not suggestions:
+            raise ValueError("No suggestions returned")
+        return {"suggestions": suggestions}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Suggestion generation failed: {str(e)}")

routes/transcribe.py

@@ -0,0 +1,64 @@
+from fastapi import APIRouter, UploadFile, File, Depends, HTTPException
+from auth import verify_firebase_token
+import os
+from groq import Groq
+
+router = APIRouter()
+groq_client = Groq(api_key=os.environ.get("GROQ_API_KEY"))
+
+SUPPORTED_AUDIO_TYPES = {
+    "audio/webm", "audio/mp4", "audio/mpeg", "audio/wav",
+    "audio/ogg", "audio/flac", "audio/x-m4a",
+}
+
+MAX_AUDIO_BYTES = 25 * 1024 * 1024  # 25 MB — Groq Whisper limit
+
+
+@router.post("/transcribe")
+async def transcribe_audio(
+    audio: UploadFile = File(...),
+    user: dict = Depends(verify_firebase_token),
+):
+    """
+    Accepts a browser-recorded audio blob, sends it to Groq Whisper,
+    and returns the transcript text.
+
+    Voice input is NEVER stored — the audio bytes are discarded after
+    transcription returns. Only the resulting text is saved by the caller.
+    See VUL-019 (no audio persistence).
+    """
+    # Basic content-type guard — not a hard security boundary since the
+    # browser may send 'application/octet-stream'. Real validation happens
+    # when Groq rejects unsupported formats.
+    content_type = audio.content_type or "audio/webm"
+    if content_type not in SUPPORTED_AUDIO_TYPES and content_type != "application/octet-stream":
+        raise HTTPException(
+            status_code=415,
+            detail=f"Unsupported audio format: {content_type}",
+        )
+
+    audio_bytes = await audio.read()
+
+    if len(audio_bytes) > MAX_AUDIO_BYTES:
+        raise HTTPException(
+            status_code=413,
+            detail="Audio file exceeds 25 MB limit.",
+        )
+
+    if len(audio_bytes) == 0:
+        raise HTTPException(status_code=400, detail="Audio file is empty.")
+
+    try:
+        transcription = groq_client.audio.transcriptions.create(
+            model="whisper-large-v3-turbo",
+            file=(audio.filename or "recording.webm", audio_bytes, content_type),
+            response_format="json",
+            language="en",
+        )
+        return {"transcript": transcription.text}
+
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Transcription failed: {str(e)}",
+        )

scripts/ingest_book.py

@@ -0,0 +1,154 @@
+"""
+"Built on Rock" — Pinecone Ingestion Script
+──────────────────────────────────────────────────────────────────────────────
+Run this ONCE after setting up your Pinecone index to populate it with
+content from "Built on Rock" by Iyanuoluwa Joseph Akinnusi.
+
+Prerequisites:
+  1. Create a Pinecone index named 'venthrive-bff' with:
+     - Dimensions: 1024
+     - Metric: Cosine
+     - Cloud: AWS us-east-1 (Serverless, free tier)
+  2. Set PINECONE_API_KEY in backend/.env
+  3. Ensure the PDF is in the APEX folder (path configured below)
+
+Usage (from the VenThrive/backend/ directory):
+    python scripts/ingest_book.py
+
+No local ML library needed — embeddings are generated by Pinecone's
+hosted multilingual-e5-large model (1024 dimensions).
+"""
+
+import os
+import sys
+import time
+
+# Load backend env
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from dotenv import load_dotenv
+load_dotenv(os.path.join(os.path.dirname(os.path.dirname(__file__)), ".env"))
+
+from pinecone import Pinecone
+import pypdf
+
+# ─── Config ───────────────────────────────────────────────────────────────────
+# Absolute path — the PDF lives in the sibling APEX project folder
+_BASE = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+PDF_PATH = os.path.join(_BASE, "APEX", "Built On Rock by Iyanuoluwa Joseph Akinnusi-1.pdf")
+CHUNK_WORDS   = 400
+OVERLAP_WORDS = 50
+BATCH_SIZE    = 90   # Pinecone Inference allows up to 96 inputs per request
+EMBED_MODEL   = "multilingual-e5-large"
+
+
+def extract_pdf_text(path: str) -> str:
+    if not os.path.exists(path):
+        raise FileNotFoundError(
+            f"\n[ERR] PDF not found: {path}\n"
+            "Ensure 'Built On Rock by Iyanuoluwa Joseph Akinnusi-1.pdf' "
+            "is in the APEX folder."
+        )
+    reader = pypdf.PdfReader(path)
+    return "\n".join(page.extract_text() or "" for page in reader.pages)
+
+
+def chunk_text(text: str, chunk_words: int, overlap_words: int) -> list[dict]:
+    words  = text.split()
+    chunks = []
+    i = 0
+    while i < len(words):
+        chunk_text_str = " ".join(words[i : i + chunk_words])
+        chunks.append({
+            "id":   f"chunk_{len(chunks):04d}",
+            "text": chunk_text_str,
+            "meta": {
+                "source":     "built_on_rock",
+                "chunk_id":   len(chunks),
+                "word_start": i,
+                "word_end":   min(i + chunk_words, len(words)),
+            },
+        })
+        i += chunk_words - overlap_words
+    return chunks
+
+
+def main():
+    api_key    = os.environ.get("PINECONE_API_KEY", "")
+    index_name = os.environ.get("PINECONE_INDEX_NAME", "venthrive-bff")
+
+    if not api_key:
+        print("[ERR] PINECONE_API_KEY not set in backend/.env")
+        return
+
+    # ── Extract text ──────────────────────────────────────────────────────────
+    print(f"[PDF] Reading: {os.path.basename(PDF_PATH)}")
+    text = extract_pdf_text(PDF_PATH)
+    words = len(text.split())
+    print(f"   {words:,} words extracted from PDF")
+
+    # ── Chunk ─────────────────────────────────────────────────────────────────
+    chunks = chunk_text(text, CHUNK_WORDS, OVERLAP_WORDS)
+    print(f"   {len(chunks)} chunks ({CHUNK_WORDS} words each, {OVERLAP_WORDS} overlap)")
+
+    # ── Connect to Pinecone ───────────────────────────────────────────────────
+    print(f"\n[PIN] Connecting to Pinecone index '{index_name}'...")
+    pc    = Pinecone(api_key=api_key)
+    index = pc.Index(index_name)
+
+    stats = index.describe_index_stats()
+    existing = stats.get("total_vector_count", 0)
+    print(f"   Existing vectors: {existing}")
+
+    if existing > 0:
+        print(f"   Index already has {existing} vectors.")
+        ans = input("   Clear and re-ingest? (y/N): ").strip().lower()
+        if ans == 'y':
+            index.delete(delete_all=True)
+            print("   ✓ Cleared")
+        else:
+            print("   Skipping ingestion.")
+            return
+
+    # ── Embed + upsert in batches ─────────────────────────────────────────────
+    print(f"\n[AI] Embedding + uploading {len(chunks)} chunks via Pinecone Inference...")
+    print("   (Model: multilingual-e5-large, 1024 dims — no local ML needed)")
+
+    for i in range(0, len(chunks), BATCH_SIZE):
+        batch = chunks[i : i + BATCH_SIZE]
+        texts = [c["text"] for c in batch]
+
+        # Generate embeddings via Pinecone Inference API
+        embedding_result = pc.inference.embed(
+            model=EMBED_MODEL,
+            inputs=texts,
+            parameters={"input_type": "passage", "truncate": "END"},
+        )
+        embeddings = [e.values for e in embedding_result]
+
+        # Upsert vectors
+        vectors = [
+            {
+                "id":       chunk["id"],
+                "values":   embeddings[j],
+                "metadata": {**chunk["meta"], "text": chunk["text"]},
+            }
+            for j, chunk in enumerate(batch)
+        ]
+        index.upsert(vectors=vectors)
+
+        done = min(i + BATCH_SIZE, len(chunks))
+        print(f"   {done}/{len(chunks)} chunks uploaded")
+
+        # Small pause to stay within Pinecone rate limits
+        if done < len(chunks):
+            time.sleep(0.5)
+
+    # ── Done ──────────────────────────────────────────────────────────────────
+    final = index.describe_index_stats()
+    total = final.get("total_vector_count", "?")
+    print(f"\n[OK] Ingestion complete! Index '{index_name}' now has {total} vectors.")
+    print("   VenThrive AI will now draw from 'Built on Rock' for every relevant query.")
+
+
+if __name__ == "__main__":
+    main()

utils/groq_client.py

@@ -0,0 +1,167 @@
+"""
+Groq API Key Rotation Utility
+──────────────────────────────────────────────────────────────────────────────
+Loads ALL env vars named GROQ_API_KEY or GROQ_API_KEY_* at startup.
+When any route hits a 429 rate-limit error, calling rotate() silently
+advances to the next key. Users never see a rate-limit error as long as
+at least one key still has remaining quota.
+
+Rotation is round-robin and thread-safe (uses a threading.Lock so concurrent
+FastAPI workers don't race on the index).
+
+Usage:
+    from utils.groq_client import call_groq_json, HEAVY_MODEL, LIGHT_MODEL
+
+    data = call_groq_json(system_prompt, user_prompt, json_mode=True)
+"""
+
+import os
+import json
+import time
+import threading
+from groq import Groq
+
+# ─── Load all keys ────────────────────────────────────────────────────────────
+# Accepts: GROQ_API_KEY, GROQ_API_KEY_1 ... GROQ_API_KEY_N (any suffix)
+_KEYS: list[str] = []
+for k in sorted(os.environ.keys()):
+    if k == 'GROQ_API_KEY' or k.startswith('GROQ_API_KEY_'):
+        v = os.environ[k].strip()
+        if v:
+            _KEYS.append(v)
+
+if not _KEYS:
+    raise RuntimeError(
+        "No Groq API keys found. "
+        "Set GROQ_API_KEY (and optionally GROQ_API_KEY_7, etc.) in your .env file."
+    )
+
+print(f"[groq] {len(_KEYS)} API key(s) loaded for rotation")
+
+# ─── Model names ──────────────────────────────────────────────────────────────
+HEAVY_MODEL = "llama-3.3-70b-versatile"   # reasoning, profile generation, consultation
+LIGHT_MODEL  = "llama-3.1-8b-instant"     # chat, quick responses
+
+# ─── Round-robin state ────────────────────────────────────────────────────────
+_idx  = 0
+_lock = threading.Lock()
+
+
+def _current_key() -> str:
+    return _KEYS[_idx % len(_KEYS)]
+
+
+def _rotate() -> str:
+    """Advance to the next key and return it. Thread-safe."""
+    global _idx
+    with _lock:
+        _idx = (_idx + 1) % len(_KEYS)
+        new_key = _KEYS[_idx]
+    print(f"[groq] Rotated to key index {_idx % len(_KEYS)} of {len(_KEYS)}")
+    return new_key
+
+
+# ─── Core call ────────────────────────────────────────────────────────────────
+def call_groq(
+    system_prompt: str,
+    user_prompt: str,
+    model: str = HEAVY_MODEL,
+    json_mode: bool = False,
+    max_tokens: int = 1500,
+    temperature: float = 0.7,
+) -> str:
+    """
+    Calls Groq with automatic key rotation on 429 errors.
+    Tries every available key before giving up.
+    Raises the last error if all keys are exhausted.
+
+    Returns the raw string content of the first choice message.
+    """
+    last_error: Exception | None = None
+
+    # Try each key in the rotation at most once, plus one extra attempt
+    # in case the first key has recovered by the time we loop around.
+    for attempt in range(len(_KEYS) + 1):
+        try:
+            client = Groq(api_key=_current_key())
+            kwargs: dict = dict(
+                model=model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user",   "content": user_prompt},
+                ],
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+            if json_mode:
+                kwargs["response_format"] = {"type": "json_object"}
+
+            response = client.chat.completions.create(**kwargs)
+            return response.choices[0].message.content  # type: ignore
+
+        except Exception as e:
+            last_error = e
+            err_str = str(e)
+            is_rate_limit = (
+                '429' in err_str
+                or 'rate_limit' in err_str.lower()
+                or 'rate limit' in err_str.lower()
+            )
+
+            if is_rate_limit and attempt < len(_KEYS):
+                # Rotate and pause briefly before retrying
+                _rotate()
+                time.sleep(1)
+                continue
+
+            # Non-rate-limit errors bubble up immediately
+            raise
+
+    # All keys exhausted
+    raise last_error or RuntimeError("All Groq API keys are rate-limited")
+
+
+def call_groq_json(
+    system_prompt: str,
+    user_prompt: str,
+    model: str = HEAVY_MODEL,
+    max_tokens: int = 1500,
+) -> dict:
+    """Convenience wrapper: calls Groq in JSON mode and returns parsed dict."""
+    raw = call_groq(system_prompt, user_prompt, model=model,
+                    json_mode=True, max_tokens=max_tokens)
+    return json.loads(raw)
+
+
+def call_groq_stream(
+    system_prompt: str,
+    user_prompt: str,
+    model: str = LIGHT_MODEL,
+    max_tokens: int = 512,
+):
+    """
+    Returns a Groq streaming completion object.
+    Rotates key on 429 like all other calls.
+    """
+    last_error: Exception | None = None
+    for attempt in range(len(_KEYS) + 1):
+        try:
+            client = Groq(api_key=_current_key())
+            return client.chat.completions.create(
+                model=model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user",   "content": user_prompt},
+                ],
+                temperature=0.7,
+                max_tokens=max_tokens,
+                stream=True,
+            )
+        except Exception as e:
+            last_error = e
+            if ('429' in str(e) or 'rate_limit' in str(e).lower()) and attempt < len(_KEYS):
+                _rotate()
+                time.sleep(1)
+                continue
+            raise
+    raise last_error or RuntimeError("All Groq API keys are rate-limited")

utils/pinecone_client.py

@@ -0,0 +1,74 @@
+"""
+Pinecone Vector Search — "Built on Rock" context retrieval
+──────────────────────────────────────────────────────────────────────────────
+Uses Pinecone's hosted Inference API (multilingual-e5-large, 1024 dims) to
+embed queries and retrieve relevant passages from "Built on Rock".
+
+No local ML library required — embeddings are generated by Pinecone's servers.
+
+If PINECONE_API_KEY is not set or the call fails for any reason, returns ''
+so all AI calls work normally without book context (graceful degradation).
+"""
+
+import os
+from functools import lru_cache
+
+PINECONE_API_KEY  = os.environ.get("PINECONE_API_KEY", "")
+PINECONE_INDEX    = os.environ.get("PINECONE_INDEX_NAME", "venthrive-bff")
+EMBED_MODEL       = "multilingual-e5-large"  # 1024 dims, free on Pinecone
+MIN_SCORE         = 0.40
+DEFAULT_TOP_K     = 3
+
+
+@lru_cache(maxsize=1)
+def _get_pinecone():
+    from pinecone import Pinecone
+    return Pinecone(api_key=PINECONE_API_KEY)
+
+
+def query_book_context(query: str, top_k: int = DEFAULT_TOP_K) -> str:
+    """
+    Returns the most relevant passages from 'Built on Rock' as a formatted
+    context string for injection into AI system prompts.
+
+    Returns '' if Pinecone is not configured or the call fails.
+    """
+    if not PINECONE_API_KEY:
+        return ""
+
+    try:
+        pc    = _get_pinecone()
+        index = pc.Index(PINECONE_INDEX)
+
+        # Generate query embedding via Pinecone Inference (no local model needed)
+        embedding_result = pc.inference.embed(
+            model=EMBED_MODEL,
+            inputs=[query],
+            parameters={"input_type": "query", "truncate": "END"},
+        )
+        query_vector = embedding_result[0].values
+
+        results = index.query(
+            vector=query_vector,
+            top_k=top_k,
+            include_metadata=True,
+        )
+
+        passages = [
+            match["metadata"]["text"]
+            for match in results.get("matches", [])
+            if match.get("score", 0) >= MIN_SCORE
+        ]
+
+        if not passages:
+            return ""
+
+        return (
+            "RELEVANT CONTEXT FROM 'BUILT ON ROCK' (Business Footing Framework):\n\n"
+            + "\n\n---\n\n".join(passages)
+            + "\n\nApply the BFF philosophy above to ground your advice."
+        )
+
+    except Exception as e:
+        print(f"[pinecone] Context retrieval skipped: {e}")
+        return ""  # graceful degradation