README_DEV.md

Developer Guide

This guide covers local development setup for the Scientific Content Agent project.

Prerequisites

• Python 3.11 or higher
• uv package manager
• Git

Quick Start

# Clone the repository
git clone https://github.com/ChrisBg/scientific-content-agent-interface.git
cd scientific-content-agent-interface

# Setup everything (create venv + install dependencies)
make setup

# Activate the virtual environment
source .venv/bin/activate

# Create your .env file
cp .env.example .env
# Add your GOOGLE_API_KEY to .env

# Run the Gradio UI
make run-ui

# Or run the CLI
make run-cli TOPIC="Your research topic"

Available Make Commands

Setup & Installation

make setup          # Complete setup (venv + dependencies)
make venv           # Create uv virtual environment
make install        # Install production dependencies
make install-dev    # Install development dependencies
make update         # Update all dependencies

Running the Application

make run            # Run Gradio UI (default)
make run-ui         # Run Gradio web interface
make run-cli        # Run CLI (add TOPIC="..." for custom topic)
make run-session    # Resume session (requires SESSION_ID=...)

Profile Management

make profile-init       # Initialize default profile
make profile-edit       # Edit profile interactively
make profile-validate   # Validate current profile

Session Management

make sessions-list      # List all sessions
make session-delete     # Delete session (requires SESSION_ID=...)

Testing

make test               # Run all tests
make test-unit          # Run unit tests only
make test-integration   # Run integration tests only
make test-fast          # Run tests without slow tests
make test-cov           # Run tests with coverage report

Code Quality

make lint               # Run ruff linter
make lint-fix           # Run ruff and auto-fix issues
make format             # Format code with ruff
make type-check         # Run mypy type checker
make check              # Run lint + type-check + fast tests
make all                # Format + lint + type-check + test

Development Workflow

make dev                # Format and lint code
make pre-commit         # Pre-commit checks (recommended before commit)
make ci                 # CI checks (lint + type-check + test with coverage)

Deployment

make deploy-github MSG="commit message"    # Deploy to GitHub
make deploy-hf MSG="commit message"        # Deploy to Hugging Face
make deploy-both MSG="commit message"      # Deploy to both

Cleaning

make clean              # Clean build artifacts and cache
make clean-all          # Clean everything including venv

Project Structure

scientific-content-agent/
├── src/                    # Source code
│   ├── agents.py          # Agent definitions
│   ├── tools.py           # Custom tools
│   ├── config.py          # Configuration
│   ├── profile.py         # User profile management
│   └── session_manager.py # Session persistence
├── tests/                  # Test suite
│   └── test_tools.py      # Tool tests
├── app.py                  # HF Spaces entry point
├── main.py                 # CLI entry point
├── ui_app.py               # Gradio UI
├── pyproject.toml          # Project configuration
├── Makefile                # Development commands
├── CLAUDE.md               # Claude Code documentation
└── README.md               # User-facing README

Development Workflow

1. Create a feature branch

   git checkout -b feature/my-feature
   

2. Make your changes

   • Edit code in src/
   • Add tests in tests/

3. Format and lint

   make dev
   

4. Run tests

   make test
   

5. Pre-commit checks

   make pre-commit
   

6. Commit and push

   git add .
   git commit -m "Your message"
   git push origin feature/my-feature
   

Running Tests

Unit Tests

# Run all unit tests
make test-unit

# Run specific test file
uv run pytest tests/test_tools.py

# Run specific test
uv run pytest tests/test_tools.py::TestFormatForPlatform::test_format_blog

Integration Tests

# Run all integration tests (requires internet)
make test-integration

With Coverage

make test-cov
# View HTML report: open htmlcov/index.html

Code Quality Tools

Ruff (Linter + Formatter)

# Check code
make lint

# Auto-fix issues
make lint-fix

# Format code
make format

Mypy (Type Checker)

make type-check

Environment Variables

Create a .env file with:

GOOGLE_API_KEY=your_api_key_here
GOOGLE_GENAI_USE_VERTEXAI=FALSE

Get your API key from: https://aistudio.google.com/app/api_keys

Troubleshooting

Virtual environment issues

make clean-all
make setup

Dependency conflicts

make update

Test failures

# Run tests with verbose output
uv run pytest -vv

# Run with debugging
uv run pytest --pdb

Contributing

1. Fork the repository
2. Create your feature branch
3. Make changes and add tests
4. Run make pre-commit to ensure quality
5. Push to your fork
6. Create a Pull Request

CI/CD

The project uses:

• GitHub: Source code repository
• Hugging Face Spaces: Live demo deployment

Both remotes are configured:

• github: https://github.com/ChrisBg/scientific-content-agent-interface
• origin: https://huggingface.co/spaces/Chris30/scientific-content-agent

Use make deploy-both MSG="message" to deploy to both.

Resources

• uv documentation
• Ruff documentation
• pytest documentation
• Google ADK documentation
• Gradio documentation