server, adding some basic. also got rid of gemini mess, and deleted reviews and moved notes out of repo

notes_etc/development_guide_01.md

@@ -1,797 +0,0 @@
-# Corvid Council - Development Guide
-
-## Project Overview
-
-**Name**: Corvid Council  
-**Hackathon**: Gradio Agents & MCP Hackathon - Winter 25  
-**Track**: Building MCP (Creative)  
-**Tags**: `building-mcp-track-creative`
-
-### Concept
-A multi-agent group chat where 4 AI crow experts discuss topics, each using specialized MCP tools. The Gradio app itself also exposes MCP tools, allowing external applications to query the expert panel.
-
-### The Hook
-"What if you could consult a panel of AI experts? Use it two ways: watch them research and debate in a group chat, or query them as an MCP tool from Claude Desktop or any MCP client."
-
----
-
-## Architecture
-
-```
-External User/App (Claude Desktop, etc.)
-    ↓ (calls MCP tool)
-ask_crow_council(question)
-    ↓ (hits)
-Gradio App (IS an MCP server)
-    ↓ (internally orchestrates)
-CouncilOrchestrator
-    ↓ (manages)
-4 Character Agents (Corvus, Magpie, Raven, Crow)
-    ↓ (each uses)
-Character-Specific MCP Tools (~12-15 total)
-    ↓ (which call)
-External APIs (Semantic Scholar, eBird, Weather, etc.)
-    ↓ (returns aggregated response)
-Back to User
-```
-
-### Two Interfaces, Same Backend
-
-**Interface 1: Gradio Chat UI** (Direct access)
-- Users see the full group chat
-- Watch characters use their tools in real-time
-- See sources, debates, synthesis
-- Can inject questions
-
-**Interface 2: MCP Tools** (Programmatic access)
-- External apps call `ask_crow_council(question)`
-- Same orchestration happens internally
-- Returns structured, synthesized response
-- Fast, clean API integration
-
----
-
-## The Characters
-
-### Corvus (The Scholar) - Melancholic
-**Archetype**: Academic, thorough, perfectionist  
-**Personality**: 
-- PhD researcher studying corvid cognition
-- Every claim needs citation
-- Cautious, analytical, sometimes pedantic
-- Posts rarely but substantively
-- Always verifies before sharing
-
-**Communication Style**:
-- Long, structured messages
-- Includes citations and methodology
-- Questions assumptions
-- "According to X study (DOI)..."
-
-**MCP Tools** (4 tools):
-- `search_corvid_papers(query, years, min_citations)` - Academic database search
-- `get_paper_details(doi)` - Full paper information
-- `verify_claim_against_literature(claim, context)` - Fact-checking
-- `get_citation_network(doi, depth)` - Related research
-
-**Behavior Pattern**:
-1. Sees topic → searches papers
-2. Reads abstract/methods → verifies quality
-3. Composes careful response with citations
-4. If others make claims → verifies against literature
-
----
-
-### Magpie (The Enthusiast) - Sanguine
-**Archetype**: Social, optimistic, storyteller  
-**Personality**:
-- Collects crow stories like magpies collect shiny things
-- Loves viral videos, human-interest pieces
-- Shares everything excitedly, often unchecked
-- Makes connections between unrelated things
-- High energy, frequent poster
-
-**Communication Style**:
-- Rapid-fire short messages
-- Uses emojis
-- "omg you HAVE to see this!"
-- Shares first, verifies later (or never)
-
-**MCP Tools** (3 tools):
-- `search_social_media(query, platform, timeframe)` - TikTok, Twitter, Reddit
-- `search_web(query)` - General web search
-- `find_trending_content(topic)` - What's viral right now
-
-**Behavior Pattern**:
-1. Sees topic → searches social/web immediately
-2. Shares whatever looks interesting
-3. Sometimes posts old/duplicate content
-4. Creates energy, others moderate
-
-**Quirk**: Posts old news 30-40% of the time (doesn't check dates)
-
----
-
-### Raven (The Activist) - Choleric
-**Archetype**: Action-oriented, passionate, confrontational  
-**Personality**:
-- Environmental activist
-- Sees crows as ecosystem health indicators
-- Aggressive fact-gathering
-- Calls out misinformation
-- Posts urgent updates
-
-**Communication Style**:
-- Short, urgent messages
-- Exclamation points
-- "We need to act NOW"
-- Challenges others directly
-- Facts as weapons
-
-**MCP Tools** (4 tools):
-- `get_environmental_data(location, metric)` - Pollution, habitat data
-- `search_news(query, recency)` - Current news monitoring
-- `fact_check_claim(claim, source)` - Debunking tool
-- `analyze_sentiment(topic, source)` - What are people saying?
-
-**Behavior Pattern**:
-1. Sees topic → looks for environmental angle
-2. Searches news for threats/problems
-3. Fact-checks others' claims aggressively
-4. Rallies for action
-
-**Creates drama**: Often disagrees with Corvus (action vs. more research)
-
----
-
-### Crow (The Observer) - Phlegmatic
-**Archetype**: Calm, patient, contemplative  
-**Personality**:
-- Birdwatcher who observes local populations
-- Philosophical, sees long-term patterns
-- Rarely posts but reads everything
-- When speaks, it's meaningful
-- Patience over urgency
-
-**Communication Style**:
-- Rare, brief, profound
-- Long silences then sudden insight
-- "I've been watching..."
-- Ties everything together
-- No wasted words
-
-**MCP Tools** (3 tools):
-- `get_bird_sightings(location, species, timeframe)` - eBird data
-- `get_weather_patterns(location, duration)` - Weather effects on behavior
-- `analyze_temporal_patterns(data, timeframe)` - Long-term trends
-
-**Behavior Pattern**:
-1. Observes conversation quietly
-2. Uses tools to gather observational data
-3. Waits for pattern to emerge
-4. Posts when has something meaningful
-5. Often provides perspective that settles debates
-
-**Special role**: The "wise elder" who cuts through noise
-
----
-
-## MCP Tool Architecture
-
-### Internal MCP Tools (Consumed by App)
-
-All tools live in one MCP server: `crow-chat-mcp`
-
-**Tool Categories**:
-1. Academic (Corvus): 4 tools
-2. Social/Web (Magpie): 3 tools
-3. Real-time Data (Raven): 4 tools
-4. Observational (Crow): 3 tools
-
-**Total**: ~14 core tools
-
-**Tool Definition Pattern**:
-```python
-@mcp.tool()
-async def tool_name(
-    param1: str,
-    param2: int = default_value
-) -> ReturnType:
-    """
-    Clear description of what tool does.
-    
-    Args:
-        param1: Description
-        param2: Description
-    
-    Returns:
-        Description of return value
-    """
-    # Implementation
-    pass
-```
-
-### External MCP Tools (Exposed by App)
-
-**The Gradio app exposes these tools**:
-
-```python
-@mcp.tool()
-async def ask_crow_council(question: str) -> dict:
-    """
-    Consult the Corvid Council expert panel.
-    
-    All four experts research using their specialized tools
-    and provide a synthesized answer with sources.
-    
-    Returns:
-        {
-            "consensus": str,  # Synthesized answer
-            "expert_opinions": [...],  # Individual takes
-            "sources": [...],  # All citations/links
-            "confidence": float  # 0-1
-        }
-    """
-    
-@mcp.tool()
-async def ask_specific_expert(
-    question: str,
-    expert: Literal["corvus", "magpie", "raven", "crow"]
-) -> dict:
-    """
-    Query one specific expert.
-    """
-    
-@mcp.tool()
-async def fact_check_claim(claim: str) -> dict:
-    """
-    Have the council verify a claim about crows.
-    
-    Returns:
-        {
-            "verdict": "verified" | "disputed" | "unknown",
-            "evidence": [...],
-            "expert_consensus": str
-        }
-    """
-```
-
----
-
-## Core Components
-
-### 1. CouncilOrchestrator
-**Purpose**: Coordinates character responses, manages conversation flow
-
-**Key Methods**:
-```python
-class CouncilOrchestrator:
-    async def process_query(question: str) -> CouncilResult:
-        """Main entry point for both UI and MCP"""
-        
-    async def facilitate_discussion(question, initial_responses) -> Discussion:
-        """Characters respond to each other"""
-        
-    async def synthesize_consensus(responses) -> str:
-        """Create unified answer for MCP calls"""
-```
-
-### 2. Character (Base Class)
-**Purpose**: Encapsulates character behavior
-
-**Key Methods**:
-```python
-class Character:
-    async def research_and_respond(question: str, context: list) -> Response:
-        """Use tools to research, generate response"""
-        
-    async def use_tools(question: str) -> list[ToolResult]:
-        """Call relevant MCP tools"""
-        
-    async def generate_message(question, tool_results, context) -> str:
-        """Compose message in character voice"""
-```
-
-### 3. MCPToolManager
-**Purpose**: Handles all MCP tool calls, error handling, rate limiting
-
-**Key Methods**:
-```python
-class MCPToolManager:
-    async def call_tool(tool_name: str, params: dict) -> ToolResult:
-        """Execute tool with error handling"""
-        
-    async def batch_call_tools(calls: list) -> list[ToolResult]:
-        """Call multiple tools efficiently"""
-```
-
-### 4. GradioInterface
-**Purpose**: Chat UI for direct human interaction
-
-**Key Methods**:
-```python
-def create_interface() -> gr.Blocks:
-    """Build Gradio chat interface"""
-    
-async def handle_user_message(message, history, state):
-    """Process user input, orchestrate responses"""
-    
-def display_tool_usage(character, tool_name):
-    """Show 'Character is using tool...' indicators"""
-```
-
----
-
-## Development Phases
-
-### Week 1: Core System (Days 1-7)
-
-#### Days 1-2: Foundation
-**Goal**: One character working with tools in Gradio
-
-- [ ] Set up project structure
-- [ ] Build `CouncilOrchestrator` skeleton
-- [ ] Implement `Character` base class
-- [ ] Create Corvus with 2 tools (search_papers, get_details)
-- [ ] Basic Gradio interface
-- [ ] Test: Corvus responds to question using tools
-
-**Success Metric**: Ask "Are crows smart?", see Corvus search papers and respond with citation
-
-#### Days 3-4: Second Character
-**Goal**: Two characters interacting
-
-- [ ] Add Magpie with 2 tools (search_web, search_social)
-- [ ] Implement character interaction (they respond to each other)
-- [ ] Staggered response timing (2-3 sec apart)
-- [ ] Test: Both characters respond differently to same question
-
-**Success Metric**: Two distinct personalities with different tool usage patterns visible
-
-#### Days 5-6: Third & Fourth Characters
-**Goal**: Full council assembled
-
-- [ ] Add Raven with 2 tools (get_environmental_data, search_news)
-- [ ] Add Crow with 2 tools (get_sightings, get_weather)
-- [ ] Four-way interaction patterns
-- [ ] Test: All four respond to question, some interact with each other
-
-**Success Metric**: Rich multi-agent discussion with varied tool usage
-
-#### Day 7: Week 1 Polish
-- [ ] Improve system prompts for distinct personalities
-- [ ] Add typing indicators
-- [ ] Better error handling for tool failures
-- [ ] Test conversation flows
-- [ ] Fix bugs
-
----
-
-### Week 2: External MCP & Polish (Days 8-14)
-
-#### Days 8-9: MCP Exposure
-**Goal**: Gradio app as MCP server
-
-- [ ] Implement external MCP tool exposure
-- [ ] `ask_crow_council()` tool
-- [ ] `ask_specific_expert()` tool
-- [ ] Test from Claude Desktop or MCP inspector
-- [ ] Ensure both interfaces use same orchestrator
-
-**Success Metric**: External tool call triggers internal discussion, returns synthesized response
-
-#### Days 10-11: Additional Tools & Refinement
-**Goal**: Complete tool sets
-
-- [ ] Add remaining tools (3rd-4th tool per character)
-- [ ] Implement `fact_check_claim()` external tool
-- [ ] Add tool chaining where appropriate
-- [ ] Better synthesis algorithm for consensus
-- [ ] Rate limiting and caching
-
-#### Days 12-13: Polish & Demo Prep
-**Goal**: Production ready
-
-- [ ] UI improvements (avatars, timestamps, theming)
-- [ ] Tool usage visualization
-- [ ] Demo mode with curated scenarios
-- [ ] Write comprehensive README
-- [ ] Create demo video showing both interfaces
-- [ ] Test edge cases
-
-#### Day 14: Deployment & Documentation
-**Goal**: Ship it
-
-- [ ] Deploy to Hugging Face Spaces
-- [ ] Verify both interfaces work publicly
-- [ ] Final testing in Claude Desktop
-- [ ] Polish documentation
-- [ ] Submit to hackathon
-- [ ] Buffer for last-minute issues
-
----
-
-## Technical Stack
-
-### Core
-- **Python 3.10+**
-- **Gradio 5.x** (with MCP capabilities)
-- **MCP SDK** (`pip install mcp`)
-- **OpenAI API** (gpt-4o-mini for characters)
-- **Anthropic API** (optional, for variety)
-
-### External APIs
-- **Semantic Scholar API** (academic papers) - Free, no key needed
-- **Brave Search API** or **SerpAPI** (web search) - Free tier available
-- **eBird API** (bird sightings) - Free with registration
-- **OpenWeather API** (weather data) - Free tier
-- **News API** (news search) - Free tier
-
-### Development Tools
-- **MCP Inspector** (for testing MCP tools)
-- **Claude Desktop** (for testing external tool usage)
-- **Git/GitHub** (version control)
-- **HF Spaces** (deployment)
-
----
-
-## File Structure
-
-```
-corvid-council/
-├── README.md
-├── requirements.txt
-├── app.py                          # Main Gradio app
-├── .env.example                    # API key template
-├── src/
-│   ├── __init__.py
-│   ├── orchestrator.py             # CouncilOrchestrator
-│   ├── character.py                # Character base class
-│   ├── characters/
-│   │   ├── __init__.py
-│   │   ├── corvus.py              # Corvus implementation
-│   │   ├── magpie.py              # Magpie implementation
-│   │   ├── raven.py               # Raven implementation
-│   │   └── crow.py                # Crow implementation
-│   ├── mcp/
-│   │   ├── __init__.py
-│   │   ├── server.py              # Internal MCP server
-│   │   ├── tools/
-│   │   │   ├── academic.py        # Corvus tools
-│   │   │   ├── social.py          # Magpie tools
-│   │   │   ├── realtime.py        # Raven tools
-│   │   │   └── observational.py   # Crow tools
-│   │   └── external.py            # External MCP tools (exposed by app)
-│   ├── ui/
-│   │   ├── __init__.py
-│   │   ├── interface.py           # Gradio interface
-│   │   └── components.py          # Custom UI components
-│   └── utils/
-│       ├── __init__.py
-│       ├── prompts.py             # System prompts for characters
-│       └── helpers.py             # Utility functions
-└── tests/
-    ├── test_orchestrator.py
-    ├── test_characters.py
-    └── test_mcp_tools.py
-```
-
----
-
-## Key Implementation Patterns
-
-### Pattern 1: Staggered Responses
-```python
-async def generate_responses(question, characters):
-    """Characters respond one at a time with delays"""
-    responses = []
-    
-    for i, character in enumerate(characters):
-        # Show typing indicator
-        show_typing(character.name)
-        
-        # Delay based on message length
-        await asyncio.sleep(random.uniform(2, 5))
-        
-        # Generate response (includes tool usage)
-        response = await character.research_and_respond(
-            question, 
-            context=responses  # See previous responses
-        )
-        
-        responses.append(response)
-        
-    return responses
-```
-
-### Pattern 2: Tool Usage Display
-```python
-async def use_tools_with_display(character, tools_to_use):
-    """Show tool usage in UI"""
-    results = []
-    
-    for tool in tools_to_use:
-        # Show in UI: "Corvus is searching papers..."
-        update_ui(f"{character.name} is using {tool.name}...")
-        
-        try:
-            result = await mcp_client.call_tool(tool.name, tool.params)
-            results.append(result)
-        except Exception as e:
-            # Show error gracefully
-            update_ui(f"⚠️ Tool {tool.name} failed, continuing...")
-            
-    return results
-```
-
-### Pattern 3: Character Decides Which Tools
-```python
-async def research_and_respond(self, question, context):
-    """Character decides which tools to use"""
-    
-    # Ask LLM what tools to use
-    tool_plan = await self.llm.generate(
-        system_prompt=self.system_prompt,
-        user_prompt=f"""
-        Question: {question}
-        Available tools: {self.tools}
-        
-        Which tools should you use? Return JSON list.
-        """
-    )
-    
-    # Execute chosen tools
-    tool_results = await self.execute_tools(tool_plan)
-    
-    # Generate response using results
-    message = await self.llm.generate(
-        system_prompt=self.system_prompt,
-        user_prompt=f"""
-        Question: {question}
-        Tool results: {tool_results}
-        
-        Write your response in character.
-        """
-    )
-    
-    return message
-```
-
-### Pattern 4: Consensus Synthesis
-```python
-async def synthesize_consensus(self, responses):
-    """Create unified answer for MCP calls"""
-    
-    # Extract key points from each response
-    synthesis_prompt = f"""
-    Four experts answered the same question. Synthesize their responses:
-    
-    Corvus (Academic): {responses['corvus']}
-    Magpie (Social): {responses['magpie']}
-    Raven (Activist): {responses['raven']}
-    Crow (Observer): {responses['crow']}
-    
-    Create a consensus answer that:
-    - Combines their insights
-    - Notes where they agree/disagree
-    - Includes all sources
-    - Rates overall confidence
-    """
-    
-    return await llm.generate(synthesis_prompt)
-```
-
----
-
-## Common Pitfalls & Solutions
-
-### Pitfall 1: Rate Limiting
-**Problem**: Hitting API rate limits with multiple characters
-
-**Solutions**:
-- Stagger API calls (2-3 seconds apart)
-- Use cheaper models (gpt-4o-mini)
-- Cache tool results
-- Implement exponential backoff
-
-### Pitfall 2: Tool Failures
-**Problem**: External API is down or returns error
-
-**Solutions**:
-- Always wrap tool calls in try-except
-- Have fallback responses
-- Show errors gracefully to user
-- Continue conversation even if one tool fails
-
-### Pitfall 3: Repetitive Conversations
-**Problem**: Characters say similar things
-
-**Solutions**:
-- Strong, distinct system prompts
-- Different tool sets force different perspectives
-- Include context of previous responses
-- Add personality quirks (Magpie posts old news, etc.)
-
-### Pitfall 4: Slow Responses
-**Problem**: Waiting for multiple LLM + tool calls is slow
-
-**Solutions**:
-- Show typing indicators
-- Stream responses where possible
-- Call tools in parallel when they don't depend on each other
-- Pre-generate demo scenarios for judging
-
-### Pitfall 5: MCP Exposure Not Working
-**Problem**: External apps can't call your tools
-
-**Solutions**:
-- Test with MCP Inspector first
-- Check CORS settings
-- Verify tool schemas are valid
-- Ensure server is publicly accessible
-- Check HF Spaces networking settings
-
----
-
-## Testing Strategy
-
-### Unit Tests
-- Individual tools return expected format
-- Characters generate appropriate responses
-- Orchestrator handles edge cases
-
-### Integration Tests
-- Full conversation flow works
-- Both interfaces (UI and MCP) work
-- Tool failures handled gracefully
-
-### Manual Testing Scenarios
-
-**Scenario 1: Basic Question**
-- Ask: "Are crows smart?"
-- Expect: All 4 respond, use tools, cite sources
-
-**Scenario 2: Fact-Checking**
-- Magpie posts dubious claim
-- Expect: Corvus or Raven fact-checks it
-
-**Scenario 3: External MCP Call**
-- From Claude Desktop: call `ask_crow_council("Do crows use tools?")`
-- Expect: Structured response with consensus
-
-**Scenario 4: Old News**
-- Magpie shares old content
-- Expect: Others notice and comment (first few times)
-
-**Scenario 5: Tool Failure**
-- Simulate API down
-- Expect: Graceful degradation, conversation continues
-
----
-
-## Demo Script
-
-### Demo 1: Gradio UI (2 minutes)
-1. Open interface, introduce the four experts
-2. Ask: "Can crows recognize individual humans?"
-3. Show:
-   - Characters using different tools
-   - Tool usage indicators
-   - Different personality styles
-   - Sources and citations
-4. Highlight: Real-time research, transparent process
-
-### Demo 2: MCP Tool Usage (2 minutes)
-1. Switch to Claude Desktop
-2. Show available tools: `ask_crow_council`, etc.
-3. Ask same question through MCP tool
-4. Show:
-   - Same backend process (quick view of Gradio)
-   - Structured response returned
-   - Synthesized consensus with sources
-5. Highlight: Same intelligence, two interfaces
-
-### Demo 3: Architecture Explanation (1 minute)
-1. Show diagram
-2. Explain: MCP tools consuming MCP tools
-3. Point out: Composability, extensibility
-4. Mention: Could add more experts, more tools
-
----
-
-## Success Criteria
-
-### Minimum Viable Product (Must Have)
-- ✅ 4 characters with distinct personalities
-- ✅ 8-10 working MCP tools (2-3 per character)
-- ✅ Gradio chat interface
-- ✅ External MCP tool exposure (ask_crow_council)
-- ✅ Both interfaces work reliably
-- ✅ Deployed to HF Spaces
-- ✅ Good README and demo
-
-### Stretch Goals (Nice to Have)
-- ✅ 12-15 tools (full tool sets)
-- ✅ Tool chaining (one tool's output → another)
-- ✅ Advanced interaction patterns (quirk decay)
-- ✅ Memory across sessions
-- ✅ Beautiful UI with animations
-- ✅ Comprehensive error handling
-
-### Judging Criteria (What Matters)
-1. **Technical sophistication**: Multi-tool MCP system
-2. **Creativity**: Novel use of MCP (agents-as-tools)
-3. **Completeness**: Both interfaces work well
-4. **Demo quality**: Clear, impressive, functional
-5. **Documentation**: Easy to understand and extend
-
----
-
-## Resources
-
-### APIs
-- Semantic Scholar: https://api.semanticscholar.org/
-- eBird: https://documenter.getpostman.com/view/664302/S1ENwy59
-- OpenWeather: https://openweathermap.org/api
-- News API: https://newsapi.org/
-
-### Documentation
-- MCP Spec: https://spec.modelcontextprotocol.io/
-- Gradio Docs: https://www.gradio.app/docs
-- HF Course: https://huggingface.co/learn/mcp-course/
-
-### Tools
-- MCP Inspector: (check course for link)
-- Claude Desktop: https://claude.ai/download
-
----
-
-## Quick Start Commands
-
-```bash
-# Clone and setup
-git clone <your-repo>
-cd corvid-council
-pip install -r requirements.txt
-
-# Set up environment
-cp .env.example .env
-# Edit .env with your API keys
-
-# Run locally
-python app.py
-
-# Deploy to HF Spaces
-git push hf main
-```
-
----
-
-## Support Checklist for LLMs
-
-When asking an LLM for help, provide:
-- [ ] This development guide
-- [ ] Specific file you're working on
-- [ ] Error message if debugging
-- [ ] What you've tried already
-- [ ] Specific question or task
-
-**Example prompt**:
-```
-I'm building the Corvid Council project (see attached dev guide).
-I'm working on [specific component].
-I'm trying to [specific task].
-I'm getting [error/issue].
-I've tried [what you tried].
-Can you help me [specific ask]?
-```
-
----
-
-## Contact & Resources
-
-**Hackathon**: Gradio Agents & MCP Hackathon - Winter 25  
-**Track**: Building MCP (Creative)  
-**Tag**: `building-mcp-track-creative`
-
-Good luck! Build something amazing. 🎯

notes_etc/development_guide_02.txt

@@ -1,181 +0,0 @@
-Project Overview
-
-Name: Cluas
-Hackathon / Track: Gradio Agents & MCP Hackathon – Winter 25, Creative Track
-Concept: A multi-agent MCP system where four AI “crow experts” discuss topics, each using specialized tools. Users can either observe the panel in a Gradio chat interface or query it programmatically via MCP.
-
-Hook:
-“What if you could consult a panel of AI experts that not only debates, researches, and cross-verifies claims but also maintains a shared memory across sessions?”
-
-Architecture Overview
-External User/App (Claude Desktop, etc.)
-    ↓ (calls MCP tool)
-ask_crow_council(question)
-    ↓
-Gradio App (MCP server)
-    ↓
-CouncilOrchestrator
-    ↓
-4 Character Agents (Corvus, Magpie, Raven, Crow)
-    ↓
-Character-Specific MCP Tools (~12–15 total)
-    ↓
-External APIs (Semantic Scholar, eBird, Weather, News)
-    ↓
-Shared AgentMemory (JSON / DB)
-    ↓
-Synthesized Response → User
-
-
-Key Differences vs. earlier plan:
-
-AgentMemory is first-class: acts as shared context, not just caching.
-
-Cache is memory: supports cross-agent recall, deduplication, “didn’t we discuss this?”
-
-Tool orchestration is separate from UI: backend drives both Gradio interface and MCP endpoint.
-
-Characters
-Character	Role	Personality	Core Tools	Behavior
-Corvus	Scholar	Analytical, cautious, thorough	search_academic, get_paper_details, verify_claim, citation_network	Reads literature, fact-checks, posts rarely but substantively
-Magpie	Enthusiast	Social, rapid-fire, excited	search_social, search_web, find_trending	Posts frequently, may repeat info, creates conversational energy
-Raven	Activist	Urgent, confrontational, data-driven	get_environmental_data, search_news, fact_check_claim, analyze_sentiment	Searches real-time threats, challenges others’ claims
-Crow	Observer	Calm, patient, contemplative	get_sightings, get_weather_patterns, analyze_temporal_patterns	Rarely posts, synthesizes patterns, provides perspective
-
-Notes:
-
-Each character writes in a distinct voice.
-
-AgentMemory is referenced when appropriate to recall past papers, claims, or events.
-
-Tools are abstracted behind MCP methods for modularity.
-
-MCP Tool Architecture
-
-Internal MCP Tools (Character Tools):
-
-Academic (Corvus): 4 tools
-
-Social/Web (Magpie): 3 tools
-
-Real-time Data (Raven): 4 tools
-
-Observational (Crow): 3 tools
-
-External MCP Tools (Exposed via Gradio App):
-
-@mcp.tool()
-async def ask_crow_council(question: str) -> dict:
-    """Consult all 4 characters; return synthesized response with sources."""
-
-@mcp.tool()
-async def ask_specific_expert(question: str, expert: Literal["corvus", "magpie", "raven", "crow"]) -> dict:
-    """Query a single character."""
-
-@mcp.tool()
-async def fact_check_claim(claim: str) -> dict:
-    """Have the council verify a claim using AgentMemory and tools."""
-
-
-AgentMemory Integration:
-
-Logs items with metadata: title, DOI/arXiv link, snippet, timestamp, tags.
-
-Retrieval methods: get_recent(days), get_by_tag(tag), search_title(query).
-
-Can prune old memories; supports both short-term and long-term context.
-
-Project Structure (Updated for Modularity)
-cluas/
-├── README.md
-├── .env.example
-├── src/
-│   ├── __init__.py
-│   ├── orchestrator.py          # CouncilOrchestrator
-│   ├── character.py             # Character base class
-│   ├── characters/
-│   │   ├── corvus.py
-│   │   ├── magpie.py
-│   │   ├── raven.py
-│   │   └── crow.py
-│   ├── mcp/
-│   │   ├── server.py            # Internal MCP server
-│   │   ├── tools/
-│   │   │   ├── academic.py
-│   │   │   ├── social.py
-│   │   │   ├── realtime.py
-│   │   │   └── observational.py
-│   │   └── external.py          # Exposed MCP tools
-│   ├── memory/
-│   │   └── agent_memory.py      # Shared memory / cache
-│   ├── ui/
-│   │   ├── interface.py
-│   │   └── components.py
-│   └── utils/
-│       ├── prompts.py
-│       └── helpers.py
-└── tests/
-    ├── test_orchestrator.py
-    ├── test_characters.py
-    └── test_agent_memory.py
-
-Development Phases (Current Scope)
-Phase 1 – Core MVP
-
-Corvus implemented with 2 academic tools.
-
-Basic AgentMemory operational (short-term storage).
-
-Basic Gradio chat interface.
-
-Tool orchestration scaffolding in place.
-
-Phase 2 – Additional Characters & Tools
-
-Add Magpie and Raven with partial tools.
-
-Implement staggered responses, typing indicators.
-
-Ensure memory integration across agents.
-
-Phase 3 – Full Council & MCP Exposure
-
-Crow added.
-
-Expose ask_crow_council() and ask_specific_expert().
-
-Test multi-agent synthesis and external calls.
-
-Phase 4 – Polish & Deploy
-
-Error handling, retries, and rate limiting.
-
-Memory pruning, long-term storage optional (Supabase / MongoDB).
-
-UI/UX polish for Gradio.
-
-Demo-ready, hackathon-ready deployment.
-
-Key Implementation Patterns
-
-Tool orchestration per character – each agent decides which tools to use, executes asynchronously.
-
-Staggered responses – enhances human-like timing.
-
-Memory-driven context – prior discussions inform current responses.
-
-Consensus synthesis – LLM generates unified response for MCP output.
-
-Technical Stack
-
-Python 3.13 (uv-managed)
-
-Gradio 5.x with MCP
-
-MCP SDK for server and tools
-
-LLM: gpt-4o-mini (Anthropic optional)
-
-APIs: Semantic Scholar, eBird, News API, OpenWeather
-
-Data/Memory: JSON for now, possible future DB (Supabase or MongoDB)

notes_etc/exposing_cluas_as_an_MCP.py

@@ -1,14 +0,0 @@
-# figure something a bit like this
-
-
-@mcp.tool()
-async def ask_crow_council(question: str) -> dict:
-    """Consult all 4 characters; return synthesized response with sources."""
-
-@mcp.tool()
-async def ask_specific_expert(question: str, expert: Literal["corvus", "magpie", "raven", "crow"]) -> dict:
-    """Query a single character."""
-
-@mcp.tool()
-async def fact_check_claim(claim: str) -> dict:
-    """Have the council verify a claim using AgentMemory and tools."""

notes_etc/possible_architecture_diagram.txt

@@ -1,48 +0,0 @@
-                ┌─────────────────────────────────────┐
-                │           User / Client             │
-                │ (Claude Desktop, App, API caller)   │
-                └────────────────────┬────────────────┘
-                                     │ ask_council()
-                                     ▼
-                ┌─────────────────────────────────────┐
-                │      Corvid Council MCP Server      │
-                │   (Gradio chat + MCP tool handler)  │
-                └────────────────────┬────────────────┘
-                                     │ orchestrates
-                                     ▼
-                ┌─────────────────────────────────────┐
-                │        Council Orchestrator         │
-                │ - Calls individual agents           │
-                │ - Coordinates group chat flow       │
-                └────────────────────┬────────────────┘
-                                     │
-         ┌───────────────────────────┼─────────────────────────────┐
-         ▼                           ▼                             ▼
-┌─────────────────┐       ┌─────────────────┐          ┌─────────────────┐
-│     Corvus      │       │     Magpie      │          │     Raven       │
-│ (Academic AI)   │       │ (Trends AI)     │          │ (Deep-Focus AI)│
-│ PubMed/S2 API   │       │ Web/Social API  │          │ Feeds/Alerts    │
-└───────┬─────────┘       └───────┬─────────┘          └───────┬─────────┘
-        │                           │                             │
-        └──────────────┬────────────┴────────────┬───────────────┘
-                       ▼                           ▼
-                ┌─────────────────────────────────────┐
-                │            Agent Memory             │
-                │  (shared JSON/DB knowledge log)     │
-                │ - recent papers, trends, facts      │
-                │ - tags, timestamps, DOIs            │
-                │ - enables recall & “inside jokes”   │
-                └─────────────────────────────────────┘
-                                     │
-                                     ▼
-                ┌─────────────────────────────────────┐
-                │        LLM Consensus Layer           │
-                │ - builds final group answer          │
-                │ - personality + expertise mixing     │
-                └─────────────────────────────────────┘
-                                     │
-                                     ▼
-                ┌─────────────────────────────────────┐
-                │          Final Output               │
-                │  (chat replay + structured answer)  │
-                └─────────────────────────────────────┘

notes_etc/possible_project_structure.txt

@@ -1,32 +0,0 @@
-corvid-council/
-├── README.md
-├── .env.example
-├── src/
-│   ├── __init__.py
-│   ├── orchestrator.py          # CouncilOrchestrator
-│   ├── character.py             # Character base class
-│   ├── characters/
-│   │   ├── corvus.py
-│   │   ├── magpie.py
-│   │   ├── raven.py
-│   │   └── crow.py
-│   ├── mcp/
-│   │   ├── server.py            # Internal MCP server
-│   │   ├── tools/
-│   │   │   ├── academic.py
-│   │   │   ├── social.py
-│   │   │   ├── realtime.py
-│   │   │   └── observational.py
-│   │   └── external.py          # Exposed MCP tools
-│   ├── memory/
-│   │   └── agent_memory.py      # Shared memory / cache
-│   ├── ui/
-│   │   ├── interface.py
-│   │   └── components.py
-│   └── utils/
-│       ├── prompts.py
-│       └── helpers.py
-└── tests/
-    ├── test_orchestrator.py
-    ├── test_characters.py
-    └── test_agent_memory.py

pyproject.toml

@@ -5,6 +5,7 @@ description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.13"
 dependencies = [
+    "fastmcp>=2.13.1",
     "feedparser>=6.0.12",
     "gradio[mcp,oauth]==6.0.0.dev4",
     "mcp>=1.20.0",

reviews/changes.md

@@ -1,220 +0,0 @@
-# Change Log
-
-**Date:** 2025-11-15
-
-This document tracks notable changes in the "Corvid Council" repository.
-
----
-
-### November 15, 2025
-
-#### Summary of Changes
-
-A code snippet related to a potential PubMed API implementation was added as comments to `src/cluas_mcp/common/api_clients.py`. No other functional or structural changes were observed in the repository. The core logic, file structure, and administrative files (`README.md`, `.gitignore`, `requirements.txt`) remain the same as the last review.
-
-#### Detailed Changes
-
--   **Modified `src/cluas_mcp/common/api_clients.py`**:
-    -   A block of commented-out Python code was added. This code demonstrates how to use the `Bio.Entrez` library to search PubMed for articles related to corvids, parse the results, and extract details like title, authors, abstract, and DOI.
-
-#### Analysis
-
--   **Significant:**
-    -   The change itself is minor (it's only comments), but it's significant in what it signals: active exploration of how to implement the `PubMedClient`. This is a direct move towards fulfilling one of the key requirements for making the `Corvus` character fully functional.
-
--   **Good:**
-    -   This is a positive step. It shows that the next phase of development is being actively researched. The example code is relevant and provides a clear path for the real implementation.
-    -   Using a well-known library like `BioPython` is a good choice for interacting with NCBI services.
-
--   **Concerning:**
-    -   There are no concerns with this change. It's a healthy sign of a project in the early stages of development. The only minor point is that the code is commented out in the main source file rather than being in a separate experimental script, but this is a trivial issue at this stage.
-
----
-
-### November 18, 2025
-
-#### Summary of Changes
-
-A new `notes_etc/` directory was added, containing detailed development guides and an architecture diagram. Crucially, the previously empty `src/cluas_mcp/common/formatting.py` file was implemented, fixing a critical import error.
-
-#### Detailed Changes
-
--   **New Directory `notes_etc/`**:
-    -   `development_guide_01.md`: A comprehensive guide detailing the project's concept, architecture, characters, MCP tools, development phases, and technical stack.
-    -   `development_guide_02.txt`: A more concise version of the guide.
-    -   `possible_lightweight_architecture_diagram.txt`: A text-based visualization of the system architecture.
--   **Modified `src/cluas_mcp/common/formatting.py`**:
-    -   Implemented the `snippet_abstract` function to truncate text intelligently.
-    -   Implemented the `format_authors` function to format author lists.
-
-#### Analysis
-
--   **Significant:**
-    -   The implementation of the functions in `formatting.py` is the most significant change, as it directly unblocks the `Corvus` agent and makes a core piece of the application runnable for the first time.
-    -   The addition of the development guides provides invaluable context and a clear roadmap for the project's future.
-
--   **Good:**
-    -   These changes are overwhelmingly positive. The bug fix is a major step forward, and the planning documents demonstrate a clear and well-thought-out vision for the project. The architecture is sound, and the character-based agent design is creative and well-defined.
-
--   **Concerning:**
-    -   There are no concerning changes. The project is progressing logically and is now in a much better state than before. The next logical step is to implement the placeholder API clients.
-
----
-
-### November 18, 2025 (Afternoon)
-
-#### Summary of Changes
-
-Significant progress has been made on the API clients. The `ArxivClient` has been fully implemented, and the `PubMedClient` now has a functional search method that retrieves article IDs. More planning documents were also added.
-
-#### Detailed Changes
-
--   **Modified `src/cluas_mcp/common/api_clients.py`**:
-    -   **`ArxivClient`**: Now contains a full implementation. It builds a query, fetches data from the arXiv API, parses the Atom feed, and returns a list of structured dictionaries containing paper details.
-    -   **`PubMedClient`**: A `pubmed_search` method has been implemented to perform the `esearch` step of the API interaction. It correctly builds a complex query and uses a helper method `parse_id_list` to extract PubMed IDs from the XML response. The `efetch` step is not yet implemented.
-    -   **`SemanticScholarClient`**: Remains a placeholder.
--   **New Files in `notes_etc/`**:
-    -   `possible_architecture_diagram.txt`: A more detailed architecture diagram.
-    -   `possible_project_structure.txt`: A proposed target file structure.
-    -   `exposing_cluas_as_an_MCP.py`: A code snippet showing how the app might expose MCP tools.
-
-#### Analysis
-
--   **Significant:**
-    -   The implementation of the `ArxivClient` and the first half of the `PubMedClient` is the most significant change. This represents the first major piece of core feature development, moving the project from planning and bug-fixing into active implementation.
-
--   **Good:**
-    -   This is a huge step in the right direction. The code is functional and well-structured. The `Corvus` agent now has a working data source (arXiv) and a partially working one (PubMed). This directly addresses the main blocker and builds momentum.
-
--   **Concerning:**
-    -   There are no concerning changes. The progress is excellent. The clear next step is to complete the `PubMedClient` by adding the `efetch` logic to retrieve full article data using the IDs from `pubmed_search`.
-
----
-
-### November 18, 2025 (Late Afternoon)
-
-#### Summary of Changes
-
-A significant refactoring has occurred. The `PubMedClient` has been moved to a new `academic` submodule, and a robust, retry-enabled HTTP fetching utility has been created in `src/cluas_mcp/common/http.py`.
-
-#### Detailed Changes
-
--   **New Directory `src/cluas_mcp/academic/`**:
-    -   The `PubMedClient` has been moved to `src/cluas_mcp/academic/pubmed_client.py`.
--   **New File `src/cluas_mcp/common/http.py`**:
-    -   This file introduces a `fetch_with_retry` function that uses the `tenacity` library to provide exponential backoff for HTTP requests. This makes API calls more resilient.
--   **Modified `src/cluas_mcp/academic/pubmed_client.py`**:
-    -   The refactored `PubMedClient` now uses the new `fetch_with_retry` utility for its API calls.
--   **Modified `pyproject.toml`**:
-    -   The `tenacity` library has been added as a project dependency.
--   **Modified `src/cluas_mcp/common/api_clients.py`**:
-    -   This file still contains the old `PubMedClient` code, creating duplication.
-
-#### Analysis
-
--   **Significant:**
-    -   The architectural refactoring is highly significant. It shows a move towards a more organized, maintainable, and robust codebase, aligning with the project's planning documents. The creation of a shared, resilient HTTP utility is a major improvement.
-
--   **Good:**
-    -   The new `http.py` module is excellent and demonstrates best practices for consuming external APIs.
-    -   The file structure is becoming cleaner and more logical.
-
--   **Concerning:**
-    -   **Code Duplication:** The most pressing issue is the duplicated `PubMedClient` code. The old implementation in `src/cluas_mcp/common/api_clients.py` is now obsolete and should be removed to prevent confusion and future bugs. The other clients in that file should also be refactored into their own modules.
-
----
-
-### November 18, 2025 (Evening)
-
-#### Summary of Changes
-
-A massive and highly positive refactoring has been completed. The API clients have been fully separated into their own modules, the `PubMedClient` is now feature-complete, a new `AcademicSearch` facade provides a single point of entry, domain keywords have been separated, and—most importantly—tests have been added for the API clients.
-
-#### Detailed Changes
-
--   **Completed Refactoring**:
-    -   The API clients now live in `src/cluas_mcp/academic/` as `pubmed.py`, `arxiv.py`, and `semantic_scholar.py`.
-    -   The old `src/cluas_mcp/common/api_clients.py` file still exists but is now entirely obsolete.
--   **Completed `PubMedClient`**:
-    -   The client in `academic/pubmed.py` now includes a `fetch_articles` method, completing the `esearch`/`efetch` workflow.
--   **New `AcademicSearch` Facade**:
-    -   `academic/academic_search.py` provides a single `academic_search` function that calls all underlying clients, simplifying future use.
--   **Domain Knowledge Separation**:
-    -   `src/cluas_mcp/domain/keywords.py` now stores keyword lists, separating this data from the client logic.
--   **New Tests**:
-    -   `tests/test_arxiv.py` and `tests/test_pubmed.py` have been added, providing actual tests for the API clients.
-
-#### Analysis
-
--   **Significant:**
-    -   This is a pivotal update. The project has rapidly matured from a proof-of-concept to a well-structured and tested data access layer. The addition of tests is the most significant and important change, as it provides a foundation for reliable future development.
-
--   **Good:**
-    -   The architecture is now clean, modular, and extensible.
-    -   The separation of concerns (clients, domain data, facades) is excellent.
-    -   The data layer for the `Corvus` agent is now functionally complete and robust.
-
--   **Concerning:**
-    -   The only remaining issue is the obsolete `src/cluas_mcp/common/api_clients.py` file. It should be deleted to finalize the cleanup.
-
----
-
-### November 18, 2025 (Night)
-
-#### Summary of Changes
-
-The final placeholder API client, `SemanticScholarClient`, has been implemented and tested. The data access layer for the `Corvus` agent is now 100% complete.
-
-#### Detailed Changes
-
--   **`SemanticScholarClient` Implemented**:
-    -   The client in `src/cluas_mcp/academic/semantic_scholar.py` has been fully implemented. It queries the Semantic Scholar API, requests specific fields, and normalizes the response into the project's standard format.
--   **New Test for `SemanticScholarClient`**:
-    -   A new test file, `tests/test_semantic_scholar.py`, was added to validate the new client.
--   **`PubMedClient` Improved**:
-    -   The `pubmed.py` client was improved to extract more data (DOI, PubMed link) and includes better error handling for parsing individual articles.
--   **Facade Renamed**:
-    -   The `academic_search.py` facade was renamed to `academic_search_entry.py`.
-
-#### Analysis
-
--   **Significant:**
-    -   The completion of the final API client is a major milestone. The `academic_search` facade is now fully operational, capable of querying and aggregating results from all three target data sources.
-
--   **Good:**
-    -   The project continues its excellent momentum. The practice of adding tests for all new code is being maintained, which is crucial for long-term stability. The data access layer is now a polished, production-ready component.
-
--   **Concerning:**
-    -   There are no new concerns. The only outstanding task from the refactoring is to delete the obsolete `src/cluas_mcp/common/api_clients.py` file.
-
----
-
-### November 18, 2025 (Final)
-
-#### Summary of Changes
-
-This update finalizes the data access layer by improving the test infrastructure and cleaning up the last piece of technical debt.
-
-#### Detailed Changes
-
--   **Test Suite Refactoring**:
-    *   Tests for individual API clients have been moved to a dedicated `tests/clients/` directory.
-    *   A new `tests/integration/` directory was created for higher-level tests, starting with a test for the `academic_search_entrypoint`.
-    *   A `tests/conftest.py` file was added to manage the system path for the test suite, a standard best practice.
--   **Facade Hardening**:
-    *   The `academic_search_entrypoint` was improved with `try...except` blocks to ensure that a failure in one API client does not prevent the others from returning results.
--   **Technical Debt Removed**:
-    *   The obsolete `src/cluas_mcp/common/api_clients.py` file has been deleted.
--   **Dependencies Formalized**:
-    *   `pytest` was officially added to the `pyproject.toml` dependencies.
-
-#### Analysis
-
--   **Significant:**
-    -   The cleanup of the final piece of technical debt and the formalization of a layered testing strategy mark the official completion of the data access layer. This component is now stable, robust, and maintainable.
-
--   **Good:**
-    -   All changes are positive and demonstrate a commitment to high-quality, professional software development practices. The separation of client-level tests from integration tests is particularly noteworthy.
-
--   **Concerning:**
-    -   There are no concerns whatsoever. The project is in an ideal state to begin building the application logic.

reviews/code_review_2025-11-15_14-30-00.md

@@ -1,70 +0,0 @@
-# Code Review: Cluas MCP
-
-**Date:** 2025-11-15
-
-## a) High-Level Summary
-
-This repository, "Cluas," contains a Python-based project that appears to be a multi-character or multi-agent system for academic research. The name "Cluas" and the character names (Corvus, Raven, Magpie, Crow) all relate to corvids, a family of intelligent birds, suggesting a theme of intelligence and information gathering.
-
-The core functionality revolves around searching academic paper databases (arXiv, PubMed, Semantic Scholar) based on user queries. The system is designed with a fallback mechanism, starting with PubMed and progressing to other sources if no results are found. It includes a caching mechanism to speed up repeated searches.
-
-The project is structured into several components:
-
--   `characters`: Different agents with specific functionalities. So far, only `CorvusMCP` is implemented.
--   `cluas_mcp`: The core logic, including API clients for academic search engines, caching, and data formatting.
--   `gradio`: Suggests a web interface for interacting with the system, though it is currently empty.
--   `tests`: Unit tests for the `CorvusMCP` character, indicating a commitment to testing.
-
-## b) Detailed Component Description
-
-### `CorvusMCP` Character
-
-The `CorvusMCP` class in `src/characters/corvus.py` is the most developed part of the application. Its primary role is to search for academic papers.
-
--   **Search Priority:** It follows a clear search strategy: PubMed -> Semantic Scholar -> arXiv. This is a sensible approach, as PubMed is a high-quality, curated database for biomedical literature.
--   **Caching:** It uses a `CacheManager` to store search results. When a search is requested, it first checks the cache for the given query. If found, it returns the cached results, avoiding redundant API calls. If not, it performs the search, and the new results are cached for future use.
--   **API Clients:** It utilizes `PubMedClient`, `SemanticScholarClient`, and `ArxivClient` from `src/cluas_mcp/common/api_clients.py`. Currently, only the `ArxivClient` has a concrete implementation; the others are placeholders.
--   **Data Formatting:** After fetching results, it cleans and formats them into a consistent structure, including title, abstract, authors, publication date, DOI, and a link.
-
-### API Clients and Caching
-
--   **`api_clients.py`**: This file defines classes for interacting with external academic APIs. The `ArxivClient` is functional and constructs a search query that combines the user's query with a predefined list of keywords related to corvids. This suggests the system has a specialized focus.
--   **`cache.py`**: The `CacheManager` provides a simple file-based JSON cache. It reads and writes to a `cache.json` file, which is effective for a small-scale application.
-
-### Testing
-
-The `tests/test_corvus.py` file contains unit tests for the `CorvusMCP` class. The tests use `unittest.mock` to patch the API clients and cache manager, allowing for isolated testing of the character's logic. The tests cover several scenarios:
-
--   Cache hits.
--   Successful searches with PubMed.
--   Fallback to Semantic Scholar when PubMed returns no results.
--   Fallback to arXiv when both PubMed and Semantic Scholar fail.
-
-This demonstrates good software development practices.
-
-## c) Opinionated Breakdown and Future Development
-
-### What's Good
-
--   **Clear Structure:** The project is well-organized, with a logical separation of concerns (characters, core logic, web interface, tests).
--   **Intelligent Design:** The fallback search strategy and caching mechanism are well-thought-out features that improve both the quality of results and the performance of the system.
--   **Thematic Cohesion:** The corvid theme is creative and consistently applied, which can help in building a strong identity for the project.
--   **Test Coverage:** The presence of unit tests for the main character is a great sign of a healthy codebase.
-
-### Suggestions for Improvement
-
--   **Implement Placeholder Clients:** The `PubMedClient` and `SemanticScholarClient` are currently placeholders. Implementing these would be the highest priority next step to make `CorvusMCP` fully functional.
--   **Expand Character Roles:** The other characters (`Raven`, `Magpie`, `Crow`) are currently empty files. Their roles should be defined and implemented. Based on the `blah.py` file, it seems the intention is for them to have distinct functions:
-    -   `magpie.find_trending("topic")`: Could focus on identifying popular or recent papers.
-    -   `raven.get_environmental_data("location")`: Could specialize in a different type of data, perhaps from different sources.
-    -   `crow.analyze_patterns("dataset")`: Might be geared towards data analysis or trend detection within a set of papers.
--   **Develop the Gradio UI:** The `gradio/app.py` is empty. Building a simple web interface would make the system much more accessible and usable.
--   **Refine the `ArxivClient`:** The `ArxivClient` currently combines the user's query with a hardcoded list of corvid-related keywords. This should be made more flexible, perhaps by allowing the character or user to specify the topic or domain of interest. The `search_academic_papers` function in `tools.py` seems to be a step in this direction.
--   **Configuration Management:** API keys or other configuration settings should not be hardcoded. A configuration file or environment variables should be used.
--   **Error Handling:** The API clients should have more robust error handling for network issues or unexpected API responses.
-
-### Future Expectations
-
-I expect the project to continue developing by fleshing out the existing structure. The immediate next steps would be to implement the remaining API clients and then define the unique functionalities of the other characters. Once the core logic is more complete, the focus will likely shift to building the Gradio web interface to allow users to interact with the different characters.
-
-Overall, this is a promising project with a solid foundation and a clear, creative vision. The code is clean, well-structured, and demonstrates good engineering practices.

reviews/code_review_2025-11-15_15-00-00.md

@@ -1,62 +0,0 @@
-# Code Review: Cluas MCP (Second Pass)
-
-**Date:** 2025-11-15
-
-## a) High-Level Summary
-
-This second review of the "Cluas" repository shows some evolution from the initial version, primarily with the introduction of a shared memory system. The project remains a Python-based, multi-agent framework for academic research, themed around corvids.
-
-The core functionality is still centered on the `CorvusMCP` character, which searches academic databases. The most significant change is the replacement of the simple cache with an `AgentMemory` system. This new system is designed to create a shared context between agents by logging discovered items (papers) and allowing retrieval based on recency, tags, or title.
-
-The overall structure is largely the same: `characters` for agents, `cluas_mcp` for core logic, a placeholder `gradio` UI, and `tests`. However, many of the previously identified issues, such as placeholder API clients, empty character files, and clutter in the source directory, persist.
-
-## b) Detailed Component Description
-
-### `CorvusMCP` and `AgentMemory`
-
-The `CorvusMCP` character in `src/characters/corvus.py` has been updated to integrate with the new `AgentMemory` system.
-
--   **Memory Integration:** Instead of a simple query cache, `CorvusMCP` now interacts with `AgentMemory`. When `search_papers` finds a paper, it logs it as a memory item, tagging it with "academic_search" and noting that "Corvus" mentioned it. This creates a persistent, shared knowledge base.
--   **Contextual Results:** The `search_papers` function now has a `memory_days` parameter. When used, it appends recently mentioned items from the shared memory to the search results. This allows the character to provide contextually aware responses that include not just new findings but also recently discussed topics.
--   **`AgentMemory` Class:** Located in `src/cluas_mcp/common/memory.py`, this class provides a more sophisticated storage mechanism than the previous `CacheManager`. It stores items in a JSON file with structured data, including timestamps, snippets, DOIs, and tags. It supports various retrieval methods:
-    -   `get_recent(days)`: Fetches items referenced within a specific timeframe.
-    -   `get_by_tag(tag)`: Retrieves items with a given tag.
-    -   `search_title(query)`: Performs a simple text search on titles.
-    -   `prune_long_term()`: A utility to clean up very old memories.
-
-### Persisting Issues
-
--   **Placeholder API Clients:** The `PubMedClient` and `SemanticScholarClient` in `src/cluas_mcp/common/api_clients.py` are still not implemented. This remains the biggest blocker to the `CorvusMCP`'s full functionality, as it can only search arXiv.
--   **Empty Modules:** The `magpie`, `raven`, and `crow` character files are still empty. The `gradio/app.py` file is also empty, so there is no user-facing interface. The `formatting.py` file is still empty, which means the `corvus.py` file is still broken.
--   **Cluttered Source Directory:** The `src/cluas_mcp` directory still contains scripts that appear to be for testing or experimentation (`abstract_filtered.py`, `testing_arxiv.py`, `blah.py`).
--   **Lack of Tests for New Functionality:** There are no new tests for the `AgentMemory` class or for the updated `CorvusMCP` that uses it. The existing test files are either empty or haven't been updated.
-
-## c) Opinionated Breakdown and Future Development
-
-### What's Good
-
--   **Shared Memory is a Strong Concept:** The introduction of `AgentMemory` is a significant conceptual improvement. It moves the system from a simple tool to a collaborative multi-agent system where agents can build on each other's findings. This is a much more interesting and powerful architecture.
--   **Improved `CorvusMCP` Logic:** The ability to include recent memories in search results is a smart feature that makes the agent more context-aware.
-
-### Room for Improvement
-
-The project is still in a conceptual phase, and the execution is lagging behind the ideas. The critical feedback from the previous review still applies:
-
-1.  **Fix the Broken Code:** The `formatting.py` file needs to be implemented so that `corvus.py` can run. This is the most immediate and critical issue.
-2.  **Implement the API Clients:** The `PubMedClient` and `SemanticScholarClient` must be implemented for the core feature to work as designed.
-3.  **Write Tests for `AgentMemory`:** The new memory system is a critical component and should be thoroughly tested. Tests for adding, retrieving, and pruning items are essential.
-4.  **Clean the `src` Directory:** The experimental scripts should be moved out of the main source directory to improve code hygiene.
-5.  **Define Other Agent Roles:** The vision for the other agents (`Magpie`, `Raven`, `Crow`) should be translated into code. What do they do? How do they interact with the shared memory? For example:
-    -   `Magpie` could search for trending topics on social media or news sites and add them to memory with a "trending" tag.
-    -   `Raven` could be tasked with a specific, long-term monitoring goal, periodically updating a set of memory items.
-6.  **Build the UI:** A simple Gradio interface would provide a much-needed way to interact with the agents and see the shared memory in action.
-
-### Future Expectations
-
-The introduction of `AgentMemory` sets a clear direction for the project. The focus should now be on building out the ecosystem around this shared memory. I expect the next phase of development to involve:
-
--   Making the existing `CorvusMCP` character fully functional by implementing the remaining API clients.
--   Adding at least one more character with a distinct role that reads from or writes to the `AgentMemory`.
--   Adding a basic user interface to demonstrate the multi-agent interaction.
-
-The project has a stronger conceptual foundation now, but it needs a significant implementation effort to realize its potential. The priority should be to make the existing code runnable and tested before adding more features.

reviews/code_review_2025-11-15_15-30-00.md

@@ -1,62 +0,0 @@
-# Code Review: Corvid Council (Third Pass)
-
-**Date:** 2025-11-15
-
-## a) High-Level Summary
-
-This review assesses the "Cluas" repository against the detailed "Corvid Council - Development Guide." The document clarifies that the project is a multi-agent system ("Corvid Council") for a hackathon, with a clear vision, architecture, and development plan. The goal is a Gradio-based group chat of four AI crow experts (Corvus, Magpie, Raven, Crow) that also exposes its functionality as a set of external MCP tools.
-
-The current codebase represents a very early stage of this vision. It has established a foundational piece of the `Corvus` character and the `AgentMemory` system, which aligns with the "Week 1: Days 1-2" goals of the development plan. However, the implementation is still far from the complete architecture described in the guide. The existing code provides a skeleton for one character's tools but does not yet include the orchestration, multi-agent interaction, or the dual Gradio/MCP interface that are central to the project concept.
-
-## b) Detailed Description of Components vs. Project Plan
-
-### Current Implementation vs. "Week 1: Days 1-2" Goals
-
-The development guide sets a clear goal for the first two days: "One character working with tools in Gradio." Let's see how the current code stacks up.
-
--   **`Corvus` Character:** The `src/characters/corvus.py` file lays the groundwork for the "Scholar" archetype. Its `search_papers` function, with its fallback logic (PubMed -> Semantic Scholar -> arXiv), aligns perfectly with the described perfectionist, citation-focused personality. The integration with `AgentMemory` to log findings is a direct implementation of the cross-agent context recall mentioned in the guide.
--   **`AgentMemory`:** The `src/cluas_mcp/common/memory.py` is a solid first pass at the "agent-memory subsystem." It supports adding items with metadata (`mentioned_by`, `tags`) and retrieving them, which is the core requirement for enabling cross-agent context.
--   **API Clients:** The `src/cluas_mcp/common/api_clients.py` file contains the stubs for the clients Corvus needs. The `ArxivClient` is functional, which allows for some level of testing, while the others are placeholders. This is consistent with the iterative approach of getting one part working first.
--   **Missing Components:** Crucially, several key components from the development guide are entirely absent from the current codebase:
-    -   **`CouncilOrchestrator`**: There is no orchestrator to manage conversation flow or facilitate discussion between agents.
-    -   **`Character` Base Class**: The `CorvusMCP` class is standalone; it does not inherit from a common `Character` base class.
-    -   **Gradio Interface**: The `gradio/app.py` is empty. There is no UI to interact with Corvus.
-    -   **MCP Tool Exposure**: There is no code to expose the `ask_crow_council` or other external MCP tools.
-
-In summary, the current code has started implementing the `Corvus` character's internal logic but has not yet built the framework (orchestrator, base classes, UI) that will allow it to function as part of the "Corvid Council."
-
-## c) Opinionated Breakdown, Expectations, and Suggestions
-
-The development guide is excellent and provides a clear roadmap. The "roughness" of the current code is perfectly understandable in this context. The focus has clearly been on prototyping a single agent's core behavior, which is a sensible way to start.
-
-### Alignment with Vision
-
--   **Good:** The `CorvusMCP` and `AgentMemory` components are well-aligned with the project's vision. The idea of logging findings to a shared memory is a strong foundation for the multi-agent system.
--   **Gap:** The current file structure does not match the target structure outlined in the guide. For example, the tools are not yet separated into `src/mcp/tools/`, and there is no `orchestrator.py` or `character.py`.
-
-### Actionable Suggestions for Next Steps
-
-Given the detailed plan, my suggestions are to follow it closely. Here is a prioritized list of actions to bridge the gap between the current code and the "Week 1" goals:
-
-1.  **Establish the Target File Structure:** Before writing more code, refactor the existing files to match the structure in the development guide. This will make the project much easier to navigate and build upon.
-    -   Create `src/orchestrator.py`, `src/character.py`, and `src/mcp/tools/academic.py`.
-    -   Move the `CorvusMCP` logic into `src/characters/corvus.py` and make it inherit from a new `Character` base class in `src/character.py`.
-    -   Move the API client logic into the appropriate tool files (e.g., `academic.py`).
-    -   Move the experimental scripts (`blah.py`, etc.) to an `/experimental` directory as planned.
-
-2.  **Implement the `CouncilOrchestrator` Skeleton:** Create the `CouncilOrchestrator` class with placeholder methods as described in the guide. This will be the central hub of the application.
-
-3.  **Build a Basic Gradio UI:** Implement a minimal version of the Gradio interface. The goal for "Days 1-2" is to be able to ask a question and see Corvus respond. This will involve:
-    -   Creating the chat UI in `src/ui/interface.py`.
-    -   Wiring the UI to the `CouncilOrchestrator`.
-    -   Having the orchestrator call the `Corvus` character.
-
-4.  **Fix the Broken Import:** The `formatting.py` file is still empty, which blocks `CorvusMCP` from running. Implement the `snippet_abstract` and `format_authors` functions so the character's output can be displayed.
-
-5.  **Write Tests:** As you build these components, write basic unit tests as planned. A test for the `AgentMemory` and a simple integration test for the orchestrator calling Corvus would be a great start.
-
-### Future Expectations
-
-Following the development guide, I expect to see the project evolve rapidly. After establishing the core framework and getting Corvus to respond in the UI, the next logical steps will be to add the `Magpie` character and implement the staggered, interactive conversation flow described in the guide.
-
-The project is ambitious for a hackathon, but the detailed plan makes it achievable. The key will be to follow the phased approach, ensuring each component is functional before moving to the next. The current code is a good, albeit small, first step on that path.

reviews/code_review_2025-11-15_16-00-00.md

@@ -1,37 +0,0 @@
-# Code Review: Corvid Council (Fourth Pass)
-
-**Date:** 2025-11-15
-
-## a) High-Level Summary
-
-This review covers the latest changes to the "Corvid Council" repository, which are primarily administrative and structural. The updates focus on preparing the project for deployment on Hugging Face Spaces and aligning the repository with standard Python project practices.
-
-Key changes include the addition of a `README.md`, a `.gitignore` file, and a `requirements.txt` file. The `README.md` now effectively serves as the project's development guide, formalizing the vision and architecture. A placeholder Gradio application has also been added. While there are no major changes to the core agent logic, these updates represent a significant step towards professionalizing the repository and making it ready for collaborative development and deployment.
-
-## b) Detailed Description of Changes
-
--   **`README.md`:** The repository now has a comprehensive `README.md` file. It is a copy of the "Corvid Council - Development Guide," which clearly outlines the project's concept, architecture, character archetypes, and development plan. This is an excellent addition that makes the project's goals clear to any new contributor.
--   **`requirements.txt`:** A `requirements.txt` file has been added, listing the project's dependencies: `feedparser`, `requests`, `gradio`, and `huggingface_hub`. This is essential for ensuring a reproducible environment, especially for deployment on Hugging Face Spaces.
--   **`.gitignore`:** A standard Python `.gitignore` file has been included. This is a crucial piece of repository hygiene that prevents unnecessary files (like `__pycache__`, `.env`, virtual environment folders) from being committed to version control. It also correctly ignores the `cache.json` and `memory.json` files.
--   **`src/gradio/app.py`:** A basic Gradio application has been added. It currently contains boilerplate code for a `ChatInterface` that connects to an OpenAI model on the Hugging Face Hub. It is not yet integrated with the Corvid Council agents, but it provides the entry point for building the user-facing UI.
--   **No Core Logic Changes:** The core logic in `src/characters/corvus.py` and `src/cluas_mcp/common/memory.py` remains unchanged from the previous review.
-
-## c) Opinionated Breakdown and Suggestions
-
-These administrative changes were much-needed and have significantly improved the project's structure and readiness. While not feature development, this work is critical for a healthy project.
-
-### What's Good
-
--   **Excellent Documentation:** The `README.md` is now the project's single source of truth for its vision and plan. This is a best practice that was correctly prioritized.
--   **Ready for Deployment:** With `requirements.txt` and a basic `app.py`, the project is now technically deployable to Hugging Face Spaces, which is a key part of the hackathon plan.
--   **Improved Repository Hygiene:** The `.gitignore` file cleans up the repository and prevents common issues with sensitive data or unnecessary files in version control.
-
-### Suggestions for Next Steps
-
-The project is now well-positioned to continue with the "Week 1" development plan. The next steps should be to:
-
-1.  **Integrate the Core Logic with Gradio:** The immediate priority is to replace the boilerplate `respond` function in `src/gradio/app.py` with the logic from the `CouncilOrchestrator` (which still needs to be created). The goal is to have user input from the Gradio interface trigger the `Corvus` character's `search_papers` method.
-2.  **Continue the Refactoring:** As suggested in the previous review, continue refactoring the code to match the target file structure outlined in the `README.md`. This will involve creating the `CouncilOrchestrator` and the `Character` base class.
-3.  **Fix the `formatting.py` file:** This remains a blocker. The `snippet_abstract` and `format_authors` functions need to be implemented for the `Corvus` character to work.
-
-This round of changes was a successful and necessary step in maturing the project. The focus can now shift back to implementing the core features on this much stronger foundation.

reviews/code_review_2025-11-18_10-00-00.md

@@ -1,61 +0,0 @@
-# Code Review: Corvid Council - Initial Scaffolding
-
-**Date:** 2025-11-18
-
-## a) High-Level Summary
-
-The Corvid Council project is in its nascent stages, with the foundational scaffolding for a multi-agent research system. The core concept is strong: a group of specialized AI agents collaborating to research and discuss topics, retaining knowledge over time in a shared memory. The initial code sets up a key character, `Corvus`, responsible for academic searches, and a crucial `AgentMemory` component for persistence. However, the project is not yet functional due to missing implementations and architectural gaps. The immediate blockers are broken imports and placeholder API clients, which prevent the `Corvus` agent from executing its primary function.
-
-## b) Detailed Component Description
-
-### `src/characters/corvus.py`
-
-This file defines the `CorvusMCP` class, the first of the AI agents.
-
-*   **Functionality:** Its main purpose is to `search_papers` across multiple academic databases (PubMed, Semantic Scholar, arXiv) in a fallback sequence.
-*   **Integration:** It correctly initializes and uses the `AgentMemory` system by logging every paper it finds. This is a good early integration, ensuring that the agent's "discoveries" contribute to the collective knowledge base.
-*   **Issue:** The tool is currently broken. It imports `format_authors` and `snippet_abstract` from `src/cluas_mcp/common/formatting.py`, which is an empty file. This will cause a runtime `ImportError`.
-*   **Structure:** The class is straightforward, but it could benefit from being derived from a common `Character` base class in the future to standardize agent interfaces.
-
-### `src/cluas_mcp/common/memory.py`
-
-This is arguably the most complete and well-realized component so far.
-
-*   **Functionality:** The `AgentMemory` class provides a simple but effective JSON-backed database for the agents. It allows adding items, retrieving them based on recency or tags, and searching by title.
-*   **Persistence:** It handles file I/O for reading and writing to a `memory.json` file, ensuring that the council's knowledge persists between sessions.
-*   **Design:** The use of a dictionary with lowercase titles as keys is a simple but effective way to avoid duplicate entries and update reference timestamps. The methods for adding, retrieving, and searching are clear and well-defined.
-
-### `src/gradio/app.py`
-
-This file contains a boilerplate Gradio `ChatInterface`.
-
-*   **Functionality:** It sets up a basic chat window and connects it to the Hugging Face Inference API.
-*   **Issue:** It is completely disconnected from the Corvid Council agent system. The `respond` function is a generic chatbot implementation and does not interact with `Corvus` or the `AgentMemory`. This is expected at this early stage but is a key area for future development.
-
-## c) Opinionated Breakdown & Future Development
-
-### Current State
-
-The project has a good foundation but is more of an idea sketched in code than a working system. The separation of concerns is logical (characters, common utilities, UI), and the `AgentMemory` component is a solid start.
-
-The most significant issue is the lack of a central orchestrator. There is no "council," only a single, non-functional agent. The project's `README.md` and `gemini.md` files clearly outline a vision that the code has not yet begun to implement.
-
-### Suggestions for Future Development
-
-1.  **Fix the `Corvus` Agent:** The immediate priority is to implement the missing functions in `formatting.py` (`format_authors` and `snippet_abstract`). These could be simple implementations to start (e.g., `", ".join(authors)` and `abstract[:250] + "..."`).
-
-2.  **Implement API Clients:** The `gemini.md` file notes that the API clients are stubs. These need to be implemented to make `Corvus` functional. This involves writing the logic to make actual HTTP requests to PubMed, Semantic Scholar, and arXiv and parse their responses.
-
-3.  **Create a `CouncilOrchestrator`:** This is the most critical missing piece. A central class is needed to:
-    *   Manage the roster of agents (Corvus, Magpie, etc.).
-    *   Receive a user's query.
-    *   Mediate the conversation between agents (e.g., pass the query to Corvus, then pass Corvus's findings to another agent for critique).
-    *   Synthesize the final response for the user.
-
-4.  **Develop a `Character` Base Class:** To ensure all agents have a consistent interface, a `Character` abstract base class would be beneficial. It could define a common method like `process_query(query: str, context: List[str]) -> str` that each specialized agent would implement.
-
-5.  **Integrate Logic with Gradio UI:** Once the orchestrator is in place, the `respond` function in `gradio/app.py` should be rewritten to call the orchestrator instead of the generic Inference API. The chat history would represent the ongoing discussion of the council.
-
-6.  **Flesh out Other Characters:** After establishing the core architecture, the other characters (Magpie, Raven, Crow) can be created, each with their own specialized tools and "personalities."
-
-In summary, the project has a promising conceptual foundation. The next steps should focus on building the core architectural components that will allow the agents to interact and turning the placeholder code into functional modules.

reviews/code_review_2025-11-18_10-30-00.md

@@ -1,50 +0,0 @@
-# Code Review: Corvid Council - Path to Functionality
-
-**Date:** 2025-11-18
-
-## a) High-Level Summary
-
-The Corvid Council project has made a significant leap forward from a conceptual skeleton to a project with a clear and actionable roadmap. The addition of comprehensive development guides (`notes_etc/`) provides an excellent framework for the project's architecture, agent design, and phased implementation. Most importantly, a critical bug has been fixed by implementing the functions in `src/cluas_mcp/common/formatting.py`, which unblocks the `Corvus` agent. While the system is not yet fully operational (pending API client implementations and an orchestrator), it has moved from a state of being blocked to having a clear path toward achieving its "Week 1" goals.
-
-## b) Detailed Component Description
-
-### `notes_etc/development_guide_01.md`
-
-This new document is the most important addition to the repository. It serves as the project's bible.
-
-*   **Content:** It lays out the entire vision, from the high-level concept and architecture to the specific personalities and toolsets of the four agents (Corvus, Magpie, Raven, Crow). It also defines the external MCP tools the app will expose, the core software components (`CouncilOrchestrator`, `Character` base class), and a detailed week-by-week development plan.
-*   **Impact:** This guide provides invaluable clarity. It solidifies the project's goals and gives a strong indication of the intended structure, which was previously only hinted at in the `README.md`. It's an excellent piece of planning documentation.
-
-### `src/cluas_mcp/common/formatting.py`
-
-This file has been changed from an empty placeholder to a functional module.
-
-*   **Functionality:** It now contains `snippet_abstract` and `format_authors`. These functions provide basic but sensible text formatting, ensuring that data retrieved by agents can be presented cleanly.
-*   **Impact:** This is a critical fix. It resolves the `ImportError` that previously prevented the `CorvusMCP` tool from running. The `Corvus` agent, while still dependent on placeholder API clients, is now executable.
-
-### `src/characters/corvus.py`
-
-The `Corvus` agent is now in a much better state due to the fix in `formatting.py`.
-
-*   **State:** The code is unchanged, but its context has changed. It can now successfully call the formatting functions.
-*   **Next Blocker:** The primary blocker for `Corvus` is now the placeholder API clients (`PubMedClient`, `SemanticScholarClient`, etc.) defined in `src/cluas_mcp/common/api_clients.py`. Until these are implemented to make real API calls, `Corvus` cannot retrieve any data.
-
-## c) Opinionated Breakdown & Future Development
-
-### Current State
-
-The project is now on solid ground. The combination of a detailed plan and a critical bug fix has transformed it from a collection of disconnected files into a project with a clear trajectory. The immediate blockers are well-defined, and the long-term vision is compelling. The core challenge remains the same: building the central nervous system of the application—the `CouncilOrchestrator`—and connecting it to the agents and the UI.
-
-### Suggestions for Future Development
-
-The development plan laid out in `notes_etc/development_guide_01.md` is excellent and should be followed closely. My suggestions are aligned with it:
-
-1.  **Implement API Clients:** The immediate next step must be to implement the real API call logic in `src/cluas_mcp/common/api_clients.py`. Start with one (e.g., `PubMedClient` or `ArxivClient`) to get `Corvus` working end-to-end, even if it's just one data source.
-
-2.  **Build the `CouncilOrchestrator` Skeleton:** As per the guide, create `src/orchestrator.py`. It doesn't need to be fully featured at first. A simple version that can take a query, pass it to the `Corvus` agent, and get a result would be a huge step forward.
-
-3.  **Create the `Character` Base Class:** Create the `src/character.py` file with an abstract base class. Refactor `CorvusMCP` to inherit from this class. This will establish a pattern that will make adding the other three agents much easier.
-
-4.  **Basic UI Integration:** Wire the `CouncilOrchestrator` to the Gradio UI. The `respond` function in `src/gradio/app.py` should be updated to call `orchestrator.process_query(message)`. This will achieve the "Day 1-2" goal from the development guide: "Ask 'Are crows smart?', see Corvus search papers and respond with citation."
-
-The project is well-positioned for rapid progress. By focusing on the "Week 1" goals from the new development guide, the core functionality of a single-agent system can be achieved quickly, providing a solid foundation for the more complex multi-agent interactions to come.

reviews/code_review_2025-11-18_16-00-00.md

@@ -1,42 +0,0 @@
-# Code Review: Corvid Council - Implementation Begins
-
-**Date:** 2025-11-18
-
-## a) High-Level Summary
-
-The project has successfully transitioned from planning and bug-fixing to active feature development. The most critical blocker—the lack of functional API clients—is being directly addressed. The `ArxivClient` is now fully implemented, and the `PubMedClient` is halfway there. This marks a significant turning point for the project, as the `Corvus` agent now has access to real, structured data from at least one source. While the overall architecture (orchestrator, character base class) is still missing, this concrete progress on the data layer is a crucial and encouraging step towards a functional application.
-
-## b) Detailed Component Description
-
-### `src/cluas_mcp/common/api_clients.py`
-
-This file is now the center of the project's momentum. It has evolved from a collection of placeholders and comments into a partially functional module.
-
-*   **`ArxivClient`:** This class is now fully implemented and serves as a great template for the other clients. It correctly formulates a URL for the arXiv API, uses `requests` to get the data, and then uses the `feedparser` library to parse the resulting Atom XML feed. It demonstrates a complete, end-to-end data retrieval process: query -> fetch -> parse -> structure.
-
-*   **`PubMedClient`:** This class has seen significant progress.
-    *   The `pubmed_search` method implements the first half of the required two-step process. It intelligently constructs a search term from keywords and uses the `esearch.fcgi` endpoint to retrieve a list of article IDs.
-    *   The `parse_id_list` helper method correctly uses `xml.etree.ElementTree` to parse the XML response and extract the IDs.
-    *   **Missing Piece:** The client still needs an `efetch` method to take these IDs and retrieve the full article details.
-
-*   **`SemanticScholarClient`:** This remains a placeholder and is the last remaining data source to be implemented for the `Corvus` agent.
-
-## c) Opinionated Breakdown & Future Development
-
-### Current State
-
-This is the most positive review yet. The "brutal" assessment from our last exchange has been met with direct action. The project is no longer just a collection of plans; it has a working data pipeline for one of its key components. This is a classic example of "bottom-up" implementation: building the foundational data layers first before wiring them into the higher-level application logic.
-
-The `Corvus` agent is now theoretically capable of searching arXiv, which is a major milestone. The immediate next steps are very clear and build directly on the work that has just been completed.
-
-### Suggestions for Future Development
-
-1.  **Complete the `PubMedClient`:** The highest priority is to finish what was started. Create a new method, perhaps `fetch_paper_details(ids: List[str])`, that takes the output from `pubmed_search`, calls the `efetch.fcgi` endpoint, and parses the resulting XML to extract the title, abstract, authors, and DOI for each paper. This will bring the `PubMedClient` to parity with the `ArxivClient`.
-
-2.  **Refactor `corvus.py`:** Modify the `CorvusMCP.search_papers` method to use the newly implemented clients. The fallback logic (`try PubMed -> fallback to arXiv`) can now be implemented with real function calls. This will make the `Corvus` agent fully data-functional.
-
-3.  **Implement `SemanticScholarClient`:** Tackle the final placeholder client to complete the data-gathering capabilities of `Corvus`.
-
-4.  **Shift Focus to the Orchestrator:** Once `Corvus` is fully functional, the focus must shift to the application layer. It's time to create the `CouncilOrchestrator` and the `Character` base class as outlined in the development guides. The goal should be to create the simplest possible loop: a query comes in, the orchestrator passes it to `Corvus`, `Corvus` uses its new tools to get real data, and the result is printed or returned.
-
-The project has gained significant momentum. The key is to maintain it by immediately building on this success to complete the data layer and then moving up the stack to the application logic.

reviews/code_review_2025-11-18_17-00-00.md

@@ -1,52 +0,0 @@
-# Code Review: Corvid Council - A Move Towards Robustness
-
-**Date:** 2025-11-18
-
-## a) High-Level Summary
-
-The project has undergone a significant and positive architectural refactoring. The creation of a dedicated `academic` submodule for the `PubMedClient` and the introduction of a shared, resilient HTTP utility (`common/http.py`) show a clear move towards building a more organized, maintainable, and robust application. This addresses not just functionality but also code quality and long-term health. However, this refactoring is incomplete, having introduced significant code duplication that must be resolved.
-
-## b) Detailed Component Description
-
-### `src/cluas_mcp/common/http.py`
-
-This new file is a major architectural improvement.
-
-*   **Functionality:** It provides a `fetch_with_retry` function that wraps `requests.get` with a sophisticated retry mechanism using the `tenacity` library. It correctly implements exponential backoff and is configured to retry on transient HTTP errors (5xx status codes) and rate-limiting responses (HTTP 429), which is crucial for consuming public APIs.
-*   **Impact:** This utility makes the entire system more resilient. By centralizing this logic, any API client that uses it automatically becomes more robust without duplicating code.
-
-### `src/cluas_mcp/academic/pubmed_client.py`
-
-This new file represents a structural improvement, aligning the codebase with the planned architecture.
-
-*   **Functionality:** It contains the `PubMedClient` and its `pubmed_search` method, which is responsible for querying the PubMed `esearch` endpoint.
-*   **Improvement:** It has been updated to use the new `fetch_with_retry` function, immediately benefiting from the added resilience.
-
-### `src/cluas_mcp/common/api_clients.py`
-
-This file is now a source of technical debt.
-
-*   **State:** It still contains the old `PubMedClient` implementation, which is now obsolete. The `ArxivClient` and the placeholder `SemanticScholarClient` also remain here.
-*   **Problem:** The presence of the old `PubMedClient` creates direct code duplication. It's unclear to a new developer which client is the correct one to use, and imports could easily point to the wrong one.
-
-## c) Opinionated Breakdown & Future Development
-
-### Current State
-
-The project is in a state of healthy, if incomplete, transition. The decision to refactor the API clients into separate modules and create a shared HTTP utility is excellent. It shows that the developer is thinking not just about "what" the code does, but "how" it should be structured for maintainability.
-
-However, the job is only half-done. The lingering code duplication in `api_clients.py` is a significant problem that negates some of the benefits of the refactoring. It's a textbook example of technical debt that should be paid down immediately before it causes problems.
-
-### Suggestions for Future Development
-
-1.  **Complete the Refactoring (Immediate Priority):**
-    *   **Delete the old `PubMedClient`** from `src/cluas_mcp/common/api_clients.py`.
-    *   **Move the `ArxivClient`** from `api_clients.py` to a new file: `src/cluas_mcp/academic/arxiv_client.py`. Update it to use the `fetch_with_retry` function as well.
-    *   **Move the `SemanticScholarClient`** placeholder to `src/cluas_mcp/academic/semantic_scholar_client.py`.
-    *   **Delete the `api_clients.py` file** entirely, as its purpose has been superseded by the new `academic` submodule.
-
-2.  **Complete the `PubMedClient` Functionality:** Once the refactoring is clean, return to implementing the `efetch` logic in `src/cluas_mcp/academic/pubmed_client.py`. Create the method that takes the list of IDs and fetches the full paper details.
-
-3.  **Update `corvus.py` Imports:** After the refactoring, the `import` statements at the top of `src/characters/corvus.py` will be broken. They will need to be updated to point to the new locations of the client classes (e.g., `from ..cluas_mcp.academic.pubmed_client import PubMedClient`).
-
-The project is making great strides in code quality. The immediate task is to complete the cleanup from this recent refactoring to solidify the architectural gains before moving on to the next feature.

reviews/code_review_2025-11-18_18-00-00.md

@@ -1,55 +0,0 @@
-# Code Review: Corvid Council - A Milestone Achieved
-
-**Date:** 2025-11-18
-
-## a) High-Level Summary
-
-The project has undergone a transformative set of changes, evolving from a scattered collection of scripts into a well-structured, tested, and robust data access layer. The previous architectural issues have been fully addressed through a major refactoring. The API clients are now modular, the `PubMedClient` is feature-complete, and the entire system is supported by a resilient HTTP utility. Most importantly, the addition of a test suite marks a pivotal moment in the project's lifecycle, providing a foundation for reliable and scalable development. The data-gathering toolkit for the `Corvus` agent is now effectively complete.
-
-## b) Detailed Component Description
-
-### `src/cluas_mcp/academic/` (Submodule)
-
-This new submodule is the heart of the recent changes and represents the project's data access layer.
-
-*   **`pubmed.py` & `arxiv.py`:** These files contain the clean, refactored, and feature-complete clients for their respective services. They are focused, easy to understand, and leverage the shared `http.py` utility. The `PubMedClient` now correctly implements the full `esearch` -> `efetch` workflow.
-*   **`academic_search.py`:** This file introduces the "Facade" design pattern to the project. The `academic_search` function provides a single, simple interface for querying all underlying academic sources. This decouples the agent logic from the specifics of each API client, which is an excellent architectural choice that will make the `Corvus` agent much simpler to implement.
-
-### `src/cluas_mcp/domain/` (Submodule)
-
-*   **`keywords.py`:** The creation of this submodule to hold domain-specific data (like lists of corvid-related keywords) is a sign of a maturing codebase. It properly separates data from logic, making the system easier to configure and maintain.
-
-### `tests/` (Directory)
-
-The addition of `test_arxiv.py` and `test_pubmed.py` is the most significant improvement in this round of changes.
-
-*   **Functionality:** These files provide simple but effective integration tests for the API clients. They make real calls to the APIs and perform basic validation on the results.
-*   **Impact:** This is a critical best practice. These tests ensure that the data sources—the very foundation of the application—are working as expected. They prevent regressions and provide confidence for future modifications.
-
-## c) Opinionated Breakdown & Future Development
-
-### Current State
-
-The project is now in an excellent state. The "brutal" feedback from earlier has been met with a flurry of high-quality work that has not only fixed the identified problems but has exceeded expectations by introducing tests and better architectural patterns. The technical debt from the initial exploratory phase has been paid down, and the foundation is now solid.
-
-The `Corvus` agent has a complete, robust, and tested toolkit at its disposal. The project has successfully completed the "build the data layer" phase and is now perfectly positioned to move up the stack to the application logic.
-
-### Suggestions for Future Development
-
-The path forward is clearer than ever. The focus should now be entirely on using the new data layer to bring the agents to life.
-
-1.  **Finalize Cleanup:** Delete the obsolete `src/cluas_mcp/common/api_clients.py` file to complete the refactoring.
-
-2.  **Integrate the Data Layer into `Corvus`:**
-    *   Modify `src/characters/corvus.py`.
-    *   Remove the direct imports for the old clients.
-    *   Import and use the new `academic_search` facade from `src/cluas_mcp/academic/academic_search.py`.
-    *   The logic inside `CorvusMCP.search_papers` should now be incredibly simple: it just needs to call `academic_search` and process the unified results.
-
-3.  **Build the `CouncilOrchestrator`:** With `Corvus` now fully functional, it is time to build the central nervous system.
-    *   Create `src/orchestrator.py` as planned in the development guide.
-    *   Implement a basic `process_query` method that initializes `Corvus` and calls its `search_papers` method.
-
-4.  **Connect to the UI:** Wire the new `CouncilOrchestrator` to the Gradio app. The `respond` function in `src/gradio/app.py` should do nothing more than pass the user's message to the orchestrator and display the result.
-
-Achieving these next steps will fulfill the project's "Week 1, Day 1-2" goal and create a true end-to-end, functional application for the first time. The project has tremendous momentum; maintaining it through these next steps will bring the vision to life.

reviews/code_review_2025-11-18_19-00-00.md

@@ -1,54 +0,0 @@
-# Code Review: Corvid Council - Data Layer Complete
-
-**Date:** 2025-11-18
-
-## a) High-Level Summary
-
-This update marks the completion of the project's data access layer. The final placeholder, the `SemanticScholarClient`, has been expertly implemented and tested, bringing the `academic` submodule to 100% functionality. The `Corvus` agent's entire toolkit for gathering academic information is now in place, is architecturally sound, and is validated by a suite of tests. This is a major milestone that concludes the foundational phase of the project and clears the way for development to move up the stack to the agent and application logic.
-
-## b) Detailed Component Description
-
-### `src/cluas_mcp/academic/semantic_scholar.py`
-
-The final piece of the puzzle. This module completes the data access toolkit.
-
-*   **Functionality:** The `SemanticScholarClient` correctly queries the official API, requests a specific set of fields to keep the payload light, and normalizes the JSON response into the project's standard dictionary format. It intelligently determines if a paper is a preprint or peer-reviewed based on the presence of a DOI.
-*   **Quality:** The implementation is clean, robust (leveraging the shared `fetch_with_retry` utility), and consistent with the other clients.
-
-### `tests/test_semantic_scholar.py`
-
-This new test file demonstrates a continued commitment to quality.
-
-*   **Functionality:** It provides a solid integration test for the new client, asserting that the response format is correct and that key fields are present. This ensures the client is not only working now but will be protected against future regressions.
-
-### `src/cluas_mcp/academic/academic_search_entry.py`
-
-The facade for the `academic` module is now fully operational.
-
-*   **Functionality:** With all underlying clients implemented, this entry point can now successfully query PubMed, ArXiv, and Semantic Scholar in parallel, providing a rich, aggregated set of results from a single function call.
-
-## c) Opinionated Breakdown & Future Development
-
-### Current State
-
-The project's data access layer is now a model of good software engineering practices. It is:
-*   **Modular:** Each client is in its own file.
-*   **Robust:** It uses a shared, resilient HTTP client with retries.
-*   **Tested:** Each client has a corresponding integration test.
-*   **Well-abstracted:** A single facade provides a clean entry point for the rest of the application.
-
-This part of the project can be considered "done" for the initial MVP. It is a production-ready component. The contrast between the current state and the state of the project just a few hours ago is dramatic and speaks to a period of highly effective development.
-
-### Suggestions for Future Development
-
-The to-do list has become very short and focused. The project is at a clear inflection point.
-
-1.  **DELETE `src/cluas_mcp/common/api_clients.py` (Immediate):** This is the last piece of technical debt from the refactoring. Deleting this obsolete file is a zero-effort task that will officially close the chapter on the initial, messy structure.
-
-2.  **Build the Application Layer (The Only Remaining Task):** The entire focus must now shift to using the newly completed data layer. The following steps, outlined in previous reviews and the development guide, are now unlocked and should be pursued in order:
-    *   **Integrate into `Corvus`:** Refactor `src/characters/corvus.py` to use the `academic_search_entry.py` facade.
-    *   **Build `CouncilOrchestrator`:** Create the orchestrator to manage the agent(s).
-    *   **Build `Character` Base Class:** Create a base class to standardize the agent interface.
-    *   **Connect to UI:** Wire the orchestrator to the Gradio app.
-
-The project has successfully built a powerful and reliable engine. Now it's time to build the car around it.

reviews/code_review_2025-11-18_20-00-00.md

@@ -1,47 +0,0 @@
-# Code Review: Corvid Council - Data Layer Hardened and Finalized
-
-**Date:** 2025-11-18
-
-## a) High-Level Summary
-
-This latest update represents the final hardening and cleanup of the project's data access layer. The test suite has been refactored into a more mature, layered structure, the central search facade has been made more resilient, and the last piece of technical debt from the initial refactoring has been eliminated. The `academic` module is now a production-grade component, marking the definitive end of the foundational phase of development. The project is in an ideal state to pivot entirely to building the agent and application logic.
-
-## b) Detailed Component Description
-
-### Test Suite (`tests/`)
-
-The testing infrastructure has seen a significant and professional upgrade.
-
-*   **Layered Structure:** The tests are now organized into `tests/clients/` and `tests/integration/`. This is an excellent practice that separates focused, client-level tests from higher-level tests that verify the interaction between multiple components.
-*   **Integration Test:** The new `test_academic_search_entrypoint.py` is a perfect example of a good integration test. It uses mocking to isolate the search facade and verify two key behaviors: that it correctly calls all underlying clients, and that it gracefully handles an exception from one client without crashing.
-*   **Configuration:** The addition of `tests/conftest.py` to manage the test environment's system path is a standard and robust solution for making the test suite reliable and easy to run.
-
-### `src/cluas_mcp/academic/academic_search_entrypoint.py`
-
-The search facade has been made more resilient.
-
-*   **Error Handling:** The function now wraps each client call in a `try...except` block. This ensures that a failure from a single source (e.g., the PubMed API is down) does not prevent the function from returning successful results from the other sources. This is a crucial feature for a system that depends on multiple external services.
-
-### Code Cleanup
-
-*   **`api_clients.py` Deleted:** The obsolete `src/cluas_mcp/common/api_clients.py` file has been deleted. This small change has a large impact, as it removes ambiguity and finalizes the major refactoring effort, leaving the codebase clean and easy to navigate.
-
-## c) Opinionated Breakdown & Future Development
-
-### Current State
-
-The project is in its best state yet. The data access layer is not just "done," it is well-crafted, resilient, and thoroughly tested. The investment in the testing infrastructure will pay dividends throughout the rest of the development cycle, allowing for faster and more confident changes. The developer has successfully navigated the transition from rapid prototyping to building stable, high-quality components.
-
-There are no remaining issues or concerns with the foundational code. The table is perfectly set for the next course.
-
-### Suggestions for Future Development
-
-The focus must now shift entirely to the application layer. The next steps are clear and build directly upon the solid foundation that has been established.
-
-1.  **Integrate the Facade into `Corvus`:** This is the immediate next step. Refactor `src/characters/corvus.py` to import and use the `academic_search` function from the entrypoint. The agent's internal logic will become dramatically simpler, as it no longer needs to know about the individual clients.
-
-2.  **Build the `CouncilOrchestrator`:** With a fully functional `Corvus` agent, the orchestrator can now be built to manage it. Create `src/orchestrator.py` and implement the logic to receive a query and dispatch it to the `Corvus` agent.
-
-3.  **Connect to the UI:** Wire the orchestrator to the Gradio app in `src/gradio/app.py`. This will create the first end-to-end functional slice of the application, where a user can type a query into the UI and see real, structured data from three academic sources returned.
-
-The project has excellent momentum and a very clear path forward. Executing on these next steps will finally bring the core vision of the application to life.

src/characters/corvus.py

@@ -1,100 +0,0 @@
-import time
-from typing import List, Optional, Dict
-from ..cluas_mcp.common.memory import AgentMemory
-from ..cluas_mcp.academic.academic_search_entrypoint import academic_search
-from ..cluas_mcp.common.formatting import format_authors, snippet_abstract
-
-# init shared council memory
-memory = AgentMemory(memory_file="src/data/memory.json")
-
-class CorvusMCP:
-    """
-    Corvus MCP tool: searches academic literature and returns structured results.
-    Automatically logs items into shared agent memory for council context.
-    """
-
-    def search_papers(
-        self, 
-        query: str,
-        max_results: int = 5, # Note: max_results is not currently passed to the facade
-        memory_days: int = 30
-    ) -> List[Dict]:
-        """
-        Search academic papers for a query string.
-        Returns a list of dicts:
-        {
-            "title": str,
-            "abstract": str,
-            "authors": str,
-            "published": str,
-            "doi": Optional[str],
-            "link": str
-        }
-        """
-
-        # --- 1. Call the academic search facade ---
-        all_results = academic_search(query)
-        
-        # --- 2. Combine results from all sources ---
-        results = []
-        for source in all_results.values():
-            results.extend(source)
-
-        # --- 3. Clean, format, and log results to memory ---
-        cleaned = []
-        for r in results:
-            title = r.get("title", "Untitled")
-            abstract = snippet_abstract(r.get("abstract", ""))
-            # The new clients provide 'author_str' directly
-            authors = r.get("author_str") or format_authors(r.get("authors", []))
-            doi = r.get("doi")
-            link = r.get("link", r.get("arxiv_link", r.get("pubmed_link", "")))
-
-            # log into memory
-            memory.add_item(
-                title=title,
-                doi=doi,
-                snippet=abstract,
-                mentioned_by="Corvus",
-                tags=["academic_search", r.get("source", "unknown")]
-            )
-
-            cleaned.append({
-                "title": title,
-                "abstract": abstract,
-                "authors": authors,
-                "published": r.get("published", r.get("year", "")),
-                "doi": doi,
-                "link": link
-            })
-
-        # --- 4. Include recent memory items optionally ---
-        recent_memory = memory.get_recent(days=memory_days)
-        for item in recent_memory:
-            if item["title"] not in [c["title"] for c in cleaned]:
-                cleaned.append({
-                    "title": item["title"],
-                    "abstract": item.get("snippet", ""),
-                    "authors": "",  # optional: keep minimal
-                    "published": "",
-                    "doi": item.get("doi"),
-                    "link": item.get("doi") or "",
-                })
-
-        return cleaned
-
-
-
-
-
-# poss usage example:
-    
-# from src.characters.corvus import CorvusMCP
-
-# corvus = CorvusMCP()
-# papers = corvus.search_papers("corvid cognition", max_results=3)
-
-# for p in papers:
-#     print(f"{p['title']} ({p.get('doi')})")
-#     print(f"Snippet: {p['abstract']}\n")
-    

src/cluas_mcp/server.py

@@ -1,5 +1,21 @@
+import FastMCP
 import logging
 
 def main():
     logging.basicConfig(level=logging.INFO)
-    pass
+    pass
+
+
+@mcp.tool()
+async def search_academic_papers(query: str) -> str:
+    """Search academic papers across PubMed, Semantic Scholar, and ArXiv.
+    
+    Args:
+        query: Search term for academic papers
+        
+    Returns:
+        JSON string with results from all three sources
+    """
+    # Call the existing academic_search function
+    # Format results as clean JSON string
+    # Include paper titles, authors, abstracts, DOIs where available

src/orchestrator.py

@@ -1,45 +0,0 @@
-from typing import Dict, List
-from src.characters.corvus import CorvusMCP
-
-class CouncilOrchestrator:
-    """
-    Manages the council of agents and orchestrates the research process.
-    """
-
-    def __init__(self):
-        """
-        Initializes the orchestrator and the council members.
-        For now, only Corvus is instantiated.
-        """
-        self.corvus = CorvusMCP()
-        # In the future, other agents like Magpie, Raven, etc., will be initialized here.
-
-    def process_query(self, query: str) -> List[Dict]:
-        """
-        Processes a user query by dispatching it to the relevant agents.
-
-        For this initial implementation, it only calls Corvus.
-        
-        Args:
-            query: The user's research query.
-
-        Returns:
-            A list of dictionaries containing the search results.
-        """
-        # In the future, this method will involve more complex logic,
-        # such as selecting which agent to call first, facilitating debate,
-        # and synthesizing results.
-        
-        # For now, we just call Corvus directly.
-        results = self.corvus.search_papers(query)
-        
-        return results
-
-# Example usage (for testing):
-# if __name__ == "__main__":
-#     orchestrator = CouncilOrchestrator()
-#     search_results = orchestrator.process_query("corvid cognition")
-#     for paper in search_results:
-#         print(f"Title: {paper['title']}")
-#         print(f"Authors: {paper['authors']}")
-#         print("-" * 20)

uv.lock

@@ -122,6 +122,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f8/aa/5082412d1ee302e9e7d80b6949bc4d2a8fa1149aaab610c5fc24709605d6/authlib-1.6.5-py2.py3-none-any.whl", hash = "sha256:3e0e0507807f842b02175507bdee8957a1d5707fd4afb17c32fb43fee90b6e3a", size = 243608, upload-time = "2025-10-02T13:36:07.637Z" },
 ]
 
+[[package]]
+name = "beartype"
+version = "0.22.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/88/e2/105ceb1704cb80fe4ab3872529ab7b6f365cf7c74f725e6132d0efcf1560/beartype-0.22.6.tar.gz", hash = "sha256:97fbda69c20b48c5780ac2ca60ce3c1bb9af29b3a1a0216898ffabdd523e48f4", size = 1588975, upload-time = "2025-11-20T04:47:14.736Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/98/c9/ceecc71fe2c9495a1d8e08d44f5f31f5bca1350d5b2e27a4b6265424f59e/beartype-0.22.6-py3-none-any.whl", hash = "sha256:0584bc46a2ea2a871509679278cda992eadde676c01356ab0ac77421f3c9a093", size = 1324807, upload-time = "2025-11-20T04:47:11.837Z" },
+]
+
 [[package]]
 name = "brotli"
 version = "1.2.0"
@@ -150,6 +159,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f5/10/56978295c14794b2c12007b07f3e41ba26acda9257457d7085b0bb3bb90c/brotli-1.2.0-cp314-cp314-win_amd64.whl", hash = "sha256:e7c0af964e0b4e3412a0ebf341ea26ec767fa0b4cf81abb5e897c9338b5ad6a3", size = 375639, upload-time = "2025-11-05T18:38:55.67Z" },
 ]
 
+[[package]]
+name = "cachetools"
+version = "6.2.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fb/44/ca1675be2a83aeee1886ab745b28cda92093066590233cc501890eb8417a/cachetools-6.2.2.tar.gz", hash = "sha256:8e6d266b25e539df852251cfd6f990b4bc3a141db73b939058d809ebd2590fc6", size = 31571, upload-time = "2025-11-13T17:42:51.465Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e6/46/eb6eca305c77a4489affe1c5d8f4cae82f285d9addd8de4ec084a7184221/cachetools-6.2.2-py3-none-any.whl", hash = "sha256:6c09c98183bf58560c97b2abfcedcbaf6a896a490f534b031b661d3723b45ace", size = 11503, upload-time = "2025-11-13T17:42:50.232Z" },
+]
+
 [[package]]
 name = "certifi"
 version = "2025.11.12"
