# AGENTS.md

Guidelines for AI coding agents working in this repository.

## Project overview

A collection of Python CLI tools for working with OpenStreetMap data. Each
tool is a standalone Python script using Click for the CLI interface and
Requests for HTTP calls.

## Repository layout

```
pyproject.toml              - Package metadata and build configuration
src/
  osm_geojson/
    __init__.py             - Top-level package marker
    pt/
      __init__.py           - Public transport subpackage
      core.py               - Data fetching and processing functions
      cli.py                - Click CLI commands
tests/
  fixtures/                 - Saved OSM API responses for offline testing
  test_osm_pt_geojson.py    - Test suite
README.md                   - User-facing documentation
AGENTS.md                   - This file
```

`osm_geojson` is the top-level namespace for all tools in this collection. Each
tool lives in its own subpackage (e.g. `osm_geojson.pt`), with its CLI entry
point registered in `pyproject.toml` under `[project.scripts]`.

## Code conventions

- Python 3.11+
- CLI via [Click](https://click.palletsprojects.com/)
- HTTP via [Requests](https://requests.readthedocs.io/)
- Parse XML with lxml if needed; prefer the OSM JSON API where possible
- Errors go to stderr; data output goes to stdout
- GeoJSON output uses `ensure_ascii=False`
- All modules, functions, and test functions must have docstrings

## OSM API

Tools fetch data from the public OSM API:

```
https://www.openstreetmap.org/api/0.6/
```

No authentication is required for read-only access. Include a descriptive
`User-Agent` header in all requests.

## Type checking

All code uses type hints. Run mypy in strict mode to check:

```
mypy --strict src/osm_geojson/
```

## Testing

Run the test suite with:

```
pytest tests/
```

Tests use the `responses` library to mock HTTP calls and never hit the live OSM
API. Fixture data is stored in `tests/fixtures/` as saved API responses.

### Example relations used during development

| ID       | Description                             |
|----------|------------------------------------------|
| 15083963 | M11 Istanbul Metro (subway)              |
| 18892969 | Bus A1: Bristol Airport → Bus Station    |

## Dependencies

Use a virtual environment. Install the package and test dependencies with:

```
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
```