resolvekit 0.0.1__py3-none-any.whl

resolvekit/README.md

@@ -0,0 +1,134 @@
+# resolvekit Package Structure
+
+This directory contains the main resolvekit package implementation.
+
+## Module Overview
+
+### Core Resolution Pipeline
+
+1. **normalization/** - Text preprocessing and normalization
+   - Unicode normalization (NFKC/NFKD)
+   - Diacritic handling and case folding
+   - Transliteration support
+
+2. **matchers/** - Candidate generation cascade
+   - Exact code matcher (ISO, DCID, etc.)
+   - Canonical name matcher
+   - Alias exact matcher
+   - FTS matcher (SQLite FTS5)
+   - Fuzzy matcher (bounded)
+   - Semantic matcher (optional)
+
+3. **disambiguation/** - Ambiguity resolution
+   - Ambiguity detection
+   - Semantic sidecar (HNSW)
+   - Context analysis
+   - Default heuristics
+
+4. **constraints/** - KG and temporal validation
+   - Type validation
+   - Hierarchy validation
+   - Temporal validity
+   - Membership validation
+
+5. **calibration/** - Confidence scoring
+   - Feature extraction
+   - Calibration models
+   - Score fusion
+
+### Data Management
+
+6. **data/** - Data storage and access
+   - SQLite database management
+   - Schema definitions
+   - Data models and loaders
+   - Query builders
+
+7. **overlays/** - Custom data extensions
+   - Overlay management
+   - Precedence handling
+   - Overlay writers and validators
+
+8. **builders/** - Data pack building
+   - ETL pipelines
+   - Pack builders
+   - Calibration training
+   - Quality assurance
+
+### Interfaces
+
+9. **api/** - Python API
+   - Main Resolver class
+   - Resolution operations
+   - Code conversion
+   - Hierarchy navigation
+
+10. **cli/** - Command-line interface
+    - CLI commands
+    - Output formatters
+    - Interactive prompts
+
+### Additional Features
+
+11. **extraction/** - Entity extraction from text
+    - Dictionary matching
+    - NER assistance
+    - Context extraction
+
+12. **utils/** - Shared utilities
+    - Logging
+    - Validation
+    - Text utilities
+    - Caching
+
+## Key Files
+
+- **types.py** - Type definitions and data classes
+- **constants.py** - Constants and configuration defaults
+- **__init__.py** - Package initialization and exports
+
+## Implementation Status
+
+Current status: **Phase A - Core Resolver** (scaffolding complete)
+
+See `implementation-plan.md` in the repository root for the full implementation roadmap.
+
+## Development Workflow
+
+1. Each module has its own README explaining its purpose and components
+2. Start with Phase A modules: normalization, matchers, data, calibration, api, cli
+3. Follow test-driven development (write tests first)
+4. Maintain type hints and docstrings for all public APIs
+5. Run linting and type checking before commits
+
+## Quick Start for Developers
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests (when available)
+uv run pytest
+
+# Run linting
+uv run ruff check src/resolvekit
+
+# Run type checking
+uv run mypy src/resolvekit
+
+# Run CLI
+uv run resolvekit
+```
+
+## Architecture Principles
+
+1. **Bounded cascade**: Fail-fast with early matchers, limit expensive operations
+2. **Offline-first**: Zero runtime network dependencies
+3. **Explainable**: Return confidence scores and alternatives with reasoning
+4. **Extensible**: Support overlays at data, config, and code levels
+5. **Temporal-aware**: Handle time-varying data from day one
+6. **Type-safe**: Full type annotations throughout
+
+## Next Steps
+
+See individual module READMEs for implementation details and priorities.

resolvekit/__init__.py

@@ -0,0 +1,67 @@
+"""
+resolvekit - An open offline resolver for places and entities.
+
+resolvekit is a local, offline-first entity and place resolution system that maps
+messy place/entity strings and codes to canonical entities with calibrated
+confidence scores.
+"""
+
+from resolvekit.api import Resolver, resolve, resolve_many
+from resolvekit.config import ResolvekitConfig
+from resolvekit.constants import VERSION
+from resolvekit.types import (
+    AliasType,
+    Candidate,
+    CodeSystem,
+    Entity,
+    EntityType,
+    Explanation,
+    ExplanationMode,
+    ExtractedEntity,
+    MatchContext,
+    Membership,
+    OutputFormat,
+    Resolution,
+)
+
+__version__ = VERSION
+
+__all__ = [
+    "VERSION",
+    "AliasType",
+    "Candidate",
+    "CodeSystem",
+    "Entity",
+    "EntityType",
+    "Explanation",
+    "ExplanationMode",
+    "ExtractedEntity",
+    "MatchContext",
+    "Membership",
+    "ResolvekitConfig",
+    "OutputFormat",
+    "Resolution",
+    "Resolver",
+    "__version__",
+    "resolve",
+    "resolve_many",
+]
+
+
+def main() -> None:
+    """CLI entry point."""
+    # Import here to avoid circular imports
+    from resolvekit.cli.main import cli
+
+    cli()
+
+
+# Package metadata
+__author__ = "Jorge Rivera"
+__email__ = "jorge.rivera@one.org"
+__license__ = "MIT"
+__description__ = (
+    "A local, offline-first entity and place resolution system that maps "
+    "messy place/entity strings and codes to canonical entities with "
+    "calibrated confidence scores"
+)

resolvekit/api/README.md

@@ -0,0 +1,165 @@
+# API Module
+
+## Purpose
+
+The API module provides the primary Python programmatic interface for entity resolution, code conversion, and related operations.
+
+## Components
+
+### Core API Classes
+
+1. **Resolver** (`resolver.py`)
+   - Main entry point for all resolution operations
+   - Manages configuration and data pack loading
+   - Orchestrates matchers, constraints, and calibration
+
+2. **Resolution** (`resolution.py`)
+   - Data class representing resolution results
+   - Contains matched entity, alternatives, confidence, explanation
+   - Supports JSON serialization
+
+3. **Config** (`config.py`)
+   - Configuration management
+   - User-provided settings (thresholds, data paths, etc.)
+   - Environment variable support
+
+### API Operations
+
+- `resolve.py`: Single entity resolution
+- `batch.py`: Batch resolution operations
+- `convert.py`: Code system conversion
+- `hierarchy.py`: Hierarchy navigation
+- `extract.py`: Entity extraction from text (Phase F)
+- `membership.py`: Group membership queries
+
+## Primary API: Resolver Class
+
+```python
+from resolvekit.api import Resolver
+from datetime import date
+
+# Initialize resolver
+resolver = Resolver(
+    data_path="/path/to/data/packs",
+    custom_overlays=["custom_aliases.yaml"],
+    min_confidence=0.7
+)
+
+# Single entity resolution
+result = resolver.resolve(
+    "Cote d Ivoire",
+    entity_type=None,
+    parent=None,
+    at=None,
+    context=None,
+    return_alternates=5,
+    explain=False
+)
+
+# Access results
+print(result.entity.dcid)           # "country/CIV"
+print(result.entity.canonical_name)  # "Côte d'Ivoire"
+print(result.confidence)             # 0.95
+print(result.alternatives)           # [Entity, Entity, ...]
+
+# Code conversion
+dcid = resolver.code_to_dcid("FRA", code_type="iso3")
+codes = resolver.dcid_to_codes("country/FRA")
+
+# Batch operations
+import pandas as pd
+df = pd.DataFrame({"location": ["France", "UK", "Türkiye"]})
+results = resolver.resolve_many(df["location"].tolist())
+
+# Temporal queries
+eu_2004 = resolver.get_group_members("EU", as_of=date(2004, 1, 1))
+was_member = resolver.check_membership(
+    "country/POL",
+    group="EU",
+    as_of=date(2003, 12, 31)
+)
+
+# Hierarchy navigation
+children = resolver.get_children("country/FRA", admin_level=1)
+parent = resolver.get_parent("geoId/06")
+path = resolver.get_hierarchy_path("some/admin3/entity")
+```
+
+## Resolution Result Structure
+
+```python
+@dataclass
+class Resolution:
+    """Resolution result."""
+
+    entity: Entity | None          # Primary match
+    confidence: float              # Calibrated probability
+    alternatives: list[Entity]     # Alternative candidates
+    explanation: Explanation | None  # Why this match (if explain=True)
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary."""
+        ...
+
+    def to_json(self) -> str:
+        """Serialize to JSON."""
+        ...
+
+@dataclass
+class Entity:
+    """Resolved entity."""
+
+    dcid: str
+    canonical_name: str
+    entity_type: str
+    codes: dict[str, str]  # {system: code}
+    parent_dcid: str | None
+    valid_from: date | None
+    valid_until: date | None
+
+@dataclass
+class Explanation:
+    """Resolution explanation."""
+
+    stages: list[str]              # Stages executed
+    candidates: list[Candidate]    # All candidates with features
+    rules_applied: list[str]       # Disambiguation rules
+    calibration: dict              # Model details
+```
+
+## Design Principles
+
+1. **Pythonic**: Snake_case, context managers, type hints
+2. **Sensible defaults**: Works out of box without configuration
+3. **Progressive disclosure**: Simple for basic use, powerful for advanced
+4. **Type safety**: Full type annotations for IDE support
+5. **Pandas integration**: Native support for DataFrame operations
+
+## Error Handling
+
+```python
+from resolvekit.api import Resolver, ResolutionError, ConfigError
+
+try:
+    resolver = Resolver()
+except ConfigError as e:
+    # Handle configuration errors
+    print(f"Config error: {e}")
+
+try:
+    result = resolver.resolve("invalid input")
+except ResolutionError as e:
+    # Handle resolution errors
+    print(f"Resolution failed: {e}")
+
+# No match returns None, not exception
+result = resolver.resolve("zzzzzz")
+if result.entity is None:
+    print("No match found")
+```
+
+## Implementation Priority
+
+**Phase A** - Core resolver (Resolver class, resolve, batch)
+**Phase B** - Code conversion and hierarchy APIs
+**Phase F** - Entity extraction

resolvekit/api/__init__.py

@@ -0,0 +1,10 @@
+"""Public Resolver API."""
+
+from resolvekit.api.convenience import resolve, resolve_many
+from resolvekit.api.resolver import Resolver
+
+__all__ = [
+    "Resolver",
+    "resolve",
+    "resolve_many",
+]

resolvekit/api/convenience.py

@@ -0,0 +1,53 @@
+"""Convenience functions for quick one-off queries."""
+
+from typing import Any
+
+from resolvekit.api.resolver import Resolver
+from resolvekit.types import MatchContext, Resolution
+
+
+def resolve(
+    query: str,
+    context: MatchContext | None = None,
+    **resolver_kwargs: Any,
+) -> Resolution:
+    """
+    Resolve single entity (convenience function).
+
+    Creates ephemeral Resolver instance for one-off queries.
+    For repeated queries, create a Resolver instance for better performance.
+
+    Args:
+        query: Entity string to resolve
+        context: Optional match context
+        **resolver_kwargs: Passed to Resolver() constructor
+            (min_confidence, explanation_mode, etc.)
+
+    Returns:
+        Resolution result
+    """
+    with Resolver(**resolver_kwargs) as resolver:
+        return resolver.resolve(query, context=context)
+
+
+def resolve_many(
+    queries: list[str],
+    context: MatchContext | list[MatchContext | None] | None = None,
+    **resolver_kwargs: Any,
+) -> list[Resolution]:
+    """
+    Resolve multiple entities (convenience function).
+
+    Creates ephemeral Resolver instance.
+    For repeated queries, create a Resolver instance for better performance.
+
+    Args:
+        queries: List of query strings
+        context: Optional context (shared or per-query list)
+        **resolver_kwargs: Passed to Resolver() constructor
+
+    Returns:
+        List of Resolution objects
+    """
+    with Resolver(**resolver_kwargs) as resolver:
+        return resolver.resolve_many(queries, context=context)