@@ -262,6 +280,7 @@ name = "cluas"
 version = "0.1.0"
 source = { virtual = "." }
 dependencies = [
+    { name = "fastmcp" },
     { name = "feedparser" },
     { name = "gradio", extra = ["mcp", "oauth"] },
     { name = "mcp" },
@@ -272,6 +291,7 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
+    { name = "fastmcp", specifier = ">=2.13.1" },
     { name = "feedparser", specifier = ">=6.0.12" },
     { name = "gradio", extras = ["mcp", "oauth"], specifier = "==6.0.0.dev4" },
     { name = "mcp", specifier = ">=1.20.0" },
@@ -345,6 +365,69 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e8/cb/2da4cc83f5edb9c3257d09e1e7ab7b23f049c7962cae8d842bbef0a9cec9/cryptography-46.0.3-cp38-abi3-win_arm64.whl", hash = "sha256:d89c3468de4cdc4f08a57e214384d0471911a3830fcdaf7a8cc587e42a866372", size = 2918740, upload-time = "2025-10-15T23:18:12.277Z" },
 ]
 
+[[package]]
+name = "cyclopts"
+version = "5.0.0a1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "docstring-parser" },
+    { name = "rich" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4c/ca/65e020717410cff8916bae89d5b1704ee190d2a345f47ba5e5f903b41d59/cyclopts-5.0.0a1.tar.gz", hash = "sha256:ae24ce6c0c8dbaba3fdfccdb54d2a9d6e2a6270c47ffe101af1de89ff617851a", size = 148291, upload-time = "2025-11-02T19:32:43.176Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d3/eda07755dffa4ea637a673181934bcd54255def1c71dd1cc0f8ec49f888e/cyclopts-5.0.0a1-py3-none-any.whl", hash = "sha256:731e0c4412d47993202abffd0bfe222353b12347dfef7e874ac769c74c8a162a", size = 183923, upload-time = "2025-11-02T19:32:41.532Z" },
+]
+
+[[package]]
+name = "diskcache"
+version = "5.6.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/3f/21/1c1ffc1a039ddcc459db43cc108658f32c57d271d7289a2794e401d0fdb6/diskcache-5.6.3.tar.gz", hash = "sha256:2c3a3fa2743d8535d832ec61c2054a1641f41775aa7c556758a109941e33e4fc", size = 67916, upload-time = "2023-08-31T06:12:00.316Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3f/27/4570e78fc0bf5ea0ca45eb1de3818a23787af9b390c0b0a0033a1b8236f9/diskcache-5.6.3-py3-none-any.whl", hash = "sha256:5e31b2d5fbad117cc363ebaf6b689474db18a1f6438bc82358b024abd4c2ca19", size = 45550, upload-time = "2023-08-31T06:11:58.822Z" },
+]
+
+[[package]]
+name = "dnspython"
+version = "2.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/8c/8b/57666417c0f90f08bcafa776861060426765fdb422eb10212086fb811d26/dnspython-2.8.0.tar.gz", hash = "sha256:181d3c6996452cb1189c4046c61599b84a5a86e099562ffde77d26984ff26d0f", size = 368251, upload-time = "2025-09-07T18:58:00.022Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ba/5a/18ad964b0086c6e62e2e7500f7edc89e3faa45033c71c1893d34eed2b2de/dnspython-2.8.0-py3-none-any.whl", hash = "sha256:01d9bbc4a2d76bf0db7c1f729812ded6d912bd318d3b1cf81d30c0f845dbf3af", size = 331094, upload-time = "2025-09-07T18:57:58.071Z" },
+]
+
+[[package]]
+name = "docstring-parser"
+version = "0.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b2/9d/c3b43da9515bd270df0f80548d9944e389870713cc1fe2b8fb35fe2bcefd/docstring_parser-0.17.0.tar.gz", hash = "sha256:583de4a309722b3315439bb31d64ba3eebada841f2e2cee23b99df001434c912", size = 27442, upload-time = "2025-07-21T07:35:01.868Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/55/e2/2537ebcff11c1ee1ff17d8d0b6f4db75873e3b0fb32c2d4a2ee31ecb310a/docstring_parser-0.17.0-py3-none-any.whl", hash = "sha256:cf2569abd23dce8099b300f9b4fa8191e9582dda731fd533daf54c4551658708", size = 36896, upload-time = "2025-07-21T07:35:00.684Z" },
+]
+
+[[package]]
+name = "email-validator"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "dnspython" },
+    { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f5/22/900cb125c76b7aaa450ce02fd727f452243f2e91a61af068b40adba60ea9/email_validator-2.3.0.tar.gz", hash = "sha256:9fc05c37f2f6cf439ff414f8fc46d917929974a82244c20eb10231ba60c54426", size = 51238, upload-time = "2025-08-26T13:09:06.831Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/de/15/545e2b6cf2e3be84bc1ed85613edd75b8aea69807a71c26f4ca6a9258e82/email_validator-2.3.0-py3-none-any.whl", hash = "sha256:80f13f623413e6b197ae73bb10bf4eb0908faf509ad8362c5edeb0be7fd450b4", size = 35604, upload-time = "2025-08-26T13:09:05.858Z" },
+]
+
+[[package]]
+name = "exceptiongroup"
+version = "1.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0b/9f/a65090624ecf468cdca03533906e7c69ed7588582240cfe7cc9e770b50eb/exceptiongroup-1.3.0.tar.gz", hash = "sha256:b241f5885f560bc56a59ee63ca4c6a8bfa46ae4ad651af316d4e81817bb9fd88", size = 29749, upload-time = "2025-05-10T17:42:51.123Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/36/f4/c6e662dade71f56cd2f3735141b265c3c79293c109549c1e6933b0651ffc/exceptiongroup-1.3.0-py3-none-any.whl", hash = "sha256:4d111e6e0c13d0644cad6ddaa7ed0261a0b36971f6d23e7ec9b4b9097da78a10", size = 16674, upload-time = "2025-05-10T17:42:49.33Z" },
+]
+
 [[package]]
 name = "fastapi"
 version = "0.121.2"
