rearranging and a few bits of note taking

gemini.md

@@ -0,0 +1,55 @@
+# Gemini Context: Corvid Council Project
+    2 
+    3 ## Project Overview
+    4 - **Name**: Corvid Council (formerly "Cluas")
+    5 - **Concept**: A multi-agent group chat where four AI crow
+      experts (Corvus, Magpie, Raven, Crow) discuss topics using
+      specialized MCP tools. The application has two interfaces: a
+      Gradio chat UI for observing the discussion and an external
+      MCP tool endpoint for programmatic queries.
+    6 - **Goal**: To build this system for the Gradio Agents & MCP
+      Hackathon.
+    7 
+    8 ## Current State & Key Components
+    9 The project is in the very early stages of development,
+      aligning with "Week 1: Days 1-2" of the development guide.
+   10 
+   11 - **`Corvus` Character**: A skeleton implementation exists in
+      `src/characters/corvus.py`. It includes logic for searching
+      academic papers with a fallback mechanism and integrates with
+      the `AgentMemory` system.
+   12 - **`AgentMemory`**: A foundational component (
+      `src/cluas_mcp/common/memory.py`) has been created to act as
+      a shared, persistent knowledge base for the agents. It
+      replaces the earlier, simpler `CacheManager`.
+   13 - **Supporting Files**: The repository includes a detailed
+      `README.md` (acting as the development guide), a
+      `requirements.txt` file, and a `.gitignore` file. A
+      boilerplate `src/gradio/app.py` has also been added.
+   14 
+   15 ## Identified Issues & Blockers
+   16 1.  **Broken `corvus.py` Import**: The file
+      `src/cluas_mcp/common/formatting.py` is empty, which means
+      the `format_authors` and `snippet_abstract` functions
+      imported by `corvus.py` do not exist. This prevents the
+      `Corvus` character from running.
+   17 2.  **Missing Core Architecture**: Key components from the
+      development guide are not yet implemented:
+   18     -   `CouncilOrchestrator` class to manage the
+      conversation.
+   19     -   A `Character` base class.
+   20     -   Integration between the Gradio UI and the agent
+      logic.
+   21 3.  **Incomplete File Structure**: The current file structure
+      does not yet match the target structure outlined in the
+      development guide (e.g., separation of tools into their own
+      modules).
+   22 4.  **Placeholder API Clients**: The `PubMedClient` and
+      `SemanticScholarClient` are still stubs.
+   23 
+   24 ## Session State
+   25 - **File System Access Lost**: The project's root directory
+      was moved from `/Users/gboa/MCP-course-hf` to
+      `/Users/gboa/cluas`. My environment is sandboxed to the
+      original path, so I can no longer read from or write to any
+      project files.

main.py

@@ -1,6 +0,0 @@
-def main():
-    print("Hello from mcp-course-hf!")
-
-
-if __name__ == "__main__":
-    main()

notes_etc/development_guide_01.md

@@ -0,0 +1,797 @@
+# 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

@@ -0,0 +1,181 @@
+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

@@ -0,0 +1,14 @@
+# 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_lightweight_architecture_diagram.txt

@@ -0,0 +1,53 @@
+        ┌─────────────────────────────┐
+        │ External User / App         │
+        │ (Claude Desktop, API call) │
+        └─────────────┬─────────────┘
+                      │ ask_crow_council(question)
+                      ▼
+        ┌─────────────────────────────┐
+        │ Gradio App / MCP Server     │
+        │ (crow-chat-mcp)             │
+        └─────────────┬─────────────┘
+                      │ orchestrates
+                      ▼
+        ┌─────────────────────────────┐
+        │ CouncilOrchestrator         │
+        │ - Handles conversation flow │
+        │ - Calls Character agents    │
+        └─────────────┬─────────────┘
+                      │ interacts with
+                      ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│   Corvus      │   │   Magpie      │   │   Raven       │   │   Crow        │
+│ (Scholar)     │   │ (Enthusiast)  │   │ (Activist)   │   │ (Observer)    │
+│ - Academic    │   │ - Web/Social  │   │ - Real-time  │   │ - Observational│
+│   Tools       │   │   Tools       │   │   Data Tools │   │   Tools       │
+└───────┬───────┘   └───────┬───────┘   └───────┬───────┘   └───────┬───────┘
+        │                     │                     │                     │
+        │                     │                     │                     │
+        └───────────────┬─────────────────────────┴─────────────────────┘
+                        ▼
+                 ┌─────────────┐
+                 │ AgentMemory │
+                 │ (JSON / DB) │
+                 │ - Logs items│
+                 │ - Tags, DOI │
+                 │ - Recency   │
+                 └─────────────┘
+                        │
+                        ▼
+                 ┌─────────────┐
+                 │ LLM / Synthesis │
+                 │ - Creates unified│
+                 │   consensus      │
+                 └─────────────┘
+                        │
+                        ▼
+                 ┌─────────────┐
+                 │ Structured  │
+                 │ Response    │
+                 │ (JSON / UI)│
+                 └─────────────┘
+                        │
+                        ▼
+                 External User / App

