# 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

```
osm-pt-geojson  - Fetch a public transport route relation, list stops, export GeoJSON
README.md       - User-facing documentation
AGENTS.md       - This file
```

New tools are added as individual scripts at the repo root.

## Code conventions

- Python 3, shebang `#!/usr/bin/python3`
- 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
- Scripts have no `.py` extension and are executable
- 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 scripts use type hints. Run mypy in strict mode to check:

```
mypy --strict osm-pt-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.

Because tool scripts have hyphens in their names and no `.py` extension, they
cannot be imported with the normal `importlib.util.spec_from_file_location`.
Use `importlib.machinery.SourceFileLoader` instead:

```python
import importlib.machinery
import importlib.util

_loader = importlib.machinery.SourceFileLoader("osm_pt_geojson", "osm-pt-geojson")
_spec = importlib.util.spec_from_loader("osm_pt_geojson", _loader)
assert _spec
osm = importlib.util.module_from_spec(_spec)
_loader.exec_module(osm)
```

### Example relations used during development

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

## Dependencies

Install with pip:

```
pip install click requests
```