@@ -360,6 +443,32 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/eb/23/dfb161e91db7c92727db505dc72a384ee79681fe0603f706f9f9f52c2901/fastapi-0.121.2-py3-none-any.whl", hash = "sha256:f2d80b49a86a846b70cc3a03eb5ea6ad2939298bf6a7fe377aa9cd3dd079d358", size = 109201, upload-time = "2025-11-13T17:05:52.718Z" },
 ]
 
+[[package]]
+name = "fastmcp"
+version = "2.13.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "authlib" },
+    { name = "cyclopts" },
+    { name = "exceptiongroup" },
+    { name = "httpx" },
+    { name = "jsonschema-path" },
+    { name = "mcp" },
+    { name = "openapi-pydantic" },
+    { name = "platformdirs" },
+    { name = "py-key-value-aio", extra = ["disk", "keyring", "memory"] },
+    { name = "pydantic", extra = ["email"] },
+    { name = "pyperclip" },
+    { name = "python-dotenv" },
+    { name = "rich" },
+    { name = "uvicorn" },
+    { name = "websockets" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d4/a3/c9eb28b5f0b979b0dd8aa9ba56e69298cdb2d72c15592165d042ccb20194/fastmcp-2.13.1.tar.gz", hash = "sha256:b9c664c51f1ff47c698225e7304267ae29a51913f681bd49e442b8682f9a5f90", size = 8170226, upload-time = "2025-11-15T19:02:17.693Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/4b/7e36db0a90044be181319ff025be7cc57089ddb6ba8f3712dea543b9cf97/fastmcp-2.13.1-py3-none-any.whl", hash = "sha256:7a78b19785c4ec04a758d920c312769a497e3f6ab4c80feed504df1ed7de9f3c", size = 376750, upload-time = "2025-11-15T19:02:15.748Z" },
+]
+
 [[package]]
 name = "feedparser"
 version = "6.0.12"
