A modular AI assistant backend built with FastAPI, LangGraph, and Google Gemini that provides intelligent coding assistance inside the TalentIQ coding workspace.
The backend powers an AI coding instructor capable of:
- Understanding user coding questions
- Detecting user intent
- Building contextual prompts
- Retrieving relevant programming knowledge
- Requesting code execution through an external Express service
- Forwarding emitted model events as Server-Sent Events (SSE)
The system is designed around a LangGraph workflow architecture, allowing future expansion into more advanced agentic capabilities such as dynamic tool selection, multi-step reasoning, and long-term memory.
The assistant processes every request through a structured LangGraph workflow:
User Request
|
v
Intent Detection
|
v
Conversation Context Builder
|
v
Knowledge Retrieval
|
v
Tool Planning
|
v
Tool Execution
|
v
Prompt Assembly
|
v
LLM Generation
|
v
Streaming Response
Each stage has a dedicated responsibility, making the system easier to maintain and extend.
The assistant classifies incoming messages into supported interaction modes:
General programming conversations and explanations.
Prompt-guided hints intended to provide incremental guidance without revealing complete solutions.
Analyzes compiler errors, runtime failures, and incorrect behavior.
Reviews implementations for:
- Code quality
- Complexity
- Maintainability
- Edge cases
Focuses on teaching programming concepts and fundamentals.
- FastAPI
- Python
- LangGraph
- LangChain
- Pydantic
- SSE (Server Sent Events)
- Google Gemini
gemini-2.5-flash
- External Express.js code-execution service
- Frontend coding workspace
app
│
├── main.py
│
├── config.py
├── logger.py
│
├── schemas
│ └── request.py
│
├── security
│ └── hmac.py
│
├── streaming
│ └── sse.py
│
└── graph
│
├── builder.py
├── state.py
├── intents.py
│
├── nodes
│ ├── node.py
│ └── routing.py
│
├── prompts
│ ├── base.py
│ ├── registry.py
│ ├── general.py
│ ├── hint.py
│ ├── debug.py
│ ├── review.py
│ └── explain.py
│
├── context
│ ├── context.py
│ └── context_formatter.py
│
├── retrieval
│ ├── repository.py
│ └── retrieval.py
│
├── tools
│ ├── tool_planning.py
│ ├── tool_execution.py
│ ├── tool_executor.py
│ └── tool_schema.py
│
├── llm
│ └── llm.py
│
└── knowledge
└── data
├── arrays.json
└── hashmap.json
The assistant uses LangGraph to model the AI reasoning pipeline.
The graph state contains:
GraphStatewhich stores:
- User conversation history
- Problem context
- Execution context
- Detected intent
- Retrieved knowledge
- Tool plans
- Tool outputs
- Prompt messages
- Final response
Each graph node modifies only the part of the state it owns.
The frontend sends:
{
"problem_id": "two-sum",
"problem_context": {
"title": "Two Sum",
"description": "Find two numbers in an array that add up to a target.",
"constraints": ["Exactly one solution exists"],
"tags": ["two-sum", "hashmap"]
},
"execution_context": {
"language": "python",
"user_code": "",
"compiler_output": ""
},
"chat_history": [
{
"role": "user",
"content": "Can you help me solve this?"
}
]
}The request contains:
Information about the coding challenge:
- Title
- Description
- Constraints
Current workspace state:
- Programming language
- User code
- Compiler output
Previous conversation messages.
The router analyzes the latest user message.
Example:
"Why am I getting this runtime error?"
becomes:
DEBUG
Example:
"Can you explain binary search?"
becomes:
EXPLAIN
Conversation history is converted into LangChain message objects.
The assistant currently uses recent conversation history to keep prompts efficient.
The retrieval pipeline provides additional knowledge context.
Currently it performs tag-based matching against local JSON knowledge assets:
- Matches problem-context tags against tags in the local JSON knowledge assets
- Injects matching entries into the final prompt
It does not currently perform vector search or retrieve directly from compiler output or execution context. The retrieval layer is isolated so it can later be replaced with:
- MongoDB vector search
- Chroma
- Pinecone
- Weaviate
- Other vector databases
without affecting the graph architecture.
The assistant integrates with the existing external Express code-execution service.
The backend forwards the selected editor language to the Express execution service. The actual supported languages and runtime availability are determined by that service. The current integration is intended for:
- Python
- JavaScript
Java is not implemented or validated in this repository.
The execution pipeline provides:
- Program output
- Runtime errors
- Service-reported compilation failures
which are injected back into the AI reasoning context.
Hint mode is currently prompt-driven. The planner creates a structured request_hint
action, but the execution node only dispatches execute_code actions to the Express
service; no separate hint service is currently wired.
Prompts are dynamically selected based on intent.
Example:
DEBUG
|
v
debug.py prompt builder
HINT
|
v
hint.py prompt builder
Each prompt extends a shared base coding instructor prompt.
The final structured message payload is sent to Gemini.
The model receives:
- System instructions
- Problem information
- User workspace
- Conversation context
- Retrieved knowledge
- Tool execution results
The backend returns a Server-Sent Events (SSE) response and forwards chat-model chunks emitted through LangGraph's event stream. Incremental delivery depends on the model provider and deployment path; end-to-end browser streaming has not been independently verified.
The response flow:
Gemini Model Events
|
v
LangGraph Event Stream
|
v
FastAPI StreamingResponse
|
v
Frontend Chat Interface
GET /health
Response:
{
"status": "awake"
}POST /api/graph/chat
Headers:
X-Signature
X-Timestamp
Request:
{
"problem_id": "two-sum",
"problem_context": {
"title": "Two Sum",
"description": "Find two numbers",
"constraints": [],
"tags": ["two-sum"]
},
"execution_context": {
"language": "python",
"user_code": "",
"compiler_output": ""
},
"chat_history": [
{
"role": "user",
"content": "Help debug this"
}
]
}Response:
text/event-stream
Example:
data: The issue is caused by...
data: because your loop condition...
event: done
data: done
- Python 3.12+
- Google Gemini API Key
Clone repository:
git clone <repository-url>
cd TalentIQ-AI-Assistant-LangGraph-FastAPIInstall dependencies and sync the managed environment:
uv syncThe project declares dependencies in pyproject.toml and pins the resolved
environment in uv.lock. This repository does not include a requirements.txt
file.
Create:
.env
Example:
GOOGLE_API_KEY=your_google_api_key
CLIENT_URL=http://localhost:5173
EXPRESS_API_URL=http://localhost:3000/api
INTERNAL_SHARED_SECRET=your_shared_secretStart FastAPI:
uvicorn app.main:app --reloadWhen using uv, the equivalent command keeps execution inside the managed
environment:
uv run uvicorn app.main:app --reloadServer:
http://localhost:8000
The chat endpoint uses HMAC request verification.
The middleware validates:
- Request signature
- Timestamp freshness
- Verification using the configured shared secret
Protection includes:
- Rejection of requests outside a 30-second timestamp window
- Timing-attack-resistant signature comparison
This provides request-integrity and authenticity checks between parties that share
the secret; it is not user authentication and does not prevent replay within the
accepted timestamp window. Configure a strong INTERNAL_SHARED_SECRET in every
non-local environment; the current application has a development fallback when
the variable is absent. Remove that fallback before deployment.
The project separates:
Responsible for:
- HTTP requests
- Authentication
- Streaming responses
Responsible for:
- AI workflow orchestration
Responsible for:
- Assistant behavior
Responsible for:
- External actions
Responsible for:
- Knowledge enrichment
Responsible for:
- LLM provider interaction
The architecture supports future additions:
Move from:
Plan -> Execute -> Respond
towards:
Observe
|
Reason
|
Act
|
Observe
|
Refine
Possible additions:
- User learning history
- Previous solutions
- Coding patterns
- Personalized teaching
Replace current retrieval implementation with:
- MongoDB Atlas Vector Search
- Dedicated knowledge database
- Embedding pipeline
Future monitoring:
- LangSmith tracing
- Request latency tracking
- Token usage analytics
- Failure monitoring
The backend currently provides:
✅ FastAPI API layer
✅ LangGraph orchestration
✅ Gemini integration
✅ Intent-based routing
✅ Context management
✅ Tag-based local JSON retrieval
✅ Express-backed code execution for debug requests
✅ SSE response streaming when provider events are emitted
✅ HMAC request validation
The repository does not currently include a runnable automated test suite. The Express execution service and Google Gemini credentials are external runtime dependencies.
The architecture is prepared for future expansion into a more advanced coding assistant system.