# Python Quickstart Template

A ready-to-use template for building agentic applications with the GitHub Copilot SDK and Python.

## Features

- ✅ Pre-configured Python setup
- ✅ Example custom tools (calculator, time)
- ✅ Interactive CLI interface
- ✅ Streaming responses
- ✅ Environment variable support
- ✅ Type hints and documentation

## Quick Start

### Option 1: Using venv (Standard)

1. **Create and activate virtual environment:**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

2. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

3. **Create environment file:**
   ```bash
   cp ../../.env.example .env
   ```

4. **Run the application:**
   ```bash
   python src/main.py
   ```

### Option 2: Using uv (Recommended, Faster)

1. **Create and activate virtual environment:**
   ```bash
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

2. **Install dependencies:**
   ```bash
   uv pip install -r requirements.txt
   ```

3. **Create environment file:**
   ```bash
   cp ../../.env.example .env
   ```

4. **Run the application:**
   ```bash
   python src/main.py
   ```

## Project Structure

```
.
├── src/
│   ├── __init__.py    # Package marker
│   └── main.py        # Main application with example tools
├── requirements.txt   # Python dependencies
└── .env               # Environment variables (create from .env.example)
```

## Customization

### Adding Custom Tools

Edit `src/main.py` and add your tool using the `@define_tool` decorator:

```python
@define_tool(description="Description of what your tool does")
async def my_tool(params: dict) -> dict:
    """
    Your tool documentation
    
    Args:
        params: Dictionary with your parameters
    """
    # Your tool logic here
    return {"result": "success"}

# Add to session:
session = await client.create_session({
    "tools": [my_tool, get_time, calculator],
})
```

### Configuring the Model

Set the model in `.env`:

```env
COPILOT_MODEL=gpt-4.1
```

Or modify directly in code:

```python
session = await client.create_session({
    "model": "gpt-4.1",
})
```

## Development

### Installing Development Dependencies

```bash
pip install -r requirements.txt
pip install pytest black ruff mypy  # Optional dev tools
```

### Code Formatting

```bash
black src/
```

### Linting

```bash
ruff check src/
```

### Type Checking

```bash
mypy src/
```

## Next Steps

- Read the [Getting Started Guide](../../../docs/getting-started.md)
- Explore [Cookbook Examples](../../../cookbook/python/)
- Learn about [MCP Servers](https://github.com/modelcontextprotocol/servers)

## Troubleshooting

**Issue:** `copilot: command not found`

**Solution:** Install GitHub Copilot CLI:
```bash
gh extension install github/gh-copilot
```

**Issue:** Import errors

**Solution:** Ensure virtual environment is activated:
```bash
source venv/bin/activate  # or .venv/bin/activate
pip install -r requirements.txt
```

**Issue:** Module not found

**Solution:** Install in development mode:
```bash
pip install -e .
```