University students in Kenya face major barriers when searching for scholarships, bursaries, internships, and industrial attachments. Essential details—such as Kenya Certificate of Secondary Education (KCSE) grade requirements, county quotas, statutory clearance certificates (HELB, KRA, NITA), and deadlines—are scattered across uncoordinated portals, leading to missed opportunities and application abandonment.
Opportunity Intelligence AI is a full-stack agentic platform that unifies opportunity discovery, transparent eligibility checks, deterministic deadline countdowns, dynamic checklists, and RAG-grounded conversational guidance.
The platform separates deterministic business logic (deadlines, checklists, scoring, data isolation) from probabilistic language generation (conversational advice and synthesis).
# Architecture & Data Flow +-------------------------------------------------------------------------+ | REACT 18 + VITE FRONTEND (SPA) | | Discovery Catalog | Eligibility Checker | Application Tracker | +------------------------------------+------------------------------------+ | HTTPS / REST (JWT Bearer) v +-------------------------------------------------------------------------+ | FASTAPI REST API GATEWAY | | JWT Authentication | Rate Limiting | Security Headers | +------------------------------------+------------------------------------+ | +------------------+------------------+ | | v v +------------------------------------+ +--------------------------------+ | AGENTIC ORCHESTRATION (Groq) | | DETERMINISTIC TOOLS & LOGIC | | - llama-3.3-70b-versatile | | - Eligibility Validation | | - Intent Parsing & Tool Dispatch | | - Deadline Countdown Math | | - Grounded Response Synthesis | | - Statutory Document Checklists| +-----------------+------------------+ +----------------+---------------+ | | +------------------+------------------+ | v +-------------------------------------------------------------------------+ | STORAGE & RETRIEVAL (PostgreSQL + pgvector) | | - Neon PostgreSQL: Users, Student Profiles, Tracked Applications | | - pgvector: 384-d Cosine HNSW Index (57 precomputed opportunity chunks) | +-------------------------------------------------------------------------+ # Core Technology Stack +---------------+--------------------------------------+----------------------------------------------------+ | Layer | Technology | Role | +---------------+--------------------------------------+----------------------------------------------------+ | Frontend | React 18, Vite, Tailwind CSS | Single-page student dashboard & chat drawer | | Backend | Python 3.10+, FastAPI, Pydantic v2 | High-performance asynchronous API gateway | | Relational DB | PostgreSQL 16 (Neon), SQLAlchemy 2.0 | Multi-tenant isolated storage for profiles & track | | Vector DB | pgvector (HNSW Cosine Index) | Native 384-dimensional dense semantic retrieval | | Embeddings | sentence-transformers/all-MiniLM-L6 | Fast CPU-based local dense vector generation | | LLM Inference | Groq Cloud (llama-3.3-70b-versatile) | Fast intent classification & cited answer synthesis| +---------------+--------------------------------------+----------------------------------------------------+ Agentic Architecture & Deterministic Tools The agent does not guess dates, calculate eligibility, or manipulate data via raw text prompts. Instead, it dispatches structured tasks to a deterministic Python TOOL_REGISTRY: # Tool Execution Flow Student Query ──> FastAPI ──> Agent Orchestrator ──> Groq LLM (Selects Tool) │ ┌─────────────────────────┘ ▼ TOOL_REGISTRY Execution ├── search_opportunities (pgvector 384-d semantic search) ├── assess_eligibility (Deterministic profile criteria check) ├── generate_application_checklist(Statutory items: KRA, HELB, NITA) ├── calculate_deadline_countdown (Exact calendar date math) └── get_tracked_applications (Isolated student tracking query) │ ▼ Structured Tool Results ──> Groq LLM (Cited Answer) Bounded Execution: Tool loops have a hard step limit to prevent infinite recursion. Data Isolation: All database queries enforce WHERE user_id = current_user.id, guaranteeing zero cross-student data leakage. Citation Reconciliation: Claims must map to verified opportunity chunk IDs; unverified assertions are flagged. Knowledge Base & Vector Retrieval (RAG) Curated Knowledge Base: 14 verified opportunities (scholarships, industrial attachments, internships, bursaries) formatted in Markdown with structured YAML frontmatter. Chunking Strategy: 500-character chunks with a 100-character overlap (57 total chunks) to preserve semantic context across sections. Vector Storage: Integrated directly into PostgreSQL using pgvector with an HNSW cosine index, retiring separate vector database silos while keeping local ChromaDB as fallback. Local Setup & Clone Guide To run Opportunity Intelligence AI locally: 1. Clone & Set Up Backend git clone https://github.com/Abdullahi-Ai/Opportunity-Intelligence-AI.git cd Opportunity-Intelligence-AI # Virtual environment & dependencies python3 -m venv backend/venv source backend/venv/bin/activate pip install -r backend/requirements.txt # Configure environment cp backend/.env.example backend/.env # Add your GROQ_API_KEY inside backend/.env # Run migrations & start server cd backend alembic upgrade head uvicorn app.main:app --reload --port 8000 cd Opportunity-Intelligence-AI/frontend npm install npm run dev Conclusion Opportunity Intelligence AI demonstrates a reliable, production-ready blueprint for student opportunity navigation by strictly isolating probabilistic LLM conversation from deterministic eligibility rules, date calculations, and statutory requirements. Grounding all retrieval in verified data eliminates hallucinations and protects students from scams and missed deadlines.