AI Context Stack Agent: Google OKF + MCP with Gemini

Knowledge-Grounded AI Agent for E-Commerce Analytics

This project demonstrates the AI Context Stack pattern from Google OKF + MCP: Explained The New "AI Context Stack" — combining two layers to build AI agents that produce accurate, real-time answers:

Layer	Technology	Role
Knowledge Layer	OKF (Open Knowledge Format)	Tells the agent what things mean — metric definitions, table schemas, SQL formulas
Access Layer	MCP-style Tools	Lets the agent query live data — read-only SQL against the database
LLM	Google Gemini	Reasons over both layers to answer questions

Why This Matters

• Without OKF: The agent guesses what "weekly active users" means and writes incorrect SQL
• Without MCP: The agent knows the definition but can't fetch live data
• With both: The agent reads the exact metric definition from OKF, then queries the database using the correct formula

Project Structure

ai-context-stack-agent/
├── agent.py                # Main agent (Gemini + OKF + tool calling)
├── mcp_server.py           # FastMCP server with database query tools
├── seed_db.py              # Seeds SQLite with sample e-commerce data
├── requirements.txt
└── knowledge/              # OKF Knowledge Bundle
    ├── index.md
    ├── datasets/
    │   └── ecommerce_db.md
    ├── tables/
    │   ├── orders.md
    │   └── customers.md
    └── metrics/
        ├── weekly_active_users.md
        └── monthly_revenue.md

Quick Start

# 1. Install dependencies
pip install -r requirements.txt

# 2. Seed the database
python seed_db.py

# 3. Set your Gemini API key
export GOOGLE_API_KEY=your-api-key  # Get one at https://aistudio.google.com/apikey

# 4. Run the agent
python agent.py

Example Queries

You: What are our weekly active users?
Agent: There are 15 weekly active users right now.

You: Show me the monthly revenue trend
Agent: Here is the monthly revenue trend:
  - 2026-04: $5,499.01 (36 orders)
  - 2026-05: $9,332.38 (65 orders)
  - 2026-06: $6,596.61 (52 orders)
  - 2026-07: $1,901.67 (16 orders)

How It Works

1. OKF Knowledge Bundle is loaded at startup — Markdown files with YAML frontmatter define every table schema, metric formula, and business concept
2. When you ask a question, the agent consults the relevant OKF concept document to understand the exact definition
3. Gemini's function calling invokes the database tools with the correct SQL from the OKF definition
4. The agent presents results grounded in the OKF definition — no hallucinated metric formulas

OKF Knowledge Format

Each concept is a Markdown file with YAML frontmatter following the OKF v0.1 spec:

---
type: Metric
title: Weekly Active Users (WAU)
description: Count of unique customers who placed at least one completed order in the last 7 days.
tags: [metric, engagement, users]
---

# Definition
Weekly Active Users (WAU) is the count of unique customers...

# SQL
SELECT COUNT(DISTINCT customer_id) AS weekly_active_users
FROM orders
WHERE status = 'completed'
  AND order_date >= date('now', '-7 days');

Tech Stack

• Google Gemini 2.5 Flash — LLM with native function calling
• google-genai — Google's Python SDK for Gemini
• FastMCP — MCP server framework (standalone server included)
• SQLite — Zero-setup database
• OKF v0.1 — Open Knowledge Format by Google Cloud

Tags

google-okf, mcp, model-context-protocol, open-knowledge-format, ai-context-stack, gemini-ai, google-gemini, ai-agent, llm-agent, function-calling, tool-use, ecommerce-analytics, knowledge-grounded-ai, agentic-ai, python, sqlite, fastmcp, okf-knowledge-bundle, data-analytics, ai-orchestration