gemini-grounded iterative research with google search integration
Executes multi-turn research workflows using Google Gemini API with built-in Google Search grounding to retrieve factual, up-to-date information. The Deep Research Agent (src/research/server.py) implements a tool-use pattern where Gemini can invoke search tools iteratively, refining queries based on intermediate results, and persists findings into a structured research.md file. Supports YouTube transcript extraction when URLs are provided, enabling multi-modal source integration.
Unique: Uses Gemini's native Google Search grounding (not external RAG) combined with tool-use agents for iterative query refinement, eliminating hallucination risk while maintaining real-time information access. YouTube transcript extraction is built-in, enabling multi-modal research without separate API calls.
vs alternatives: Faster and more accurate than RAG-based research systems because it queries live search results directly rather than relying on static embeddings, and cheaper than multi-step LLM chains because grounding is native to Gemini's API.
mcp-based multi-agent orchestration with decoupled server architecture
Implements a two-server MCP architecture (Deep Research Agent + LinkedIn Writer Agent) using FastMCP framework, where each server exposes tools, resources, and prompts independently and communicates through standardized MCP protocol. The architecture decouples research and writing concerns, allowing each agent to be developed, tested, and scaled independently while maintaining a unified interface. Configuration is managed via .mcp.json and environment variables, enabling runtime server discovery and tool registration.
Unique: Uses FastMCP framework to expose agents as standardized MCP servers rather than monolithic functions, enabling true decoupling where each agent (research, writing) has its own process, configuration, and tool registry. This pattern allows IDE integration (Claude Code, Cursor) without custom client code.
vs alternatives: More modular and testable than LangChain agent chains because each agent is independently deployable and has explicit tool/resource contracts, and more flexible than REST-based agent APIs because MCP provides native IDE integration without custom UI.
configuration management with environment variables and pydantic settings
Centralizes configuration using Pydantic Settings models (src/research/config/, src/writing/config/) that load from environment variables and .env files, enabling environment-specific configuration without code changes. Configuration includes API keys, model parameters, evaluation thresholds, and server endpoints. Pydantic validation ensures type safety and provides helpful error messages for missing or invalid configuration.
Unique: Uses Pydantic Settings for type-safe, validated configuration with automatic environment variable loading. Configuration is centralized in dedicated config modules (src/research/config/, src/writing/config/), making it easy to add new configuration options without modifying agent code.
vs alternatives: More robust than manual environment variable parsing because Pydantic validates types and provides helpful error messages, and more maintainable than hardcoded configuration because all settings are in one place.
structured research persistence and markdown-based knowledge representation
Persists research findings to a structured markdown file (research.md) that serves as the knowledge base for the writing agent. The markdown format enables human readability while maintaining machine-parseable structure (headings, lists, citations). Research findings include source citations, timestamps, and iterative search history, creating an auditable record of how conclusions were reached. The writing agent reads this markdown to generate content, ensuring factual grounding.
Unique: Uses markdown as the primary knowledge representation format, enabling both machine parsing (for writing agent) and human inspection (for manual review). Includes source citations and search history, creating an auditable record of research methodology.
vs alternatives: More transparent than vector databases because research is human-readable and manually editable, and more flexible than structured databases because markdown can accommodate unstructured notes and citations.
evaluator-optimizer loop for iterative content refinement
Implements a multi-iteration content generation and evaluation pattern in the LinkedIn Writer Agent (src/writing/server.py) where an LLM generates initial content, an evaluator (LLM-as-judge) scores it against quality criteria, and an optimizer refines it based on feedback. The loop continues until quality thresholds are met or max iterations reached. Uses Opik for tracing and LLM-based evaluation metrics, enabling observable, measurable content quality improvement without human-in-the-loop.
Unique: Combines LLM-as-judge evaluation with iterative optimization in a closed loop, using Opik for full observability of each refinement cycle. Unlike simple prompt engineering, this pattern measures quality objectively and refines based on measurable feedback, not heuristics.
vs alternatives: More reliable than single-pass LLM generation because it validates and refines output against explicit criteria, and more transparent than black-box content APIs because every iteration is traced and evaluated metrics are visible.
ai image generation with gemini imagen integration
Integrates Google Gemini's Imagen model for AI-generated images within the writing workflow, enabling automatic image creation to accompany generated LinkedIn posts. The image generation is triggered based on post content and writing profiles, with generated images persisted to the dataset directory. Supports prompt engineering for image generation based on post themes and audience preferences.
Unique: Integrates Imagen directly into the writing workflow as a native step, not a separate tool — image generation is triggered automatically based on post content and writing profiles, enabling end-to-end content creation without manual image selection.
vs alternatives: More integrated than using external image APIs (DALL-E, Midjourney) because it's part of the same Gemini API ecosystem and can reference post content directly, and faster than manual image selection because generation is automated and parallelizable.
dataset-driven evaluation with llm-as-judge metrics
Implements a structured dataset system (datasets/ directory) with batch evaluation scripts that process multiple content samples through the writing workflow and score them using LLM-as-judge metrics via Opik. The evaluation system measures quality across dimensions (clarity, engagement, relevance) and aggregates results for statistical analysis. Supports dataset versioning and comparison across model versions or writing profiles.
Unique: Combines structured dataset management with Opik-based LLM-as-judge evaluation, enabling systematic quality measurement across multiple samples with full traceability. Unlike ad-hoc evaluation, this pattern produces reproducible, comparable metrics across writing profiles and model versions.
vs alternatives: More rigorous than manual spot-checking because it evaluates entire datasets systematically, and more transparent than black-box quality scores because each evaluation is traced in Opik with full iteration history visible.
mcp tool and resource definition with schema-based routing
Defines MCP tools and resources using FastMCP decorators (@mcp.tool, @mcp.resource) with JSON schema validation, enabling type-safe tool invocation and automatic schema generation. The research and writing servers expose distinct tool sets (search, research persistence, content generation, evaluation) with Pydantic-based input/output validation. MCP routers (src/research/routers/, src/writing/routers/) map tool invocations to application logic, decoupling tool definitions from implementation.
Unique: Uses FastMCP decorators with Pydantic models to automatically generate MCP tool schemas, eliminating manual JSON schema writing. Router pattern (src/research/routers/, src/writing/routers/) decouples tool definitions from implementation, enabling easy tool addition without modifying server core.
vs alternatives: More maintainable than hand-written JSON schemas because Pydantic models are single source of truth, and more discoverable than REST APIs because MCP clients can introspect tool schemas at runtime without documentation.
+4 more capabilities