Policy Advisor Research Assistant

🚀 Next-Generation Policy Research Platform - A sophisticated AI-powered research assistant with intelligent report management, multi-agent workflow, and conversational interface for comprehensive UK policy analysis.

✨ Modern Python project with professional dependency management, comprehensive security, and advanced AI features!

🏗️ Architecture

🚀 Quick Start

1. Install uv (if you don't have it)

# Install uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install Dependencies

# Install all dependencies from pyproject.toml
uv sync

3. Set Up Environment Variables

Create a .env file with your API keys:

# Required API Keys
GEMINI_API_KEY=your_gemini_api_key_here
SERP_API_KEY=your_serpapi_key_here

# Optional: LangSmith for observability and error tracking
LANGCHAIN_API_KEY=your_langsmith_api_key_here
LANGCHAIN_PROJECT=Policy Advisor Research Assistant
LANGCHAIN_TRACING_V2=true

🔍 LangSmith Tracing

The application uses LangGraph's built-in LangSmith integration for comprehensive tracing:

• Automatic Workflow Tracing: Every agent execution is automatically traced
• Node-Level Visibility: See individual agent performance and outputs
• Routing Decisions: Track conditional routing logic between agents
• Error Tracking: Detailed error traces with full context
• Performance Metrics: Timing and resource usage for each workflow step

Test Tracing:

# Test the tracing setup
python test_langgraph_tracing.py

4. Run the Application

# Using uv
uv run python app.py

# Or activate the environment and run directly
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python app.py

The application will start on http://localhost:7863

🎨 LangGraph Workflow Visualization

Visualize the multi-agent workflow in multiple formats:

Quick Visualization

# Show complete workflow visualization (ASCII + Mermaid + PNG)
python app.py --graph

# Alternative complete visualization
python visualize_graph.py

Specific Format Options

# ASCII diagram (terminal-friendly)
python visualize_graph.py --ascii

# Mermaid diagram (code format for documentation)
python visualize_graph.py --mermaid

# PNG image (visual diagram file) - saved to graphs/ folder
python visualize_graph.py --png

# Statistics only
python visualize_graph.py --stats

# Show available formats
python visualize_graph.py --formats

Save All Formats to Files

# Save all diagrams to graphs/ folder
python visualize_graph.py --save

# Save specific format with custom filename
python visualize_graph.py --png --output my_workflow.png
python visualize_graph.py --mermaid --save --output my_diagram.mmd
python visualize_graph.py --ascii --save --output my_ascii.txt

Clean Up and Management

# Clean up old graph files before generating new ones
python visualize_graph.py --clean --save

# Just clean up without generating new files
python visualize_graph.py --clean

📁 Folder Structure:

graphs/
├── README.md              # Documentation for graph files
├── workflow_graph.png     # Visual PNG diagram
├── workflow_diagram.mmd   # Mermaid diagram code
├── workflow_ascii.txt     # ASCII art diagram
└── .gitkeep              # Ensures folder exists in git

📝 All graph files are automatically organized in the graphs/ folder with comprehensive documentation.

🚀 Advanced Multi-Agent Workflow

The system uses a sophisticated 4-node LangGraph workflow with dual evaluation paths and intelligent context-aware routing:

🎯 Core Agent Nodes:

1. 🛡️ SAFETY_CHECK - Advanced security validation with threat classification
2. 🔍 RESEARCH - Multi-source policy research with AI synthesis
3. 📊 EVALUATOR - Automated quality assessment with detailed scoring
4. 💬 CONVERSATION - Context-aware report updates and conversational assistance

🔄 Intelligent Routing Pathways:

🆕 New Research Path:

Research Request → SAFETY_CHECK → RESEARCH → EVALUATOR → Follow-up Questions

🔄 Report Update Path:

Follow-up Question → SAFETY_CHECK → CONVERSATION → EVALUATOR → Enhanced Report

💬 Analysis Path:

Analytical Question → SAFETY_CHECK → CONVERSATION → Direct Answer

❓ Help Path:

Help Request → SAFETY_CHECK → CONVERSATION → Guidance

🛡️ Security Path:

Security Threat → SAFETY_CHECK → BLOCK & LOG

✨ Dual Auto-Evaluation System:

• Research Reports: Automatically evaluated after generation
• Report Updates: Automatically evaluated after modifications
• Quality Scoring: Structure, content, sources, and writing assessment
• Improvement Suggestions: Actionable recommendations for enhancement

🎉 Result: Every piece of content - whether new or updated - receives comprehensive quality assurance!

🚀 Why uv with pyproject.toml?

• Standard Python packaging: Uses modern Python project standards
• Fast installs: Much faster than pip
• Dependency management: Clear separation of runtime and dev dependencies
• Reproducible: Lock file ensures exact same versions
• Professional: Industry-standard project structure

📋 Requirements

• Python 3.12+: Latest Python version with improved performance, better error messages, and modern features
• uv package manager: For fast dependency management

🐍 Why Python 3.12?

• Performance: Up to 11% faster than Python 3.11
• Better error messages: More helpful debugging information
• Modern syntax: Latest Python language features
• Security: Latest security updates and improvements
• Type hints: Enhanced type system support

✨ Features

🎨 Advanced ChatGPT-like Interface

• Conversational chat interface with intelligent context awareness
• Dynamic follow-up questions automatically generated after each report
• Smart example topics in the sidebar for quick start
• Suggestion prompts to guide your research journey
• Real-time responses with comprehensive status indicators
• Clean, modern design with responsive layout and professional styling

🔍 Intelligent Research Capabilities

• Multi-Source Research: Government (.gov.uk) + external analysis integration
• AI-Powered Synthesis: Google Gemini 2.5 Pro for comprehensive report generation
• 🎆 Dual Auto-Evaluation: Every report AND every update gets AI quality assessment
• Context-Aware Updates: Smart modifications preserve existing content and structure
• Intelligent Routing: System distinguishes between new research vs. report updates
• Version Control: Complete report history with change tracking and metadata
• Professional Standards: British English conventions with proper citations

📊 Enhanced Report Management

• Automatic Saving: Reports saved with metadata and comprehensive tracking
• Version History: Complete audit trail of all report modifications
• Change Indicators: Visual markers (🔄 [UPDATED]) for modified sections
• Report Metadata: Word counts, source tracking, creation timestamps
• Organized Storage: Structured file system with versions and metadata
• Report Recovery: Never lose work with automatic version backups

🛡️ Security & Safety

• Comprehensive Safety Guardrails: Protection against prompt injection and malicious inputs
• Input Validation: Multi-pattern security threat detection
• Security Logging: Detailed logging of blocked requests and threats
• User-friendly Error Messages: Clear feedback for security violations
• Threat Classification: Categorized security threat detection

📊 Observability & Error Handling

• LangGraph + LangSmith Integration: Automatic tracing of multi-agent workflow execution
• Enhanced Error Handling: Detailed error logging and user-friendly messages
• Performance Tracking: Complete monitoring of agent interactions and workflow performance
• Distributed Tracing: Full visibility into each agent node execution and routing decisions
• Security Metrics: Statistics on blocked requests and threat types
• Error Recovery: Graceful handling of failures with helpful suggestions

💬 Interactive Features

• Context-Aware Conversations: System remembers your reports and maintains context
• Dynamic Follow-up Questions: 8 tailored questions appear after each report
• 🎆 Enhanced Report Updates: Click follow-up buttons to improve reports + get automatic quality evaluation
• Smart Routing: System intelligently routes between new research, updates, and analysis
• Comprehensive Quality Feedback: Every interaction provides detailed AI assessment
• Seamless Experience: Updates flow naturally with evaluation and version tracking
• Help System: Comprehensive guides and examples
• Conversation Persistence: Session state maintained across interactions

🛠️ How to Use

🚀 Getting Started:

1. Click example topics from the sidebar, or
2. Type your research request naturally:
   • "Generate a report on UK digital economy strategy"
   • "Research climate change policy and net zero targets"
   • "Analyze NHS digital transformation initiatives"

💫 Follow-up Magic:

After generating a report, 8 dynamic follow-up questions appear as clickable buttons:

• 🔒 "What are the cybersecurity implications?"
• 📈 "How effective are current policies?"
• 📝 "Expand the implementation section"
• 🆕 "Add more recent developments"
• 👥 "Include more stakeholder perspectives"
• 🌍 "Compare this to international best practices"
• 📅 "What are the key milestones and timelines?"
• 🏢 "Who are the main stakeholders affected?"

🎆 The Complete Experience:

1. Click any follow-up question
2. Watch as the system intelligently updates your report
3. Receive automatic AI quality evaluation with detailed scoring
4. See visual markers (🔄 [UPDATED]) highlighting changes
5. Get actionable recommendations for further improvements

✨ Result: Enhanced reports with professional quality assurance - all in one seamless interaction!**

📊 Report Management:

• Auto-Evaluation: Every report receives quality assessment
• Version Tracking: All changes are saved with version history
• Professional Format: Reports include metadata, citations, and proper structure
• Organized Storage: Files saved to reports/ with versions and metadata

🎯 Quick Actions:

• 📚 Help & Guide: Get detailed instructions
• 🔍 Evaluate Last Report: Re-assess current report quality
• 🗑️ Clear Conversation: Start fresh (preserves saved reports)

💡 Example Conversations

User: "Generate a report on UK digital economy strategy"
Assistant: Searches government sources, generates comprehensive report

User: "Evaluate this report's quality"
Assistant: Provides detailed AI evaluation with scores and feedback

User: "Add more details about implementation timelines"
Assistant: Updates the report with expanded implementation section

📁 Project Structure

├── app.py                 # Main application with UI and workflow integration
├── agents.py              # LangGraph agent nodes (safety, research, evaluator, conversation)
├── workflow.py            # LangGraph workflow definition and routing logic
├── report_manager.py      # Enhanced report management with versioning
├── visualize_graph.py     # Workflow visualization tools
├── pyproject.toml         # Modern project configuration and dependencies
├── .env                   # API keys (create this file)
├── graphs/                # Workflow visualizations
│   ├── workflow_ascii.txt   # ASCII diagram
│   ├── workflow_diagram.mmd # Mermaid diagram
│   └── README.md           # Graph documentation
├── reports/               # Generated reports with full management
│   ├── report_topic_timestamp.md  # Main report files
│   ├── metadata/          # Report metadata (JSON)
│   └── versions/           # Version history backups
└── README.md              # This comprehensive documentation

🎨 Advanced Architecture: Multi-agent LangGraph workflow with intelligent routing, comprehensive report management, and professional file organization.

📄 File Organization System

Reports Structure:

reports/
├── education_technology_20250916_231100.md     # Main report (latest version)
├── brexit_impact_20250916_231503.md           # Another report
├── metadata/                                   # Report metadata
│   ├── education_technology_20250916_231100.json
│   └── brexit_impact_20250916_231503.json
└── versions/                                   # Version history
    ├── education_technology_20250916_231100_v1.md
    ├── education_technology_20250916_231100_v2.md
    └── education_technology_20250916_231100_v3.md

✨ Every report includes:

• Complete metadata (word count, sources, timestamps)
• Version history (full audit trail of changes)
• Change tracking (what was modified and when)
• Source documentation (government vs external sources)

🔑 API Keys Required

• GEMINI_API_KEY: Get from Google AI Studio
• SERP_API_KEY: Get from SerpApi

🎯 Built-in Example Topics

The sidebar includes ready-to-use examples:

• UK digital economy strategy and implementation
• Climate change policy and net zero targets
• NHS digital transformation initiatives
• Education technology in UK schools
• Housing policy and affordability crisis
• Brexit impact on trade and economy
• AI regulation and governance framework
• Green energy transition policies
• Social care reform and funding
• Transport infrastructure investment

🚀 Suggestion Prompts

Quick-start prompts to guide your research:

• "Generate a comprehensive policy report on..."
• "Analyze the current status of..."
• "Compare different approaches to..."
• "Evaluate the effectiveness of..."
• "Provide recommendations for improving..."

📊 Report Features

• Structured Markdown format with clear headings
• Proper citations with numbered references
• British English spelling throughout
• Policy-focused analysis with practical implications
• Balanced perspectives from government and external sources
• Professional tone suitable for policy advisors
• Automatic saving to timestamped files

🎨 Interface Features

• Responsive design works on desktop and mobile
• Clean, modern styling inspired by ChatGPT
• Sidebar with examples for quick access
• Status indicators for ongoing operations
• Conversation persistence during session
• Easy navigation with intuitive controls

🚨 Troubleshooting

• uv not found: Install uv with curl -LsSf https://astral.sh/uv/install.sh | sh
• Dependencies not installed: Run uv sync to install from pyproject.toml
• No search results: Check your SERP_API_KEY in .env file
• AI generation fails: Verify your GEMINI_API_KEY in .env file
• Slow responses: Large topics may take 30-60 seconds
• Network errors: Ensure stable internet connection
• Interface issues: Try refreshing the page
• Module not found: Ensure you're in the project directory and ran uv sync
• gRPC/ALTS warnings: These Google Cloud auth warnings are harmless and can be ignored

📝 Common Warnings (Safe to Ignore)

Google Cloud Authentication Warning:

ALTS creds ignored. Not running on GCP and untrusted ALTS is not enabled

This is normal when using Google AI services locally (not on Google Cloud Platform). The application works correctly despite this warning.

🔧 Customization

Modern Python project structure makes it easy to:

• Modify dependencies: Edit pyproject.toml
• Customize the chat interface: All UI code in app.py
• Add new example topics: Update the EXAMPLE_TOPICS list
• Customize AI prompts: Modify prompt templates directly
• Change styling: Update the CSS in _get_chatgpt_css()
• Add new features: Everything is in the single app.py file

Adding Dependencies

To add new Python packages, update the pyproject.toml file:

[project]
dependencies = [
    "gradio>=4.0.0",
    "your-new-package>=1.0.0",  # Add here
]

Then run uv sync to install the new dependencies.

📝 License

MIT License - feel free to modify and distribute.

🎬 Quick Demo

# 1. Clone or download the project
# 2. Install dependencies
uv sync
# 3. Create .env with your API keys
# 4. Run the application
uv run python app.py
# 5. Open http://localhost:7863
# 6. Start chatting about UK policy!

---

Experience policy research like never before with a ChatGPT-style interface designed for policy professionals.