reviews/changes.md

@@ -0,0 +1,60 @@
+# 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.

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

@@ -0,0 +1,61 @@
+# 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

@@ -0,0 +1,50 @@
+# 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.

{cluas/src → src}/cluas_mcp/common/api_clients.py

@@ -34,3 +34,57 @@ class ArxivClient:
                 "arxiv_link": getattr(entry, "link", "")
             })
         return results
+
+
+
+
+# possible endpoint?
+# https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&retmode=json&term=corvid+AND+memory
+
+
+
+
+# from Bio import Entrez
+# Entrez.email = "your.email@domain.tld"  # required by NCBI
+# Entrez.api_key = "YOUR_KEY_IF_YOU_HAVE_ONE"
+
+# KEYWORDS = ['corvid','crow','raven','corvus','jay','magpie','jackdaw','rook','chough','nutcracker']
+# SECONDARY = ['memory', 'feeding']
+
+# term = "(" + " OR ".join(KEYWORDS) + ")" + " AND (" + " OR ".join(SECONDARY) + ")"
+# handle = Entrez.esearch(db="pubmed", term=term, retmax=100)  # adjust retmax
+# record = Entrez.read(handle)
+# ids = record["IdList"]
+
+# for pmid in ids:
+#     handle2 = Entrez.efetch(db="pubmed", id=pmid, retmode="xml")
+#     rec = Entrez.read(handle2)
+#     article = rec['PubmedArticle'][0]
+#     # parse title
+#     title = article['MedlineCitation']['Article']['ArticleTitle']
+#     # parse authors
+#     authors = article['MedlineCitation']['Article']['AuthorList']
+#     first_author = authors[0]['LastName'] + ", " + authors[0]['ForeName']
+#     author_str = first_author + (", et al" if len(authors) > 1 else "")
+#     # parse abstract
+#     abstract = ""
+#     if 'Abstract' in article['MedlineCitation']['Article']:
+#         abstract = " ".join([x for x in article['MedlineCitation']['Article']['Abstract']['AbstractText']])
+#     # parse DOI
+#     doi = None
+#     for aid in article['PubmedData']['ArticleIdList']:
+#         if aid.attributes['IdType'] == 'doi':
+#             doi = str(aid)
+#     # parse a “conclusion” if structured abstract includes it
+#     conclusion = None
+#     # one simple heuristic: look for segments labeled 'CONCLUSION' in structured abstract
+#     if 'Abstract' in article['MedlineCitation']['Article']:
+#         for sec in article['MedlineCitation']['Article']['Abstract']['AbstractText']:
+#             if hasattr(sec, "attributes") and sec.attributes.get('Label', '').upper() == 'CONCLUSION':
+#                 conclusion = str(sec)
+#     # fallback: maybe take the last sentence of abstract
+#     if conclusion is None and abstract:
+#         conclusion = abstract.split('.')[-2] + '.'
+
+#     # now you have doi, title, author_str, abstract, conclusion
+#     print(pmid, doi, title, author_str, conclusion)

src/cluas_mcp/common/formatting.py

@@ -0,0 +1,22 @@
+# some thoughts re:formatting
+#  havent set up API calls properly yet tho 
+
+
+def snippet_abstract(abstract: str, max_length: int = 200) -> str:
+    """Truncate abstract to first N chars, end at sentence."""
+    if len(abstract) <= max_length:
+        return abstract
+    
+    truncated = abstract[:max_length]
+    last_period = truncated.rfind('.')
+    if last_period > 0:
+        return truncated[:last_period + 1]
+    return truncated + "..."
+
+def format_authors(authors: list) -> str:
+    """Format author list as 'First, Second, et al.'"""
+    if not authors:
+        return "Unknown authors"
+    if len(authors) <= 2:
+        return ", ".join(authors)
+    return f"{authors[0]}, {authors[1]}, et al."