Metadata-Version: 2.5
Name: alpin-api
Version: 1.0.0
Summary: Deterministic forum scraping for Alpine ski-resort updates
Author: Michael Medek
License: MIT License
        
        Copyright (c) 2026 Michael Medek
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: curl-cffi>=0.13
Requires-Dist: requests>=2.32
Requires-Dist: tqdm>=4.67
Provides-Extra: tracker
Requires-Dist: groq>=0.31; extra == 'tracker'
Description-Content-Type: text/markdown

# alpin-api

Every night, this project turns posts from dedicated Alpine ski-resort forum topics into a public GeoJSON map of the latest construction and infrastructure progress.

[View the live interactive map](https://michaelmedek.github.io/alpin-api/)

## Install the package for developers

Requires Python 3.11+, Docker, internet, and a Funiforum account. macOS setup with [Homebrew](https://brew.sh):

```shell
# Install the required tools and start the local Docker environment.
brew install python@3.11 colima docker
colima start --vm-type vz --cpu 2 --memory 4 --disk 20

# Create and activate a virtual environment, then install alpin-api.
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install alpin-api
```

### Start the forum services

Alpinforum uses HTTP; Alpinfans and Remontées Mécaniques need FlareSolverr (:8191), Funiforum the browser solver (:8194).

```shell
# Stop the service setup immediately if any command fails.
set -e

# Start FlareSolverr for the forums that require browser-aware HTTP requests.
docker run -d --name flaresolverr --restart unless-stopped -p 127.0.0.1:8191:8191 -e BROWSER_WAIT_TIMEOUT=5 ghcr.io/flaresolverr/flaresolverr@sha256:c80ae007ce2ccdcd217a12426e4f039ef763ff90738c808d38810c3e59323767

# Export the credentials required by the Funiforum solver and Python client.
export FUNIFORUM_USER='your-forum-user'
export FUNIFORUM_PASSWORD='your-forum-password'

# Build and start the authenticated Funiforum browser solver.
docker build -t alpin-api-funisolver:local "$(alpin-api-funisolver-context)"
docker run -d --name funisolver --restart unless-stopped --cap-drop=ALL --security-opt no-new-privileges:true --shm-size=2g -p 127.0.0.1:8194:8194 -e FUNIFORUM_USER -e FUNIFORUM_PASSWORD alpin-api-funisolver:local
```

Wait until `docker logs funisolver` shows `Running on`, then verify; health waits for authentication:

```shell
# Stop the verification immediately if any check fails.
set -e

# Verify that both local forum services are ready.
curl -fsS --max-time 5 http://localhost:8191/
curl -fsS --max-time 125 http://localhost:8194/health
```

Keep credentials exported in Python and Docker. Initialization warns and retains unavailable forums. Skip unavailable sources; return remaining sources without extra warnings, or an empty list and one resort warning if none remain. Invalid resort/forum assignments fail before traffic. Restore prerequisites and recreate `AlpinAPI`.

After reboot: `colima start`, `docker start flaresolverr funisolver`, `source .venv/bin/activate`; export both credentials. Recreate Funiforum's container if credentials change. Repeat the checks.

### Use the API

Compose source discovery and ordered matching, then run the complete resort-post pipeline. Start with exact registry matching over one bounded construction source:

<!-- BEGIN DOCSTRING EXAMPLE: ResortPostPipeline.run -->

```python
# Registry-only pipeline using one bounded live source.
from alpin_api import (
    AlpinAPI, AlpinforumSources, FORUM_TOPICS, Forum, SKI_RESORTS,
    MatcherPipeline, RegistryMatcher, ResortPostPipeline, SourcePipeline,
)

# Configure discovery and exact matching directly at the composed entry point.
posts = ResortPostPipeline(
    api=AlpinAPI(),
    source_pipeline=SourcePipeline(
        # One Austrian construction board and five topics keep this live example bounded.
        sources={Forum.ALPINFORUM: (AlpinforumSources.CONSTRUCTION[1],)},
        topic_limit=5,
        hours_old_max=24.0,
    ),
    matcher_pipeline=MatcherPipeline(
        ski_resorts=SKI_RESORTS,
        # Exact registry matching requires no language-model provider.
        matchers=[RegistryMatcher(forum_topics=FORUM_TOPICS)],
    ),
).run()
```

<!-- END DOCSTRING EXAMPLE: ResortPostPipeline.run -->

For unmapped topics, use an LLM matcher. This independent example keeps the live request to one country-scoped LMM batch:

<!-- BEGIN DOCSTRING EXAMPLE: ResortPostPipeline.run -->

```python
# LLM-only pipeline using one small country-scoped source batch.
from alpin_api import (
    AlpinAPI, AlpinfansSources, Forum, LLMGroqBackend, LLMMatcher,
    MatcherPipeline, ResortPostPipeline, SKI_RESORTS, SourcePipeline,
)

# Inline the bounded live source and the LLM-only matcher pipeline.
posts = ResortPostPipeline(
    api=AlpinAPI(),
    source_pipeline=SourcePipeline(
        # Three topics from one Austrian board produce at most one country-scoped Groq batch.
        sources={Forum.ALPINFANS: (AlpinfansSources.CONSTRUCTION[1],)},
        topic_limit=3,
        hours_old_max=24.0,
    ),
    matcher_pipeline=MatcherPipeline(
        ski_resorts=SKI_RESORTS,
        # Without RegistryMatcher, every discovered topic reaches the LLM matcher.
        matchers=[
            LLMMatcher(
                backend=LLMGroqBackend(
                    model="openai/gpt-oss-120b",
                    reasoning_effort="medium",
                    api_key=None,
                    # The schema is global; LLMMatcher narrows this call to Austrian resorts.
                    response_format=LLMMatcher.response_format(ski_resorts=SKI_RESORTS),
                    max_completion_tokens=16_384,
                )
            )
        ],
    ),
).run()
```

<!-- END DOCSTRING EXAMPLE: ResortPostPipeline.run -->

Discover topics from one explicit forum source:

<!-- BEGIN DOCSTRING EXAMPLE: AlpinAPI.fetch_source_topics -->

```python
from alpin_api import AlpinAPI, AlpinforumSources, Forum

topics = AlpinAPI().fetch_source_topics(
    forum=Forum.ALPINFORUM,
    source_identifier=AlpinforumSources.ACTIVE[0],
    topic_limit=20,
    hours_old_max=24.0,
)
```

<!-- END DOCSTRING EXAMPLE: AlpinAPI.fetch_source_topics -->

Fetch posts from one explicit topic:

<!-- BEGIN DOCSTRING EXAMPLE: AlpinAPI.fetch_topic_posts -->

```python
from alpin_api import AlpinAPI, Forum, ForumTopicListing

posts = AlpinAPI().fetch_topic_posts(
    forum=Forum.ALPINFORUM,
    topic_identifier=ForumTopicListing.from_id(topic_id=285),
    hours_old_max=72.0,
)
```

<!-- END DOCSTRING EXAMPLE: AlpinAPI.fetch_topic_posts -->

All timestamps are UTC. Topic retrieval reads at most the newest two pages. Each source call applies its topic limit before its age filter. ResortPostPipeline deduplicates overlapping source topics, runs matchers in order, fetches each routed topic once, and returns every configured resort key.

Combine RegistryMatcher followed by LLMMatcher when only still-unmatched topics should reach the LLM matcher. LLM matching requires GROQ_API_KEY and the tracker extra.

## Install and test the repo from source

On macOS with [Homebrew](https://brew.sh), install tools and clone:

```shell
# Install the development tools and clone the repository.
brew install git uv node colima docker
git clone https://github.com/MichaelMedek/alpin-api.git

# Enter the checkout, install dependencies, and enable pre-commit.
cd alpin-api
uv sync --extra tracker
uv run --extra tracker pre-commit install

# Start the local Docker environment.
colima start --vm-type vz --cpu 2 --memory 4 --disk 20
```

Select `.venv/bin/python` in VS Code. Configure and start services:

```shell
# Export the API key and forum credentials required by the full test suite.
export GROQ_API_KEY='your-groq-key'
export FUNIFORUM_USER='your-forum-user'
export FUNIFORUM_PASSWORD='your-forum-password'

# Start FlareSolverr for its live forum regressions.
docker run -d --name flaresolverr --restart unless-stopped -p 127.0.0.1:8191:8191 -e BROWSER_WAIT_TIMEOUT=5 ghcr.io/flaresolverr/flaresolverr@sha256:c80ae007ce2ccdcd217a12426e4f039ef763ff90738c808d38810c3e59323767

# Build and start the authenticated Funiforum browser solver.
docker build -t alpin-api-funisolver:local src/alpin_api/_funisolver
docker run -d --name funisolver --restart unless-stopped --cap-drop=ALL --security-opt no-new-privileges:true --shm-size=2g -p 127.0.0.1:8194:8194 -e FUNIFORUM_USER -e FUNIFORUM_PASSWORD alpin-api-funisolver:local
```

Wait until `docker logs funisolver` shows `Running on`, then verify; health waits for authentication:

```shell
# Verify that both local forum services are ready.
curl -fsS --max-time 5 http://localhost:8191/
curl -fsS --max-time 125 http://localhost:8194/health

# Run the complete test suite.
uv run --extra tracker pytest --exitfirst

# Run repository checks and build the release distributions.
uv run --extra tracker pre-commit run --all-files
uv build

# Run the live tracker locally to create a run directory and rewrite map.geojson.
uv run --extra tracker --no-dev python main.py
```

A passing full run covers all four forums and Groq without skips. After reboot, start Colima and both containers, export all three credentials, and repeat the health checks.

Topic inference requires `GROQ_API_KEY` and `pip install 'alpin-api[tracker]'`. Exact registry mappings remain authoritative and need neither.