@@ -596,6 +705,48 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/04/96/92447566d16df59b2a776c0fb82dbc4d9e07cd95062562af01e408583fc4/itsdangerous-2.2.0-py3-none-any.whl", hash = "sha256:c6242fc49e35958c8b15141343aa660db5fc54d4f13a1db01a3f5891b98700ef", size = 16234, upload-time = "2024-04-16T21:28:14.499Z" },
 ]
 
+[[package]]
+name = "jaraco-classes"
+version = "3.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "more-itertools" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/c0/ed4a27bc5571b99e3cff68f8a9fa5b56ff7df1c2251cc715a652ddd26402/jaraco.classes-3.4.0.tar.gz", hash = "sha256:47a024b51d0239c0dd8c8540c6c7f484be3b8fcf0b2d85c13825780d3b3f3acd", size = 11780, upload-time = "2024-03-31T07:27:36.643Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7f/66/b15ce62552d84bbfcec9a4873ab79d993a1dd4edb922cbfccae192bd5b5f/jaraco.classes-3.4.0-py3-none-any.whl", hash = "sha256:f662826b6bed8cace05e7ff873ce0f9283b5c924470fe664fff1c2f00f581790", size = 6777, upload-time = "2024-03-31T07:27:34.792Z" },
+]
+
+[[package]]
+name = "jaraco-context"
+version = "6.0.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/df/ad/f3777b81bf0b6e7bc7514a1656d3e637b2e8e15fab2ce3235730b3e7a4e6/jaraco_context-6.0.1.tar.gz", hash = "sha256:9bae4ea555cf0b14938dc0aee7c9f32ed303aa20a3b73e7dc80111628792d1b3", size = 13912, upload-time = "2024-08-20T03:39:27.358Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ff/db/0c52c4cf5e4bd9f5d7135ec7669a3a767af21b3a308e1ed3674881e52b62/jaraco.context-6.0.1-py3-none-any.whl", hash = "sha256:f797fc481b490edb305122c9181830a3a5b76d84ef6d1aef2fb9b47ab956f9e4", size = 6825, upload-time = "2024-08-20T03:39:25.966Z" },
+]
+
+[[package]]
+name = "jaraco-functools"
+version = "4.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "more-itertools" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f7/ed/1aa2d585304ec07262e1a83a9889880701079dde796ac7b1d1826f40c63d/jaraco_functools-4.3.0.tar.gz", hash = "sha256:cfd13ad0dd2c47a3600b439ef72d8615d482cedcff1632930d6f28924d92f294", size = 19755, upload-time = "2025-08-18T20:05:09.91Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b4/09/726f168acad366b11e420df31bf1c702a54d373a83f968d94141a8c3fde0/jaraco_functools-4.3.0-py3-none-any.whl", hash = "sha256:227ff8ed6f7b8f62c56deff101545fa7543cf2c8e7b82a7c2116e672f29c26e8", size = 10408, upload-time = "2025-08-18T20:05:08.69Z" },
+]
+
+[[package]]
+name = "jeepney"
+version = "0.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7b/6f/357efd7602486741aa73ffc0617fb310a29b588ed0fd69c2399acbb85b0c/jeepney-0.9.0.tar.gz", hash = "sha256:cf0e9e845622b81e4a28df94c40345400256ec608d0e55bb8a3feaa9163f5732", size = 106758, upload-time = "2025-02-27T18:51:01.684Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b2/a3/e137168c9c44d18eff0376253da9f1e9234d0239e0ee230d2fee6cea8e55/jeepney-0.9.0-py3-none-any.whl", hash = "sha256:97e5714520c16fc0a45695e5365a2e11b81ea79bba796e26f9f1d178cb182683", size = 49010, upload-time = "2025-02-27T18:51:00.104Z" },
+]
+
 [[package]]
 name = "jinja2"
 version = "3.1.6"
