Add development environment setup with uv, pyproject.toml, and Makefile

- Added pyproject.toml with project metadata and dependencies
- Created comprehensive Makefile for development tasks
- Set up uv virtual environment with all dependencies
- Added .gitignore for Python/uv projects
- Created CLAUDE.md documentation for future Claude instances
- Added basic test structure with pytest
- Configured ruff, mypy, and pytest in pyproject.toml

Development commands available via make:
- make setup: Create venv and install dependencies
- make test: Run all tests
- make lint: Run linter
- make format: Format code
- make run-ui: Run Gradio interface
- make deploy-github/deploy-hf: Deploy to repositories

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,175 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+.venv/
+venv/
+ENV/
+env/
+.env.local
+
+# uv
+.uv/
+uv.lock
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask
+instance/
+.webassets-cache
+
+# Scrapy
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder
+.spyderproject
+.spyproject
+
+# Rope
+.ropeproject
+
+# mkdocs
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre
+.pyre/
+
+# pytype
+.pytype/
+
+# Cython
+cython_debug/
+
+# ruff
+.ruff_cache/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Project specific
+agent.log
+output/
+logs/
+sessions.db
+*.db
+*.sqlite
+
+# User profile (may contain sensitive info)
+profile.yaml
+
+# Temporary files
+*.tmp
+*.bak
+*.swp
+*~
+
+# ADK/Gemini cache
+.adk_cache/
+.google_cache/
+
+# Session data (local only)
+~/.agentic-content-generation/
+
+# Build artifacts
+*.whl
+*.tar.gz

CLAUDE.md

