README_DEV.md

# Developer Guide

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

## Prerequisites

- Python 3.11 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- Git

## Quick Start

```bash
# 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

```bash
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

```bash
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

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

### Session Management

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

### Testing

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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**
   ```bash
   git checkout -b feature/my-feature
   ```

2. **Make your changes**
   - Edit code in `src/`
   - Add tests in `tests/`

3. **Format and lint**
   ```bash
   make dev
   ```

4. **Run tests**
   ```bash
   make test
   ```

5. **Pre-commit checks**
   ```bash
   make pre-commit
   ```

6. **Commit and push**
   ```bash
   git add .
   git commit -m "Your message"
   git push origin feature/my-feature
   ```

## Running Tests

### Unit Tests
```bash
# 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
```bash
# Run all integration tests (requires internet)
make test-integration
```

### With Coverage
```bash
make test-cov
# View HTML report: open htmlcov/index.html
```

## Code Quality Tools

### Ruff (Linter + Formatter)
```bash
# Check code
make lint

# Auto-fix issues
make lint-fix

# Format code
make format
```

### Mypy (Type Checker)
```bash
make type-check
```

## Environment Variables

Create a `.env` file with:

```bash
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
```bash
make clean-all
make setup
```

### Dependency conflicts
```bash
make update
```

### Test failures
```bash
# 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](https://github.com/astral-sh/uv)
- [Ruff documentation](https://docs.astral.sh/ruff/)
- [pytest documentation](https://docs.pytest.org/)
- [Google ADK documentation](https://github.com/google/adk)
- [Gradio documentation](https://gradio.app/docs)