@@ -623,6 +774,21 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/bf/9c/8c95d856233c1f82500c2450b8c68576b4cf1c871db3afac5c34ff84e6fd/jsonschema-4.25.1-py3-none-any.whl", hash = "sha256:3fba0169e345c7175110351d456342c364814cfcf3b964ba4587f22915230a63", size = 90040, upload-time = "2025-08-18T17:03:48.373Z" },
 ]
 
+[[package]]
+name = "jsonschema-path"
+version = "0.4.0b1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pathable" },
+    { name = "pyrsistent" },
+    { name = "pyyaml" },
+    { name = "referencing" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0f/b9/eb99f1367ebcf8d6e2ae4f1c6e3da61eeb0ddd11c2695b1cdad8a9dad631/jsonschema_path-0.4.0b1.tar.gz", hash = "sha256:4678dcb27e5fbc58b39baf7ca8c36a6a7de3bcafacaaafc1b8a1d54038ce8d8a", size = 11807, upload-time = "2025-06-07T20:52:58.9Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/67/f5/24d5b91ed0409989140d1d4217e9c852d81782ced54e46b0582ad5f56dcb/jsonschema_path-0.4.0b1-py3-none-any.whl", hash = "sha256:f0cd42238c1445cecac3b2796fa24dcc62b8426623d1cb4d8d755f3715abf3ba", size = 15293, upload-time = "2025-06-07T20:52:57.029Z" },
+]
+
 [[package]]
 name = "jsonschema-specifications"
 version = "2025.9.1"
