Adds project files

.gitignore

@@ -0,0 +1,35 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python packaging/build artifacts
+build/
+dist/
+*.egg-info/
+pip-wheel-metadata/
+
+# Caches and logs
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+*.log
+.env
+
+# Tooling/project settings
+.idea/
+.vscode/
+.DS_Store
+
+# Hugging Face / Gradio artifacts
+~/.cache/huggingface/
+gradio_cached_examples/
+
+uv.lock
+main.py

.python-version

@@ -0,0 +1 @@
+3.13

README.md

@@ -1,14 +1,226 @@
 ---
 title: ContextPilot
-emoji: 📚
-colorFrom: pink
-colorTo: red
+emoji: 🧭
+colorFrom: blue
+colorTo: purple
 sdk: gradio
 sdk_version: 6.0.1
-app_file: app.py
+app_file: src/app.py
 pinned: false
 license: mit
-short_description: 'ContextPilot: Autonomous Context Engineering'
+short_description: 'ContextPilot: Autonomous Context Engineering for LLMs'
+tags:
+    - mcp-in-action-track-creative
+    - building-mcp-track-creative
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🧭 ContextPilot
+
+**Autonomous Context Engineering for LLM Conversations**
+
+ContextPilot automatically detects topic shifts in conversations and intelligently manages context to provide more relevant responses while saving tokens. Instead of sending the entire conversation history to the LLM on every turn, ContextPilot curates the context based on what's actually relevant.
+
+## 🎯 Problem Statement
+
+Traditional chatbots send the **entire conversation history** to the LLM on every message. This leads to:
+- **Token waste**: Paying for irrelevant context on every API call
+- **Context pollution**: Old topics confusing the model about current questions
+- **Context window limits**: Eventually hitting the model's maximum context length
+
+## 💡 Solution
+
+ContextPilot uses a **two-LLM architecture**:
+
+1. **Topic Detection LLM** (cheap, fast): Detects when conversation topics change
+2. **Response LLM** (capable, quality): Generates actual responses with curated context
+
+When you switch topics, ContextPilot:
+1. Saves the old topic's context (summary or full history)
+2. Loads only the relevant context for the new topic
+3. Sends a minimal, focused context to the response LLM
+
+## 🔄 Two Context Modes
+
+### Summary Mode (Default)
+- Stores a **summary + key facts** for each topic
+- Most token-efficient
+- Best for: General conversations, FAQ-style interactions
+- Trade-off: Some detail may be lost in summarization
+
+### Full Mode
+- Stores the **complete message history** for each topic
+- Maximum context preservation
+- Best for: Technical discussions, debugging sessions, detailed Q&A
+- Trade-off: Uses more tokens when returning to topics
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        User Message                          │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Topic Detection (CONTEXT_LLM)                   │
+│  - Smaller model (e.g., openai/gpt-oss-20b)                 │
+│  - Detects: same topic? new topic? returning to old topic?  │
+│  - Tools: save_context, load_context, set_current_topic     │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                    ┌─────────┴─────────┐
+                    │                   │
+            No Topic Change      Topic Changed
+                    │                   │
+                    │           ┌───────┴───────┐
+                    │           │               │
+                    │      Save Old         Load/Create
+                    │      Context          New Context
+                    │           │               │
+                    │           └───────┬───────┘
+                    │                   │
+                    └─────────┬─────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  Context Curation                            │
+│  Summary Mode: System prompt + topic summary + user message  │
+│  Full Mode: System prompt + full history + user message      │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────���──────────────────────┐
+│              Response Generation (RESPONSE_LLM)              │
+│  - Capable model (e.g., openai/gpt-oss-120b)                │
+│  - Receives curated context (not full history)              │
+│  - Generates response + compact context summary             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Store & Display                          │
+│  - Buffer exchange in session (for topic continuity)        │
+│  - Display clean response to user                           │
+│  - Show token savings metrics                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 📊 Token Savings
+
+ContextPilot tracks and displays:
+- **Curated Tokens**: What was actually sent to the LLM
+- **Full Context Tokens**: What would have been sent without curation
+- **Tokens Saved**: The difference (your savings!)
+- **Savings %**: Percentage of tokens saved
+- **Detection Tokens**: Tokens used by the topic detection LLM
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.10+
+- OpenAI-compatible API (OpenAI, Nebius, Together, etc.)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/contextPilot.git
+cd contextPilot
+
+# Install dependencies
+pip install -r requirements.txt
+# or with uv:
+uv sync
+
+# Set up environment variables
+cp .env.example .env
+# Edit .env with your API keys
+```
+
+### Environment Variables
+
+```bash
+# Required
+NEBIUS_API_KEY=your_api_key
+NEBIUS_BASE_URL=https://api.tokenfactory.nebius.com/v1/
+
+# Optional (with defaults)
+CONTEXT_LLM=openai/gpt-oss-20b        # Smaller model for topic detection
+RESPONSE_LLM=openai/gpt-oss-120b      # Capable model for responses
+SUMMARIZE_THRESHOLD=500                # Character threshold for summarization
+```
+
+### Run the App
+
+```bash
+# From project root
+python src/app.py
+
+# Or with Gradio reload
+gradio src/app.py
+```
+
+## 📁 Project Structure
+
+```
+contextPilot/
+├── src/
+│   ├── app.py                    # Gradio UI + Response LLM
+│   ├── context_pilot_workflow.py # Topic detection + context curation
+│   ├── mcp_server.py             # MCP server wrapper
+│   └── .context_store.json       # Persisted context (auto-generated)
+├── prompts/
+│   └── system_prompt.txt         # Topic detection system prompt
+├── pyproject.toml
+└── README.md
+```
+
+## 🎮 Demo Flow
+
+Try this conversation to see ContextPilot in action:
+
+1. **"Tell me 10 cool facts about cats"** → Topic set to "cats"
+2. **"How long do cats typically live?"** → Continues "cats" topic
+3. **"Tell me 10 cool things about horses"** → Saves "cats", switches to "horses"
+4. **"How long do horses typically live?"** → Continues "horses" topic
+5. **"Name 10 famous cats"** → Saves "horses", loads "cats" context
+6. **"What have I asked you about horses?"** → Saves "cats", loads "horses" with full history
+
+## 🔧 How It Works
+
+### Topic Detection
+The topic detection LLM receives:
+- Current topic name
+- List of previously saved topics
+- Brief context summaries
+- The new user message
+
+It decides whether to:
+- Continue the current topic (no tool call)
+- Save current + set new topic
+- Save current + load previous topic
+
+### Context Storage
+```json
+{
+  "contexts": {
+    "cats": {
+      "topic": "cats",
+      "summary": "Discussion about cats, their behavior and care",
+      "key_facts": ["Cats are obligate carnivores", "Cats have retractable claws"],
+      "full_history": [...]  // Only in full mode
+    }
+  },
+  "current_topic": "cats",
+  "mode": "summary",
+  "current_session_messages": [...]  // Buffer for current session
+}
+```
+
+## 🤝 Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+## 📄 License
+
+MIT License

prompts/system_prompt.txt

@@ -0,0 +1,37 @@
+You are a helpful AI assistant with context management capabilities. The contexts are managed by high level concepts.
+
+## Current State
+- Current topic: {current_topic}
+- Previously saved topics: {saved_topics}
+
+## Saved Context Summaries
+{context_summaries}
+
+## Your Context Management Responsibilities
+You have tools to manage conversation context.
+
+### FIRST MESSAGE (current topic is None):
+- Just call **set_current_topic** with the topic name based on the user's message
+- Do NOT call save_context (there's nothing to save yet)
+
+### When topic is changing to a NEW topic (not in saved topics):
+1. Call **save_context** to save the OLD topic
+2. Then call **set_current_topic** with the NEW topic name
+3. The topic name should not be too specific. For now, make it broad (i.e one word noun/verb)
+
+### When topic is changing to a PREVIOUSLY SAVED topic:
+1. Call **save_context** to save the OLD topic
+2. Then call **load_context** to load the saved topic
+
+### When topic is NOT changing (continuing the same topic):
+- Do NOT call any tools, just respond normally
+
+## Tool Descriptions
+- **save_context(topic, summary, key_facts)**: Save current conversation before switching away
+- **set_current_topic(topic)**: Set a new topic that hasn't been discussed before
+- **load_context(topic)**: Load and switch to a previously saved topic
+- **list_saved_contexts()**: See what topics have been discussed
+
+## IMPORTANT
+- If current topic is "None", ONLY call set_current_topic (don't save anything)
+- When switching topics, call BOTH save_context AND (set_current_topic OR load_context)

pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "contextpilot"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "gradio>=6.0.1",
+    "llama-index>=0.14.8",
+    "llama-index-llms-gemini>=0.6.1",
+    "llama-index-llms-openai>=0.6.10",
+    "llama-index-llms-openai-like>=0.5.3",
+    "llama-index-tools-mcp>=0.4.3",
+    "mcp[cli]>=1.22.0",
+    "openai>=1.30.0",
+    "python-dotenv>=1.2.1",
+]

requirements.txt

@@ -0,0 +1,21 @@
+# ContextPilot Dependencies
+# Install with: pip install -r requirements.txt
+
+# Gradio UI
+gradio>=6.0.1
+
+# LlamaIndex Core + LLM integrations
+llama-index>=0.14.8
+llama-index-llms-gemini>=0.6.1
+llama-index-llms-openai>=0.6.10
+llama-index-llms-openai-like>=0.5.3
+llama-index-tools-mcp>=0.4.3
+
+# MCP (Model Context Protocol)
+mcp[cli]>=1.22.0
+
+# OpenAI client
+openai>=1.30.0
+
+# Environment variables
+python-dotenv>=1.2.1