@@ -0,0 +1,219 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**Scientific Content Generation Agent** - A multi-agent system that generates research-backed content (blog articles, LinkedIn posts, Twitter threads) from scientific topics. Built with Google's Agent Development Kit (ADK) and deployed on Hugging Face Spaces.
+
+**Framework**: Google Agent Development Kit (ADK)
+**Model**: Gemini 2.0 Flash (`gemini-2.0-flash-exp`)
+**UI**: Gradio 6.0
+**Deployment**: Hugging Face Spaces (free hosting)
+
+## Commands
+
+### Local Development
+
+```bash
+# Run the Gradio UI locally
+python app.py
+
+# Run CLI version with default topic
+python main.py
+
+# Run CLI with custom topic
+python main.py --topic "Your Research Topic"
+
+# Initialize user profile
+python main.py --init-profile
+
+# Edit profile interactively
+python main.py --edit-profile
+
+# Validate profile
+python main.py --validate-profile
+
+# List all sessions
+python main.py --list-sessions
+
+# Resume a session
+python main.py --session-id <SESSION_ID>
+
+# Delete a session
+python main.py --delete-session <SESSION_ID>
+```
+
+### Hugging Face Deployment
+
+```bash
+# Add and commit changes
+git add .
+git commit -m "Your commit message"
+
+# Push to Hugging Face Space (triggers automatic rebuild)
+git push origin main
+```
+
+**Important**: Set `GOOGLE_API_KEY` as a secret in Hugging Face Space settings before deployment.
+
+## Architecture
+
+### Multi-Agent Pipeline
+
+The system uses a **SequentialAgent** (not ParallelAgent) because each agent depends on outputs from previous agents. State flows linearly through the pipeline via the `output_key`/placeholder pattern.
+
+**5-Agent Pipeline** (execution order matters):
+
+1. **ResearchAgent** ([src/agents.py:28](src/agents.py#L28))
+   - Searches academic papers (arXiv API)
+   - Searches web trends (DuckDuckGo)
+   - Extracts key findings
+   - Outputs: `research_findings`
+
+2. **StrategyAgent** ([src/agents.py:74](src/agents.py#L74))
+   - Analyzes research findings
+   - Plans content approach for each platform
+   - Defines target audience and key messages
+   - Focuses on professional positioning
+   - Outputs: `content_strategy`
+
+3. **ContentGeneratorAgent** ([src/agents.py:160](src/agents.py#L160))
+   - Creates platform-specific content
+   - Blog (1000-2000 words)
+   - LinkedIn post (300-800 words)
+   - Twitter thread (8-12 tweets)
+   - Outputs: `generated_content`
+
+4. **LinkedInOptimizationAgent** ([src/agents.py:234](src/agents.py#L234))
+   - Optimizes LinkedIn post for SEO
+   - Adds engagement hooks and CTAs
+   - Integrates portfolio mentions
+   - Emphasizes business value
+   - Outputs: `optimized_linkedin`
+
+5. **ReviewAgent** ([src/agents.py:316](src/agents.py#L316))
+   - Verifies scientific accuracy
+   - Adds proper citations (APA format)
+   - Scores opportunity appeal
+   - Final polish
+   - Outputs: `final_content`
+
+### Key Design Decisions
+
+**Retry Configuration** ([src/config.py:24](src/config.py#L24)):
+- 5 attempts with exponential backoff (exp_base=7)
+- Handles rate limiting (429) and server errors (500/503/504)
+- Critical for Gemini API free tier reliability
+
+**XML Parsing** ([src/tools.py:44](src/tools.py#L44)):
+- Uses ElementTree (not string parsing) for arXiv API responses
+- Robust handling of namespaces and malformed entries
+
+**Opportunity Scoring** ([src/tools.py:768](src/tools.py#L768)):
+- Weighted: SEO (30%) + Engagement (30%) + Business Value (25%) + Portfolio (15%)
+- Based on LinkedIn algorithm priorities and recruiter behavior
+
+### File Structure
+
+```
+scientific-content-agent/
+├── app.py                  # Entry point for HF Spaces (imports ui_app)
+├── main.py                 # CLI entry point with async pipeline
+├── ui_app.py               # Gradio interface (4 tabs)
+├── requirements.txt        # Python dependencies
+├── profile.example.yaml    # User profile template
+├── .env.example            # API key template
+└── src/
+    ├── agents.py           # Agent definitions and pipeline
+    ├── config.py           # Configuration and constants
+    ├── tools.py            # Custom tools (search_papers, search_web, etc.)
+    ├── profile.py          # UserProfile dataclass and management
+    ├── profile_editor.py   # Interactive profile editing
+    └── session_manager.py  # Session persistence (SQLite)
+```
+
+### State Management
+
+**Profile System**: User profiles stored in `~/.agentic-content-generation/profile.yaml` (local) or managed via Gradio UI (HF Spaces). Profiles inject professional context into agent instructions.
+
+**Session Persistence**: SQLite database at `~/.agentic-content-generation/sessions.db` stores conversation history. Sessions can be resumed by ID.
+
+**Agent State Flow**:
+```
+User Input → ResearchAgent → {research_findings}
+          → StrategyAgent → {content_strategy}
+          → ContentGeneratorAgent → {generated_content}
+          → LinkedInOptimizationAgent → {optimized_linkedin}
+          → ReviewAgent → {final_content}
+```
+
+Placeholders like `{research_findings}` in agent instructions are replaced with actual outputs from previous agents.
+
+## Tools
+
+All custom tools return `dict[str, Any]` with `status` field ("success" or "error").
+
+**Research Tools**:
+- `search_papers(topic, max_results)` - arXiv API search
+- `search_web(query, max_results)` - DuckDuckGo search
+- `extract_key_findings(research_text)` - Keyword-based extraction
+
+**Content Tools**:
+- `format_for_platform(content, platform, topic)` - Platform-specific formatting
+- `generate_citations(sources, style)` - APA/MLA/Chicago citations
+
+**Optimization Tools**:
+- `generate_seo_keywords(topic, role)` - Recruiter-focused keywords
+- `create_engagement_hooks(topic, goal)` - CTAs and discussion prompts
+- `search_industry_trends(field, region)` - Market demands and hot skills
+- `analyze_content_for_opportunities(content, target_role)` - Opportunity scoring
+
+## Configuration
+
+**Environment Variables** (`.env`):
+```bash
+GOOGLE_API_KEY=your_key_here
+GOOGLE_GENAI_USE_VERTEXAI=FALSE
+```
+
+**Constants** ([src/config.py](src/config.py)):
+- `DEFAULT_MODEL = "gemini-2.0-flash-exp"`
+- `MAX_PAPERS_PER_SEARCH = 5`
+- `CITATION_STYLE = "apa"`
+- `SUPPORTED_PLATFORMS = ["blog", "linkedin", "twitter"]`
+
+## Gradio UI
+
+4 tabs in [ui_app.py](ui_app.py):
+
+1. **Generate Content** - Main content generation interface
+2. **Profile Editor** - Manage user professional profile
+3. **Session History** - View and resume past sessions
+4. **Settings** - Configure API key and preferences
+
+Progress tracking uses fixed milestones (no real-time ADK event hooks).
+
+## Common Issues
+
+**Build fails on HF Spaces**: Ensure all dependencies in [requirements.txt](requirements.txt) are compatible with Python 3.11+.
+
+**Rate limiting**: Retry config handles 429 errors automatically. If persistent, consider upgrading to Vertex AI.
+
+**No content generated**: Check that `GOOGLE_API_KEY` is set as a Space secret or in Settings tab.
+
+**arXiv API errors**: Tool gracefully handles XML parse errors and malformed entries (continues processing).
+
+## API Key Management
+
+**Local**: Create `.env` file with `GOOGLE_API_KEY=...`
+**HF Spaces**: Add as secret in Space settings (name: `GOOGLE_API_KEY`)
+**Get key**: https://aistudio.google.com/app/api_keys
+
+## Testing
+
+No formal test suite yet. Manual testing:
+- Generate content for a topic
+- Verify all 3 platforms (Blog, LinkedIn, Twitter)
+- Check citations format
+- Validate opportunity scores

Makefile

@@ -0,0 +1,230 @@
+.PHONY: help install install-dev test test-unit test-integration test-cov lint format type-check clean run run-cli run-ui setup venv sync update build deploy-hf deploy-github all check
+
+# Default target
+.DEFAULT_GOAL := help
+
+# Variables
+PYTHON := python3
+UV := uv
+VENV_DIR := .venv
+SRC_DIR := src
+TEST_DIR := tests
+COVERAGE_DIR := htmlcov
+
+# Colors for output
+BLUE := \033[0;34m
+GREEN := \033[0;32m
+YELLOW := \033[0;33m
+RED := \033[0;31m
+NC := \033[0m # No Color
+
+help: ## Show this help message
+	@echo "$(BLUE)Scientific Content Agent - Development Commands$(NC)"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "$(GREEN)%-20s$(NC) %s\n", $$1, $$2}'
+
+# Setup and Installation
+setup: venv install-dev ## Complete setup: create venv and install all dependencies
+	@echo "$(GREEN)✓ Setup complete! Activate with: source .venv/bin/activate$(NC)"
+
+venv: ## Create uv virtual environment
+	@echo "$(BLUE)Creating uv virtual environment...$(NC)"
+	$(UV) venv $(VENV_DIR)
+	@echo "$(GREEN)✓ Virtual environment created$(NC)"
+
+install: ## Install production dependencies
+	@echo "$(BLUE)Installing production dependencies...$(NC)"
+	$(UV) pip install -e .
+	@echo "$(GREEN)✓ Production dependencies installed$(NC)"
+
+install-dev: ## Install development dependencies
+	@echo "$(BLUE)Installing development dependencies...$(NC)"
+	$(UV) pip install -e ".[dev]"
+	@echo "$(GREEN)✓ Development dependencies installed$(NC)"
+
+sync: ## Sync dependencies with pyproject.toml
+	@echo "$(BLUE)Syncing dependencies...$(NC)"
+	$(UV) pip sync pyproject.toml
+	@echo "$(GREEN)✓ Dependencies synced$(NC)"
+
+update: ## Update all dependencies to latest versions
+	@echo "$(BLUE)Updating dependencies...$(NC)"
+	$(UV) pip install --upgrade -e ".[dev]"
+	@echo "$(GREEN)✓ Dependencies updated$(NC)"
+
+# Running the application
+run: run-ui ## Run the Gradio UI (default)
+
+run-ui: ## Run the Gradio web interface
+	@echo "$(BLUE)Starting Gradio UI...$(NC)"
+	$(UV) run python app.py
+
+run-cli: ## Run the CLI version (use: make run-cli TOPIC="your topic")
+	@echo "$(BLUE)Running CLI...$(NC)"
+	@if [ -z "$(TOPIC)" ]; then \
+		$(UV) run python main.py; \
+	else \
+		$(UV) run python main.py --topic "$(TOPIC)"; \
+	fi
+
+run-session: ## Resume a session (use: make run-session SESSION_ID=...)
+	@if [ -z "$(SESSION_ID)" ]; then \
+		echo "$(RED)Error: SESSION_ID not provided. Use: make run-session SESSION_ID=xxx$(NC)"; \
+		exit 1; \
+	fi
+	$(UV) run python main.py --session-id "$(SESSION_ID)"
+
+# Profile Management
+profile-init: ## Initialize default profile
+	@echo "$(BLUE)Initializing profile...$(NC)"
+	$(UV) run python main.py --init-profile
+
+profile-edit: ## Edit profile interactively
+	@echo "$(BLUE)Opening profile editor...$(NC)"
+	$(UV) run python main.py --edit-profile
+
+profile-validate: ## Validate current profile
+	@echo "$(BLUE)Validating profile...$(NC)"
+	$(UV) run python main.py --validate-profile
+
+# Session Management
+sessions-list: ## List all sessions
+	@echo "$(BLUE)Listing sessions...$(NC)"
+	$(UV) run python main.py --list-sessions
+
+session-delete: ## Delete a session (use: make session-delete SESSION_ID=...)
+	@if [ -z "$(SESSION_ID)" ]; then \
+		echo "$(RED)Error: SESSION_ID not provided. Use: make session-delete SESSION_ID=xxx$(NC)"; \
+		exit 1; \
+	fi
+	$(UV) run python main.py --delete-session "$(SESSION_ID)"
+
+# Testing
+test: ## Run all tests
+	@echo "$(BLUE)Running all tests...$(NC)"
+	$(UV) run pytest
+
+test-unit: ## Run unit tests only
+	@echo "$(BLUE)Running unit tests...$(NC)"
+	$(UV) run pytest -m unit
+
+test-integration: ## Run integration tests only
+	@echo "$(BLUE)Running integration tests...$(NC)"
+	$(UV) run pytest -m integration
+
+test-fast: ## Run tests without slow tests
+	@echo "$(BLUE)Running fast tests...$(NC)"
+	$(UV) run pytest -m "not slow"
+
+test-cov: ## Run tests with coverage report
+	@echo "$(BLUE)Running tests with coverage...$(NC)"
+	$(UV) run pytest --cov=$(SRC_DIR) --cov-report=html --cov-report=term
+	@echo "$(GREEN)✓ Coverage report generated at $(COVERAGE_DIR)/index.html$(NC)"
+
+test-watch: ## Run tests in watch mode (requires pytest-watch)
+	@echo "$(BLUE)Running tests in watch mode...$(NC)"
+	$(UV) run ptw -- -v
+
+# Code Quality
+lint: ## Run ruff linter
+	@echo "$(BLUE)Running ruff linter...$(NC)"
+	$(UV) run ruff check $(SRC_DIR) $(TEST_DIR) main.py ui_app.py app.py
+
+lint-fix: ## Run ruff linter and fix issues
+	@echo "$(BLUE)Running ruff linter with auto-fix...$(NC)"
+	$(UV) run ruff check --fix $(SRC_DIR) $(TEST_DIR) main.py ui_app.py app.py
+	@echo "$(GREEN)✓ Linting complete$(NC)"
+
+format: ## Format code with ruff
+	@echo "$(BLUE)Formatting code...$(NC)"
+	$(UV) run ruff format $(SRC_DIR) $(TEST_DIR) main.py ui_app.py app.py
+	@echo "$(GREEN)✓ Code formatted$(NC)"
+
+type-check: ## Run mypy type checker
+	@echo "$(BLUE)Running mypy type checker...$(NC)"
+	$(UV) run mypy $(SRC_DIR)
+
+check: lint type-check test-fast ## Run all checks (lint, type-check, fast tests)
+	@echo "$(GREEN)✓ All checks passed!$(NC)"
+
+all: format lint type-check test ## Format, lint, type-check, and test everything
+	@echo "$(GREEN)✓ All tasks completed!$(NC)"
+
+# Cleaning
+clean: ## Clean build artifacts and cache files
+	@echo "$(BLUE)Cleaning build artifacts...$(NC)"
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info
+	rm -rf $(COVERAGE_DIR)
+	rm -rf .coverage
+	rm -rf .pytest_cache
+	rm -rf .mypy_cache
+	rm -rf .ruff_cache
+	rm -rf $(SRC_DIR)/__pycache__
+	rm -rf $(TEST_DIR)/__pycache__
+	rm -rf __pycache__
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete
+	find . -type f -name "*.pyo" -delete
+	@echo "$(GREEN)✓ Cleaned$(NC)"
+
+clean-all: clean ## Clean everything including venv
+	@echo "$(BLUE)Cleaning virtual environment...$(NC)"
+	rm -rf $(VENV_DIR)
+	rm -rf output/
+	rm -rf logs/
+	rm -f agent.log
+	@echo "$(GREEN)✓ Everything cleaned$(NC)"
+
+# Building
+build: ## Build the project
+	@echo "$(BLUE)Building project...$(NC)"
+	$(UV) build
+	@echo "$(GREEN)✓ Build complete$(NC)"
+
+# Deployment
+deploy-hf: ## Deploy to Hugging Face Spaces
+	@echo "$(BLUE)Deploying to Hugging Face Spaces...$(NC)"
+	@if [ -z "$(MSG)" ]; then \
+		echo "$(RED)Error: Commit message required. Use: make deploy-hf MSG='your message'$(NC)"; \
+		exit 1; \
+	fi
+	git add .
+	git commit -m "$(MSG)"
+	git push origin main
+	@echo "$(GREEN)✓ Pushed to Hugging Face. Check build status at:$(NC)"
+	@echo "$(BLUE)https://huggingface.co/spaces/Chris30/scientific-content-agent$(NC)"
+
+deploy-github: ## Deploy to GitHub
+	@echo "$(BLUE)Deploying to GitHub...$(NC)"
+	@if [ -z "$(MSG)" ]; then \
+		echo "$(RED)Error: Commit message required. Use: make deploy-github MSG='your message'$(NC)"; \
+		exit 1; \
+	fi
+	git add .
+	git commit -m "$(MSG)"
+	git push github main
+	@echo "$(GREEN)✓ Pushed to GitHub$(NC)"
+
+deploy-both: ## Deploy to both Hugging Face and GitHub
+	@echo "$(BLUE)Deploying to both remotes...$(NC)"
+	@if [ -z "$(MSG)" ]; then \
+		echo "$(RED)Error: Commit message required. Use: make deploy-both MSG='your message'$(NC)"; \
+		exit 1; \
+	fi
+	git add .
+	git commit -m "$(MSG)"
+	git push origin main
+	git push github main
+	@echo "$(GREEN)✓ Pushed to both Hugging Face and GitHub$(NC)"
+
+# Development workflow
+dev: format lint-fix ## Format and lint code
+	@echo "$(GREEN)✓ Code formatted and linted$(NC)"
+
+pre-commit: format lint type-check test-fast ## Pre-commit checks (format, lint, type-check, fast tests)
+	@echo "$(GREEN)✓ Pre-commit checks passed!$(NC)"
+
+ci: lint type-check test-cov ## Run CI checks (lint, type-check, test with coverage)
+	@echo "$(GREEN)✓ CI checks passed!$(NC)"

pyproject.toml

@@ -0,0 +1,180 @@
+[project]
+name = "scientific-content-agent"
+version = "0.1.0"
+description = "AI-powered multi-agent system for generating research-backed content"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Christophe Bourgoin", email = "chris@example.com" }
+]
+keywords = [
+    "ai",
+    "agents",
+    "content-generation",
+    "multi-agent",
+    "google-adk",
+    "gradio",
+    "research",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "google-adk>=0.1.0",
+    "google-genai>=0.1.0",
+    "google-cloud-aiplatform>=1.38.0",
+    "gradio>=6.0.1",
+    "python-dotenv>=1.0.0",
+    "requests>=2.31.0",
+    "duckduckgo-search>=6.0.0",
+    "pyyaml>=6.0",
+    "pandas>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.1.0",
+    "mypy>=1.8.0",
+    "types-requests>=2.31.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ChrisBg/scientific-content-agent-interface"
+Repository = "https://github.com/ChrisBg/scientific-content-agent-interface"
+"Bug Tracker" = "https://github.com/ChrisBg/scientific-content-agent-interface/issues"
+"Hugging Face Space" = "https://huggingface.co/spaces/Chris30/scientific-content-agent"
+
+[project.scripts]
+scientific-content-agent = "main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+# Ruff configuration
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+exclude = [
+    ".git",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "output",
+    "logs",
+    ".pytest_cache",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "ARG", # flake8-unused-arguments
+    "SIM", # flake8-simplify
+]
+ignore = [
+    "E501",  # line too long (handled by formatter)
+    "B008",  # do not perform function calls in argument defaults
+    "B905",  # zip without strict parameter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]  # unused imports
+"tests/**/*.py" = ["ARG"]  # unused arguments in tests
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+# Mypy configuration
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = true
+disallow_untyped_decorators = false
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+strict_equality = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = [
+    "google.adk.*",
+    "google.genai.*",
+    "duckduckgo_search.*",
+]
+ignore_missing_imports = true
+
+# Pytest configuration
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--strict-markers",
+    "--tb=short",
+    "--cov=src",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+    "--cov-report=xml",
+]
+asyncio_mode = "auto"
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+    "unit: marks tests as unit tests",
+]
+
+# Coverage configuration
+[tool.coverage.run]
+source = ["src"]
+omit = [
+    "*/tests/*",
+    "*/__pycache__/*",
+    "*/site-packages/*",
+]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]

tests/test_tools.py

@@ -0,0 +1,166 @@
+"""Unit tests for custom tools."""
+
+import pytest
+
+from src.tools import (
+    analyze_content_for_opportunities,
+    create_engagement_hooks,
+    extract_key_findings,
+    format_for_platform,
+    generate_citations,
+    generate_seo_keywords,
+    search_industry_trends,
+)
+
+
+class TestFormatForPlatform:
+    """Tests for format_for_platform tool."""
+
+    @pytest.mark.unit
+    def test_format_blog(self):
+        """Test blog formatting."""
+        result = format_for_platform("Test content", "blog", "AI Research")
+        assert result["status"] == "success"
+        assert result["platform"] == "blog"
+        assert "markdown" in result["metadata"]["format"]
+        assert "AI Research" in result["formatted_content"]
+
+    @pytest.mark.unit
+    def test_format_linkedin(self):
+        """Test LinkedIn formatting."""
+        result = format_for_platform("Test content", "linkedin", "ML Topic")
+        assert result["status"] == "success"
+        assert result["platform"] == "linkedin"
+        assert "Key Takeaways" in result["formatted_content"]
+
+    @pytest.mark.unit
+    def test_format_twitter(self):
+        """Test Twitter formatting."""
+        result = format_for_platform("Test content", "twitter", "AI News")
+        assert result["status"] == "success"
+        assert result["platform"] == "twitter"
+        assert "Thread" in result["formatted_content"]
+
+    @pytest.mark.unit
+    def test_invalid_platform(self):
+        """Test invalid platform error."""
+        result = format_for_platform("Test content", "invalid", "Topic")
+        assert result["status"] == "error"
+        assert "Unsupported platform" in result["error_message"]
+
+
+class TestGenerateCitations:
+    """Tests for generate_citations tool."""
+
+    @pytest.mark.unit
+    def test_apa_citations(self):
+        """Test APA citation generation."""
+        sources = [
+            {
+                "title": "Test Paper",
+                "authors": "Smith, J.",
+                "link": "https://arxiv.org/abs/123",
+                "year": "2024",
+            }
+        ]
+        result = generate_citations(sources, "apa")
+        assert result["status"] == "success"
+        assert len(result["citations"]) == 1
+        assert "Smith, J." in result["citations"][0]
+        assert "(2024)" in result["citations"][0]
+
+    @pytest.mark.unit
+    def test_empty_sources(self):
+        """Test error with no sources."""
+        result = generate_citations([])
+        assert result["status"] == "error"
+
+
+class TestExtractKeyFindings:
+    """Tests for extract_key_findings tool."""
+
+    @pytest.mark.unit
+    def test_extract_findings(self):
+        """Test key findings extraction."""
+        text = "Research found that AI improves efficiency. Studies showed significant results."
+        result = extract_key_findings(text, max_findings=2)
+        assert result["status"] == "success"
+        assert len(result["findings"]) <= 2
+
+    @pytest.mark.unit
+    def test_insufficient_text(self):
+        """Test error with short text."""
+        result = extract_key_findings("Too short", max_findings=5)
+        assert result["status"] == "error"
+
+
+class TestGenerateSeoKeywords:
+    """Tests for generate_seo_keywords tool."""
+
+    @pytest.mark.unit
+    def test_keyword_generation(self):
+        """Test SEO keyword generation."""
+        result = generate_seo_keywords("Machine Learning", "AI Consultant")
+        assert result["status"] == "success"
+        assert len(result["primary_keywords"]) > 0
+        assert len(result["technical_keywords"]) > 0
+        assert "AI Consultant" in result["primary_keywords"]
+
+
+class TestCreateEngagementHooks:
+    """Tests for create_engagement_hooks tool."""
+
+    @pytest.mark.unit
+    def test_opportunities_goal(self):
+        """Test hooks for opportunities goal."""
+        result = create_engagement_hooks("AI Agents", "opportunities")
+        assert result["status"] == "success"
+        assert len(result["opening_hooks"]) > 0
+        assert len(result["closing_ctas"]) > 0
+        assert result["goal"] == "opportunities"
+
+    @pytest.mark.unit
+    def test_discussion_goal(self):
+        """Test hooks for discussion goal."""
+        result = create_engagement_hooks("NLP", "discussion")
+        assert result["status"] == "success"
+        assert len(result["discussion_questions"]) > 0
+
+
+class TestAnalyzeContentForOpportunities:
+    """Tests for analyze_content_for_opportunities tool."""
+
+    @pytest.mark.unit
+    def test_content_analysis(self):
+        """Test content opportunity analysis."""
+        content = """
+        As an AI Consultant specializing in Machine Learning, I've built production systems
+        using PyTorch and TensorFlow. Let's connect to discuss how AI can solve your business problems.
+        Check out my GitHub for real-world implementations.
+        """
+        result = analyze_content_for_opportunities(content, "AI Consultant")
+        assert result["status"] == "success"
+        assert "opportunity_score" in result
+        assert "seo_score" in result
+        assert "engagement_score" in result
+        assert 0 <= result["opportunity_score"] <= 100
+
+    @pytest.mark.unit
+    def test_short_content_error(self):
+        """Test error with too short content."""
+        result = analyze_content_for_opportunities("Too short")
+        assert result["status"] == "error"
+
+
+class TestSearchIndustryTrends:
+    """Tests for search_industry_trends tool."""
+
+    @pytest.mark.integration
+    @pytest.mark.slow
+    def test_trend_search(self):
+        """Test industry trend search (requires internet)."""
+        result = search_industry_trends("Machine Learning", "global", max_results=3)
+        assert result["status"] == "success"
+        assert "trends" in result
+        assert "hot_skills" in result
+        assert len(result["hot_skills"]) > 0