@@ -635,6 +801,23 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437, upload-time = "2025-09-08T01:34:57.871Z" },
 ]
 
+[[package]]
+name = "keyring"
+version = "25.7.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "jaraco-classes" },
+    { name = "jaraco-context" },
+    { name = "jaraco-functools" },
+    { name = "jeepney", marker = "sys_platform == 'linux'" },
+    { name = "pywin32-ctypes", marker = "sys_platform == 'win32'" },
+    { name = "secretstorage", marker = "sys_platform == 'linux'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/43/4b/674af6ef2f97d56f0ab5153bf0bfa28ccb6c3ed4d1babf4305449668807b/keyring-25.7.0.tar.gz", hash = "sha256:fe01bd85eb3f8fb3dd0405defdeac9a5b4f6f0439edbb3149577f244a2e8245b", size = 63516, upload-time = "2025-11-16T16:26:09.482Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/81/db/e655086b7f3a705df045bf0933bdd9c2f79bb3c97bfef1384598bb79a217/keyring-25.7.0-py3-none-any.whl", hash = "sha256:be4a0b195f149690c166e850609a477c532ddbfbaed96a404d4e43f8d5e2689f", size = 39160, upload-time = "2025-11-16T16:26:08.402Z" },
+]
+
 [[package]]
 name = "markdown-it-py"
 version = "4.0.0"
