etter 0.1.1__tar.gz

etter-0.1.1/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026-present, camptocamp SA
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

etter-0.1.1/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: etter
+Version: 0.1.1
+Summary: Natural language geographic query parsing using LLMs
+Author: etter contributors
+License: BSD-3-Clause
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain>=1.2
+Requires-Dist: pydantic>=2.12
+Requires-Dist: shapely>=2.1
+Requires-Dist: pyproj>=3.7
+Requires-Dist: geopandas>=1.1
+Requires-Dist: rapidfuzz>=3.14
+Provides-Extra: postgis
+Requires-Dist: sqlalchemy>=2.0; extra == "postgis"
+Requires-Dist: geoalchemy2>=0.15; extra == "postgis"
+Provides-Extra: dev
+Requires-Dist: langchain-openai>=1.1.14; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Requires-Dist: ty>=0.0.31; extra == "dev"
+Requires-Dist: pdoc>=14.0; extra == "dev"
+Requires-Dist: fastapi>=0.135; extra == "dev"
+Requires-Dist: python-dotenv>=1.2; extra == "dev"
+Requires-Dist: uvicorn>=0.44.0; extra == "dev"
+Requires-Dist: mcp[cli]>=1.27.0; extra == "dev"
+Requires-Dist: rich>=15.0.0; extra == "dev"
+Requires-Dist: testcontainers[postgres]>=4.14.2; extra == "dev"
+Requires-Dist: psycopg2-binary>=2.9; extra == "dev"
+Requires-Dist: etter[postgis]; extra == "dev"
+Dynamic: license-file
+
+![etter logo](./images/etter-logo.png)
+
+> **[etter](https://en.wiktionary.org/wiki/Etter#German)** /ˈɛtɐ/ *n.* (Swiss German) — the boundary or enclosure marking the edge of a village or commune; a natural demarcation between settled and unsettled land.
+
+Natural language geographic query parsing using LLMs.
+
+## Overview
+
+etter transforms natural language location queries into structured geographic filters that can be used by search engines and spatial databases.
+It uses Large Language Models (LLMs) to understand multilingual queries and extract spatial relationships.
+
+**Key Principle:** etter's sole purpose is to extract the **geographic filter** from user queries. It does NOT handle feature/activity identification or search execution.
+
+> [!TIP]
+> Documentation available at [https://geoblocks.github.io/etter/](https://geoblocks.github.io/etter/)
+
+## Sponsorship
+
+[![camptocamp logo](./images/camptocamp-logo.png)](https://www.camptocamp.com)
+
+The development of this library is sponsored by [Camptocamp](https://www.camptocamp.com).
+
+## Features
+
+- **Geographic Filters Only**: Extracts spatial relationships from queries, ignoring non-geographic content
+- **Multilingual Support**: Parse queries in English, German, French, Italian, and more
+- **Rich Spatial Relations**: Support for containment, buffer, and directional queries
+- **Structured Output**: Pydantic models with full type safety
+- **Streaming Support**: Real-time feedback with reasoning transparency for responsive UIs
+- **Flexible Configuration**: Customizable spatial relations and confidence thresholds
+- **LLM Provider Agnostic**: Works with OpenAI, Anthropic, or local models
+
+## What etter Does (and Doesn't Do)
+
+**✅ etter extracts:**
+
+- Spatial relations: "north of", "in", "near", etc.
+- Reference locations: "Lausanne", "Lake Geneva", etc.
+- Distance parameters: "within 5km", "around 2 miles", etc.
+
+**❌ etter does NOT handle:**
+
+- Feature/activity identification: "hiking", "restaurants", "hotels"
+- Attribute filtering: "with children", "vegetarian", "4-star"
+- Search execution or database queries
+
+**Integration Pattern:**
+Parent application handles feature/activity filtering and combines it with etter's geographic filter for complete search functionality.
+
+## Installation
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+# Install dependencies
+uv sync
+
+# Or with development dependencies
+uv sync --extra dev
+```
+
+## REPL
+
+An interactive REPL is available for testing queries interactively:
+
+Set your OpenAI API key before running:
+
+```bash
+export OPENAI_API_KEY='sk-...'
+uv run python repl.py
+```
+
+## Demo API Server
+
+A FastAPI demo server is available that combines query parsing with geographic resolution using SwissNames3D data.
+
+**Setup:**
+
+Set `OPENAI_API_KEY` in your `.env` file:
+
+```bash
+echo "OPENAI_API_KEY=sk-..." > .env
+```
+
+**Running the server:**
+
+```bash
+uv run uvicorn demo.main:app --port 8000 --reload
+```
+
+The API will be available at `http://localhost:8000`.
+
+**Making a query:**
+
+```bash
+# Standard endpoint (returns complete result)
+curl -X POST http://localhost:8000/api/query \
+  -H "Content-Type: application/json" \
+  -d '{"query": "north of Lausanne"}'
+
+# Streaming endpoint (returns Server-Sent Events)
+curl -X POST http://localhost:8000/api/query/stream \
+  -H "Content-Type: application/json" \
+  -d '{"query": "north of Lausanne"}' \
+  --no-buffer
+```
+
+Response: A GeoJSON FeatureCollection containing the parsed geographic query, spatial relation, and computed search areas.
+
+The web UI at `http://localhost:8000` includes a toggle to enable streaming mode with real-time reasoning display.
+
+## Quick Start
+
+```python
+from langchain_openai import ChatOpenAI
+from etter import GeoFilterParser
+import os
+
+# Initialize LLM
+llm = ChatOpenAI(
+    model="gpt-4o",
+    temperature=0,
+    api_key=os.getenv("OPENAI_API_KEY")
+)
+
+# Initialize parser
+parser = GeoFilterParser(
+    llm=llm,
+    confidence_threshold=0.6,
+    strict_mode=False
+)
+
+# Strict mode - raises error on low confidence
+parser = GeoFilterParser(
+    llm=llm,
+    confidence_threshold=0.8,
+    strict_mode=True
+)
+```
+
+### Custom Spatial Relations
+
+```python
+from etter import SpatialRelationConfig, RelationConfig
+
+config = SpatialRelationConfig()
+config.register_relation(RelationConfig(
+    name="close_to",
+    category="buffer",
+    description="Very close proximity",
+    default_distance_m=1000,
+    buffer_from="center"
+))
+
+parser = GeoFilterParser(spatial_config=config)
+```
+
+## API Reference
+
+### GeoFilterParser
+
+Main class for parsing queries.
+
+**Methods:**
+
+- `parse(query: str) -> GeoQuery`: Parse a single query
+- `parse_stream(query: str) -> AsyncGenerator[dict]`: Parse with streaming events
+- `parse_batch(queries: List[str]) -> List[GeoQuery]`: Parse multiple queries
+- `get_available_relations(category: Optional[str]) -> List[str]`: List available relations
+- `describe_relation(name: str) -> str`: Get relation description
+
+### GeoQuery
+
+Structured output model representing the parsed geographic filter.
+
+**Attributes:**
+
+- `query_type`: Type of query (simple, compound, split, boolean)
+- `spatial_relation`: Spatial relationship (e.g., "north_of", "in", "near")
+- `reference_location`: Reference location (e.g., "Lausanne")
+- `buffer_config`: Buffer parameters (optional)
+- `confidence_breakdown`: Confidence scores
+- `original_query`: Original input text
+
+**Note:** etter is fully implemented with three integrated layers: parsing, geographic resolution via datasources, and spatial operations. The demo API shows a complete end-to-end workflow that resolves locations and computes search areas.
+
+## Available Spatial Relations
+
+### Containment
+
+- `in`: Exact boundary matching
+
+### Buffer/Proximity
+
+- `near`: Proximity with context-aware distance (default 5km, LLM infers based on activity, feature scale, and intent)
+- `on_shores_of`: 1km ring buffer (excludes water body)
+- `along`: 500m buffer for linear features
+- `left_bank`, `right_bank`: Buffer on one side of a linear feature (river, road) relative to its flow direction
+- `in_the_heart_of`: Erosion for central areas (default -500m, LLM infers based on area size)
+
+### Directional
+
+- **Cardinal**: `north_of`, `south_of`, `east_of`, `west_of`: 10km sector (90° each)
+- **Diagonal**: `northeast_of`, `southeast_of`, `southwest_of`, `northwest_of`: 10km sector (90° each)
+
+## Error Handling
+
+```python
+from etter import ParsingError, UnknownRelationError, LowConfidenceError
+
+try:
+    result = parser.parse("some query")
+except ParsingError as e:
+    print(f"Failed to parse: {e}")
+    print(f"Raw LLM response: {e.raw_response}")
+except UnknownRelationError as e:
+    print(f"Unknown relation: {e.relation_name}")
+except LowConfidenceError as e:
+    print(f"Low confidence: {e.confidence}")
+    print(f"Reasoning: {e.reasoning}")
+```
+
+## Demo Examples
+
+Here are some good example queries to try with the demo application:
+
+- `walk in the Gros-de-Vaud`
+- `on the shores of the lac Morat`
+- `near Lausanne`
+- `south west of Lausanne`
+- `5km north of Lausanne`
+- `walking distance from Zurich main railway station`
+- `15 min biking from Zurich main railway station`
+- `along l'Orbe`
+- `2km right bank of the Rhône`
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed system design.
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync --extra dev
+
+# Run tests
+uv run pytest
+
+# Format code
+uv run ruff format
+
+# Linting
+uv run ruff check
+
+# Type checking
+uv run ty check
+```

etter-0.1.1/README.md

@@ -0,0 +1,258 @@
+![etter logo](./images/etter-logo.png)
+
+> **[etter](https://en.wiktionary.org/wiki/Etter#German)** /ˈɛtɐ/ *n.* (Swiss German) — the boundary or enclosure marking the edge of a village or commune; a natural demarcation between settled and unsettled land.
+
+Natural language geographic query parsing using LLMs.
+
+## Overview
+
+etter transforms natural language location queries into structured geographic filters that can be used by search engines and spatial databases.
+It uses Large Language Models (LLMs) to understand multilingual queries and extract spatial relationships.
+
+**Key Principle:** etter's sole purpose is to extract the **geographic filter** from user queries. It does NOT handle feature/activity identification or search execution.
+
+> [!TIP]
+> Documentation available at [https://geoblocks.github.io/etter/](https://geoblocks.github.io/etter/)
+
+## Sponsorship
+
+[![camptocamp logo](./images/camptocamp-logo.png)](https://www.camptocamp.com)
+
+The development of this library is sponsored by [Camptocamp](https://www.camptocamp.com).
+
+## Features
+
+- **Geographic Filters Only**: Extracts spatial relationships from queries, ignoring non-geographic content
+- **Multilingual Support**: Parse queries in English, German, French, Italian, and more
+- **Rich Spatial Relations**: Support for containment, buffer, and directional queries
+- **Structured Output**: Pydantic models with full type safety
+- **Streaming Support**: Real-time feedback with reasoning transparency for responsive UIs
+- **Flexible Configuration**: Customizable spatial relations and confidence thresholds
+- **LLM Provider Agnostic**: Works with OpenAI, Anthropic, or local models
+
+## What etter Does (and Doesn't Do)
+
+**✅ etter extracts:**
+
+- Spatial relations: "north of", "in", "near", etc.
+- Reference locations: "Lausanne", "Lake Geneva", etc.
+- Distance parameters: "within 5km", "around 2 miles", etc.
+
+**❌ etter does NOT handle:**
+
+- Feature/activity identification: "hiking", "restaurants", "hotels"
+- Attribute filtering: "with children", "vegetarian", "4-star"
+- Search execution or database queries
+
+**Integration Pattern:**
+Parent application handles feature/activity filtering and combines it with etter's geographic filter for complete search functionality.
+
+## Installation
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+# Install dependencies
+uv sync
+
+# Or with development dependencies
+uv sync --extra dev
+```
+
+## REPL
+
+An interactive REPL is available for testing queries interactively:
+
+Set your OpenAI API key before running:
+
+```bash
+export OPENAI_API_KEY='sk-...'
+uv run python repl.py
+```
+
+## Demo API Server
+
+A FastAPI demo server is available that combines query parsing with geographic resolution using SwissNames3D data.
+
+**Setup:**
+
+Set `OPENAI_API_KEY` in your `.env` file:
+
+```bash
+echo "OPENAI_API_KEY=sk-..." > .env
+```
+
+**Running the server:**
+
+```bash
+uv run uvicorn demo.main:app --port 8000 --reload
+```
+
+The API will be available at `http://localhost:8000`.
+
+**Making a query:**
+
+```bash
+# Standard endpoint (returns complete result)
+curl -X POST http://localhost:8000/api/query \
+  -H "Content-Type: application/json" \
+  -d '{"query": "north of Lausanne"}'
+
+# Streaming endpoint (returns Server-Sent Events)
+curl -X POST http://localhost:8000/api/query/stream \
+  -H "Content-Type: application/json" \
+  -d '{"query": "north of Lausanne"}' \
+  --no-buffer
+```
+
+Response: A GeoJSON FeatureCollection containing the parsed geographic query, spatial relation, and computed search areas.
+
+The web UI at `http://localhost:8000` includes a toggle to enable streaming mode with real-time reasoning display.
+
+## Quick Start
+
+```python
+from langchain_openai import ChatOpenAI
+from etter import GeoFilterParser
+import os
+
+# Initialize LLM
+llm = ChatOpenAI(
+    model="gpt-4o",
+    temperature=0,
+    api_key=os.getenv("OPENAI_API_KEY")
+)
+
+# Initialize parser
+parser = GeoFilterParser(
+    llm=llm,
+    confidence_threshold=0.6,
+    strict_mode=False
+)
+
+# Strict mode - raises error on low confidence
+parser = GeoFilterParser(
+    llm=llm,
+    confidence_threshold=0.8,
+    strict_mode=True
+)
+```
+
+### Custom Spatial Relations
+
+```python
+from etter import SpatialRelationConfig, RelationConfig
+
+config = SpatialRelationConfig()
+config.register_relation(RelationConfig(
+    name="close_to",
+    category="buffer",
+    description="Very close proximity",
+    default_distance_m=1000,
+    buffer_from="center"
+))
+
+parser = GeoFilterParser(spatial_config=config)
+```
+
+## API Reference
+
+### GeoFilterParser
+
+Main class for parsing queries.
+
+**Methods:**
+
+- `parse(query: str) -> GeoQuery`: Parse a single query
+- `parse_stream(query: str) -> AsyncGenerator[dict]`: Parse with streaming events
+- `parse_batch(queries: List[str]) -> List[GeoQuery]`: Parse multiple queries
+- `get_available_relations(category: Optional[str]) -> List[str]`: List available relations
+- `describe_relation(name: str) -> str`: Get relation description
+
+### GeoQuery
+
+Structured output model representing the parsed geographic filter.
+
+**Attributes:**
+
+- `query_type`: Type of query (simple, compound, split, boolean)
+- `spatial_relation`: Spatial relationship (e.g., "north_of", "in", "near")
+- `reference_location`: Reference location (e.g., "Lausanne")
+- `buffer_config`: Buffer parameters (optional)
+- `confidence_breakdown`: Confidence scores
+- `original_query`: Original input text
+
+**Note:** etter is fully implemented with three integrated layers: parsing, geographic resolution via datasources, and spatial operations. The demo API shows a complete end-to-end workflow that resolves locations and computes search areas.
+
+## Available Spatial Relations
+
+### Containment
+
+- `in`: Exact boundary matching
+
+### Buffer/Proximity
+
+- `near`: Proximity with context-aware distance (default 5km, LLM infers based on activity, feature scale, and intent)
+- `on_shores_of`: 1km ring buffer (excludes water body)
+- `along`: 500m buffer for linear features
+- `left_bank`, `right_bank`: Buffer on one side of a linear feature (river, road) relative to its flow direction
+- `in_the_heart_of`: Erosion for central areas (default -500m, LLM infers based on area size)
+
+### Directional
+
+- **Cardinal**: `north_of`, `south_of`, `east_of`, `west_of`: 10km sector (90° each)
+- **Diagonal**: `northeast_of`, `southeast_of`, `southwest_of`, `northwest_of`: 10km sector (90° each)
+
+## Error Handling
+
+```python
+from etter import ParsingError, UnknownRelationError, LowConfidenceError
+
+try:
+    result = parser.parse("some query")
+except ParsingError as e:
+    print(f"Failed to parse: {e}")
+    print(f"Raw LLM response: {e.raw_response}")
+except UnknownRelationError as e:
+    print(f"Unknown relation: {e.relation_name}")
+except LowConfidenceError as e:
+    print(f"Low confidence: {e.confidence}")
+    print(f"Reasoning: {e.reasoning}")
+```
+
+## Demo Examples
+
+Here are some good example queries to try with the demo application:
+
+- `walk in the Gros-de-Vaud`
+- `on the shores of the lac Morat`
+- `near Lausanne`
+- `south west of Lausanne`
+- `5km north of Lausanne`
+- `walking distance from Zurich main railway station`
+- `15 min biking from Zurich main railway station`
+- `along l'Orbe`
+- `2km right bank of the Rhône`
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed system design.
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync --extra dev
+
+# Run tests
+uv run pytest
+
+# Format code
+uv run ruff format
+
+# Linting
+uv run ruff check
+
+# Type checking
+uv run ty check
+```

etter-0.1.1/etter/__init__.py

@@ -0,0 +1,72 @@
+"""
+etter - Natural language geographic query parsing using LLMs.
+
+Parse location queries into structured geographic queries using LLM.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("etter")
+except PackageNotFoundError:  # running from source without install
+    __version__ = "unknown"
+
+# Main API
+# Exceptions
+# Datasources
+from .datasources import CompositeDataSource, GeoDataSource, IGNBDCartoSource, PostGISDataSource, SwissNames3DSource
+from .exceptions import (
+    GeoFilterError,
+    LowConfidenceError,
+    LowConfidenceWarning,
+    ParsingError,
+    UnknownRelationError,
+    ValidationError,
+)
+
+# Models (for type hints and result access)
+from .models import (
+    BufferConfig,
+    ConfidenceLevel,
+    ConfidenceScore,
+    GeoQuery,
+    ReferenceLocation,
+    SpatialRelation,
+)
+from .parser import GeoFilterParser
+
+# Spatial operations
+from .spatial import apply_spatial_relation
+
+# Configuration
+from .spatial_config import RelationConfig, SpatialRelationConfig
+
+__all__ = [
+    # Main API
+    "GeoFilterParser",
+    # Models
+    "GeoQuery",
+    "SpatialRelation",
+    "ReferenceLocation",
+    "BufferConfig",
+    "ConfidenceScore",
+    "ConfidenceLevel",
+    # Configuration
+    "SpatialRelationConfig",
+    "RelationConfig",
+    # Exceptions
+    "GeoFilterError",
+    "ParsingError",
+    "ValidationError",
+    "UnknownRelationError",
+    "LowConfidenceError",
+    "LowConfidenceWarning",
+    # Datasources
+    "GeoDataSource",
+    "SwissNames3DSource",
+    "IGNBDCartoSource",
+    "CompositeDataSource",
+    "PostGISDataSource",
+    # Spatial
+    "apply_spatial_relation",
+]

etter-0.1.1/etter/datasources/__init__.py

@@ -0,0 +1,20 @@
+"""
+Geographic data source layer for resolving location names to geometries.
+
+Provides a Protocol-based interface (GeoDataSource) and concrete implementations:
+SwissNames3DSource, IGNBDCartoSource, PostGISDataSource, and CompositeDataSource.
+"""
+
+from .composite import CompositeDataSource
+from .ign_bdcarto import IGNBDCartoSource
+from .postgis import PostGISDataSource
+from .protocol import GeoDataSource
+from .swissnames3d import SwissNames3DSource
+
+__all__ = [
+    "CompositeDataSource",
+    "GeoDataSource",
+    "IGNBDCartoSource",
+    "PostGISDataSource",
+    "SwissNames3DSource",
+]