@@ -733,6 +916,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
 ]
 
+[[package]]
+name = "more-itertools"
+version = "10.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ea/5d/38b681d3fce7a266dd9ab73c66959406d565b3e85f21d5e66e1181d93721/more_itertools-10.8.0.tar.gz", hash = "sha256:f638ddf8a1a0d134181275fb5d58b086ead7c6a72429ad725c67503f13ba30bd", size = 137431, upload-time = "2025-09-02T15:23:11.018Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a4/8e/469e5a4a2f5855992e425f3cb33804cc07bf18d48f2db061aec61ce50270/more_itertools-10.8.0-py3-none-any.whl", hash = "sha256:52d4362373dcf7c52546bc4af9a86ee7c4579df9a8dc268be0a2f949d376cc9b", size = 69667, upload-time = "2025-09-02T15:23:09.635Z" },
+]
+
 [[package]]
 name = "numpy"
 version = "2.3.5"
@@ -785,6 +977,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/2d/fd/4b5eb0b3e888d86aee4d198c23acec7d214baaf17ea93c1adec94c9518b9/numpy-2.3.5-cp314-cp314t-win_arm64.whl", hash = "sha256:6203fdf9f3dc5bdaed7319ad8698e685c7a3be10819f41d32a0723e611733b42", size = 10545459, upload-time = "2025-11-16T22:52:20.55Z" },
 ]
 
+[[package]]
+name = "openapi-pydantic"
+version = "0.5.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/02/2e/58d83848dd1a79cb92ed8e63f6ba901ca282c5f09d04af9423ec26c56fd7/openapi_pydantic-0.5.1.tar.gz", hash = "sha256:ff6835af6bde7a459fb93eb93bb92b8749b754fc6e51b2f1590a19dc3005ee0d", size = 60892, upload-time = "2025-01-08T19:29:27.083Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/12/cf/03675d8bd8ecbf4445504d8071adab19f5f993676795708e36402ab38263/openapi_pydantic-0.5.1-py3-none-any.whl", hash = "sha256:a3a09ef4586f5bd760a8df7f43028b60cafb6d9f61de2acba9574766255ab146", size = 96381, upload-time = "2025-01-08T19:29:25.275Z" },
+]
+
 [[package]]
 name = "orjson"
 version = "3.11.4"
@@ -872,6 +1076,27 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/70/44/5191d2e4026f86a2a109053e194d3ba7a31a2d10a9c2348368c63ed4e85a/pandas-2.3.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:3869faf4bd07b3b66a9f462417d0ca3a9df29a9f6abd5d0d0dbab15dac7abe87", size = 13202175, upload-time = "2025-09-29T23:31:59.173Z" },
 ]
 
+[[package]]
+name = "pathable"
+version = "0.5.0b2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pyrsistent" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/10/a0/5ce545bf5d14d3b8925e73f12f67adee7a139a6726c0df75aca25ab6e8b7/pathable-0.5.0b2.tar.gz", hash = "sha256:0005483148dc1991ab32e4cb4cde7e2b8f376f081a1639631e424db0792860e9", size = 9896, upload-time = "2025-06-07T20:45:35.764Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/70/9a/8a74be1ab54bb62bd3c1554af8ef431c530f843d713785874207a77229e6/pathable-0.5.0b2-py3-none-any.whl", hash = "sha256:4c78bc5dae0c64a6191b955b7975bab58f0e298e197f591d4f0172886824a52b", size = 11374, upload-time = "2025-06-07T20:45:34.114Z" },
+]
+
+[[package]]
+name = "pathvalidate"
+version = "3.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fa/2a/52a8da6fe965dea6192eb716b357558e103aea0a1e9a8352ad575a8406ca/pathvalidate-3.3.1.tar.gz", hash = "sha256:b18c07212bfead624345bb8e1d6141cdcf15a39736994ea0b94035ad2b1ba177", size = 63262, upload-time = "2025-06-15T09:07:20.736Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9a/70/875f4a23bfc4731703a5835487d0d2fb999031bd415e7d17c0ae615c18b7/pathvalidate-3.3.1-py3-none-any.whl", hash = "sha256:5263baab691f8e1af96092fa5137ee17df5bdfbd6cff1fcac4d6ef4bc2e1735f", size = 24305, upload-time = "2025-06-15T09:07:19.117Z" },
+]
+
 [[package]]
 name = "pillow"
 version = "11.3.0"
@@ -927,6 +1152,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/89/c7/5572fa4a3f45740eaab6ae86fcdf7195b55beac1371ac8c619d880cfe948/pillow-11.3.0-cp314-cp314t-win_arm64.whl", hash = "sha256:79ea0d14d3ebad43ec77ad5272e6ff9bba5b679ef73375ea760261207fa8e0aa", size = 2512835, upload-time = "2025-07-01T09:15:50.399Z" },
 ]
 
+[[package]]
+name = "platformdirs"
+version = "4.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/61/33/9611380c2bdb1225fdef633e2a9610622310fed35ab11dac9620972ee088/platformdirs-4.5.0.tar.gz", hash = "sha256:70ddccdd7c99fc5942e9fc25636a8b34d04c24b335100223152c2803e4063312", size = 21632, upload-time = "2025-10-08T17:44:48.791Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/73/cb/ac7874b3e5d58441674fb70742e6c374b28b0c7cb988d37d991cde47166c/platformdirs-4.5.0-py3-none-any.whl", hash = "sha256:e578a81bb873cbb89a41fcc904c7ef523cc18284b7e3b3ccf06aca1403b7ebd3", size = 18651, upload-time = "2025-10-08T17:44:47.223Z" },
+]
+
 [[package]]
 name = "pluggy"
 version = "1.6.0"
@@ -936,6 +1170,44 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
 ]
 
+[[package]]
+name = "py-key-value-aio"
+version = "0.2.8"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "beartype" },
+    { name = "py-key-value-shared" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ca/35/65310a4818acec0f87a46e5565e341c5a96fc062a9a03495ad28828ff4d7/py_key_value_aio-0.2.8.tar.gz", hash = "sha256:c0cfbb0bd4e962a3fa1a9fa6db9ba9df812899bd9312fa6368aaea7b26008b36", size = 32853, upload-time = "2025-10-24T13:31:04.688Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cd/5a/e56747d87a97ad2aff0f3700d77f186f0704c90c2da03bfed9e113dae284/py_key_value_aio-0.2.8-py3-none-any.whl", hash = "sha256:561565547ce8162128fd2bd0b9d70ce04a5f4586da8500cce79a54dfac78c46a", size = 69200, upload-time = "2025-10-24T13:31:03.81Z" },
+]
+
+[package.optional-dependencies]
+disk = [
+    { name = "diskcache" },
+    { name = "pathvalidate" },
+]
+keyring = [
+    { name = "keyring" },
+]
+memory = [
+    { name = "cachetools" },
+]
+
+[[package]]
+name = "py-key-value-shared"
+version = "0.2.8"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "beartype" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/26/79/05a1f9280cfa0709479319cbfd2b1c5beb23d5034624f548c83fb65b0b61/py_key_value_shared-0.2.8.tar.gz", hash = "sha256:703b4d3c61af124f0d528ba85995c3c8d78f8bd3d2b217377bd3278598070cc1", size = 8216, upload-time = "2025-10-24T13:31:03.601Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/84/7a/1726ceaa3343874f322dd83c9ec376ad81f533df8422b8b1e1233a59f8ce/py_key_value_shared-0.2.8-py3-none-any.whl", hash = "sha256:aff1bbfd46d065b2d67897d298642e80e5349eae588c6d11b48452b46b8d46ba", size = 14586, upload-time = "2025-10-24T13:31:02.838Z" },
+]
+
 [[package]]
 name = "pycparser"
 version = "2.23"
@@ -960,6 +1232,11 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/82/2f/e68750da9b04856e2a7ec56fc6f034a5a79775e9b9a81882252789873798/pydantic-2.12.4-py3-none-any.whl", hash = "sha256:92d3d202a745d46f9be6df459ac5a064fdaa3c1c4cd8adcfa332ccf3c05f871e", size = 463400, upload-time = "2025-11-05T10:50:06.732Z" },
 ]
 
+[package.optional-dependencies]
+email = [
+    { name = "email-validator" },
+]
+
 [[package]]
 name = "pydantic-core"
 version = "2.41.5"
@@ -1059,6 +1336,24 @@ crypto = [
     { name = "cryptography" },
 ]
 
+[[package]]
+name = "pyperclip"
+version = "1.11.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e8/52/d87eba7cb129b81563019d1679026e7a112ef76855d6159d24754dbd2a51/pyperclip-1.11.0.tar.gz", hash = "sha256:244035963e4428530d9e3a6101a1ef97209c6825edab1567beac148ccc1db1b6", size = 12185, upload-time = "2025-09-26T14:40:37.245Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/df/80/fc9d01d5ed37ba4c42ca2b55b4339ae6e200b456be3a1aaddf4a9fa99b8c/pyperclip-1.11.0-py3-none-any.whl", hash = "sha256:299403e9ff44581cb9ba2ffeed69c7aa96a008622ad0c46cb575ca75b5b84273", size = 11063, upload-time = "2025-09-26T14:40:36.069Z" },
+]
+
+[[package]]
+name = "pyrsistent"
+version = "0.20.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ce/3a/5031723c09068e9c8c2f0bc25c3a9245f2b1d1aea8396c787a408f2b95ca/pyrsistent-0.20.0.tar.gz", hash = "sha256:4c48f78f62ab596c679086084d0dd13254ae4f3d6c72a83ffdf5ebdef8f265a4", size = 103642, upload-time = "2023-10-25T21:06:56.342Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/23/88/0acd180010aaed4987c85700b7cc17f9505f3edb4e5873e4dc67f613e338/pyrsistent-0.20.0-py3-none-any.whl", hash = "sha256:c55acc4733aad6560a7f5f818466631f07efc001fd023f34a6c203f8b6df0f0b", size = 58106, upload-time = "2023-10-25T21:06:54.387Z" },
+]
+
 [[package]]
 name = "pytest"
 version = "9.0.1"
@@ -1127,6 +1422,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c0/d2/21af5c535501a7233e734b8af901574572da66fcc254cb35d0609c9080dd/pywin32-311-cp314-cp314-win_arm64.whl", hash = "sha256:a508e2d9025764a8270f93111a970e1d0fbfc33f4153b388bb649b7eec4f9b42", size = 8932540, upload-time = "2025-07-14T20:13:36.379Z" },
 ]
 
+[[package]]
+name = "pywin32-ctypes"
+version = "0.2.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/85/9f/01a1a99704853cb63f253eea009390c88e7131c67e66a0a02099a8c917cb/pywin32-ctypes-0.2.3.tar.gz", hash = "sha256:d162dc04946d704503b2edc4d55f3dba5c1d539ead017afa00142c38b9885755", size = 29471, upload-time = "2024-08-14T10:15:34.626Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/de/3d/8161f7711c017e01ac9f008dfddd9410dff3674334c233bde66e7ba65bbf/pywin32_ctypes-0.2.3-py3-none-any.whl", hash = "sha256:8a1513379d709975552d202d942d9837758905c8d01eb82b8bcc30918929e7b8", size = 30756, upload-time = "2024-08-14T10:15:33.187Z" },
+]
+
 [[package]]
 name = "pyyaml"
 version = "6.0.3"
@@ -1165,15 +1469,15 @@ wheels = [
 
 [[package]]
 name = "referencing"
-version = "0.37.0"
+version = "0.36.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "attrs" },
     { name = "rpds-py" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/22/f5/df4e9027acead3ecc63e50fe1e36aca1523e1719559c499951bb4b53188f/referencing-0.37.0.tar.gz", hash = "sha256:44aefc3142c5b842538163acb373e24cce6632bd54bdb01b21ad5863489f50d8", size = 78036, upload-time = "2025-10-13T15:30:48.871Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/2f/db/98b5c277be99dd18bfd91dd04e1b759cad18d1a338188c936e92f921c7e2/referencing-0.36.2.tar.gz", hash = "sha256:df2e89862cd09deabbdba16944cc3f10feb6b3e6f18e902f7cc25609a34775aa", size = 74744, upload-time = "2025-01-25T08:48:16.138Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766, upload-time = "2025-10-13T15:30:47.625Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/b1/3baf80dc6d2b7bc27a95a67752d0208e410351e3feb4eb78de5f77454d8d/referencing-0.36.2-py3-none-any.whl", hash = "sha256:e8699adbbf8b5c7de96d8ffa0eb5c158b3beafce084968e2ea8bb08c6794dcd0", size = 26775, upload-time = "2025-01-25T08:48:14.241Z" },
 ]
 
 [[package]]
@@ -1282,6 +1586,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/2e/a3/0f0b7d78e2f1eb9e8e1afbff1d2bff8d60144aee17aca51c065b516743dd/safehttpx-0.1.7-py3-none-any.whl", hash = "sha256:c4f4a162db6993464d7ca3d7cc4af0ffc6515a606dfd220b9f82c6945d869cde", size = 8959, upload-time = "2025-10-24T18:30:08.733Z" },
 ]
 
+[[package]]
+name = "secretstorage"
+version = "3.4.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+    { name = "jeepney" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/32/8a/ed6747b1cc723c81f526d4c12c1b1d43d07190e1e8258dbf934392fc850e/secretstorage-3.4.1.tar.gz", hash = "sha256:a799acf5be9fb93db609ebaa4ab6e8f1f3ed5ae640e0fa732bfea59e9c3b50e8", size = 19871, upload-time = "2025-11-11T11:30:23.798Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b0/6d/24ebb101484f1911a6be6695b76ce43219caa110ebbe07d8c3a5f3106cca/secretstorage-3.4.1-py3-none-any.whl", hash = "sha256:c55d57b4da3de568d8c3af89dad244ab24c35ca1da8625fc1b550edf005ebc41", size = 15301, upload-time = "2025-11-11T11:30:22.618Z" },
+]
+
 [[package]]
 name = "semantic-version"
 version = "2.10.0"
@@ -1457,3 +1774,23 @@ sdist = { url = "https://files.pythonhosted.org/packages/cb/ce/f06b84e2697fef468
 wheels = [
     { url = "https://files.pythonhosted.org/packages/ee/d9/d88e73ca598f4f6ff671fb5fde8a32925c2e08a637303a1d12883c7305fa/uvicorn-0.38.0-py3-none-any.whl", hash = "sha256:48c0afd214ceb59340075b4a052ea1ee91c16fbc2a9b1469cca0e54566977b02", size = 68109, upload-time = "2025-10-18T13:46:42.958Z" },
 ]
+
+[[package]]
+name = "websockets"
+version = "15.0.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/21/e6/26d09fab466b7ca9c7737474c52be4f76a40301b08362eb2dbc19dcc16c1/websockets-15.0.1.tar.gz", hash = "sha256:82544de02076bafba038ce055ee6412d68da13ab47f0c60cab827346de828dee", size = 177016, upload-time = "2025-03-05T20:03:41.606Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/9f/51f0cf64471a9d2b4d0fc6c534f323b664e7095640c34562f5182e5a7195/websockets-15.0.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:ee443ef070bb3b6ed74514f5efaa37a252af57c90eb33b956d35c8e9c10a1931", size = 175440, upload-time = "2025-03-05T20:02:36.695Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/05/aa116ec9943c718905997412c5989f7ed671bc0188ee2ba89520e8765d7b/websockets-15.0.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5a939de6b7b4e18ca683218320fc67ea886038265fd1ed30173f5ce3f8e85675", size = 173098, upload-time = "2025-03-05T20:02:37.985Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/0b/33cef55ff24f2d92924923c99926dcce78e7bd922d649467f0eda8368923/websockets-15.0.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:746ee8dba912cd6fc889a8147168991d50ed70447bf18bcda7039f7d2e3d9151", size = 173329, upload-time = "2025-03-05T20:02:39.298Z" },
+    { url = "https://files.pythonhosted.org/packages/31/1d/063b25dcc01faa8fada1469bdf769de3768b7044eac9d41f734fd7b6ad6d/websockets-15.0.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:595b6c3969023ecf9041b2936ac3827e4623bfa3ccf007575f04c5a6aa318c22", size = 183111, upload-time = "2025-03-05T20:02:40.595Z" },
+    { url = "https://files.pythonhosted.org/packages/93/53/9a87ee494a51bf63e4ec9241c1ccc4f7c2f45fff85d5bde2ff74fcb68b9e/websockets-15.0.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:3c714d2fc58b5ca3e285461a4cc0c9a66bd0e24c5da9911e30158286c9b5be7f", size = 182054, upload-time = "2025-03-05T20:02:41.926Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/b2/83a6ddf56cdcbad4e3d841fcc55d6ba7d19aeb89c50f24dd7e859ec0805f/websockets-15.0.1-cp313-cp313-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0f3c1e2ab208db911594ae5b4f79addeb3501604a165019dd221c0bdcabe4db8", size = 182496, upload-time = "2025-03-05T20:02:43.304Z" },
+    { url = "https://files.pythonhosted.org/packages/98/41/e7038944ed0abf34c45aa4635ba28136f06052e08fc2168520bb8b25149f/websockets-15.0.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:229cf1d3ca6c1804400b0a9790dc66528e08a6a1feec0d5040e8b9eb14422375", size = 182829, upload-time = "2025-03-05T20:02:48.812Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/17/de15b6158680c7623c6ef0db361da965ab25d813ae54fcfeae2e5b9ef910/websockets-15.0.1-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:756c56e867a90fb00177d530dca4b097dd753cde348448a1012ed6c5131f8b7d", size = 182217, upload-time = "2025-03-05T20:02:50.14Z" },
+    { url = "https://files.pythonhosted.org/packages/33/2b/1f168cb6041853eef0362fb9554c3824367c5560cbdaad89ac40f8c2edfc/websockets-15.0.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:558d023b3df0bffe50a04e710bc87742de35060580a293c2a984299ed83bc4e4", size = 182195, upload-time = "2025-03-05T20:02:51.561Z" },
+    { url = "https://files.pythonhosted.org/packages/86/eb/20b6cdf273913d0ad05a6a14aed4b9a85591c18a987a3d47f20fa13dcc47/websockets-15.0.1-cp313-cp313-win32.whl", hash = "sha256:ba9e56e8ceeeedb2e080147ba85ffcd5cd0711b89576b83784d8605a7df455fa", size = 176393, upload-time = "2025-03-05T20:02:53.814Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/6c/c65773d6cab416a64d191d6ee8a8b1c68a09970ea6909d16965d26bfed1e/websockets-15.0.1-cp313-cp313-win_amd64.whl", hash = "sha256:e09473f095a819042ecb2ab9465aee615bd9c2028e4ef7d933600a8401c79561", size = 176837, upload-time = "2025-03-05T20:02:55.237Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/a8/5b41e0da817d64113292ab1f8247140aac61cbf6cfd085d6a0fa77f4984f/websockets-15.0.1-py3-none-any.whl", hash = "sha256:f7a866fbc1e97b5c617ee4116daaa09b722101d4a3c170c787450ba409f9736f", size = 169743, upload-time = "2025-03-05T20:03:39.41Z" },
+]