resolvekit 0.0.1__tar.gz

resolvekit-0.0.1/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.3
+Name: resolvekit
+Version: 0.0.1
+Summary: A local, offline-first entity and place resolution system that maps messy place/entity strings and codes to canonical entities with calibrated confidence scores
+Keywords: entity-resolution,geocoding,place-names,data-commons,iso-codes,offline,disambiguation,normalization
+Author: Jorge Rivera
+Author-email: Jorge Rivera <jorge.rivera@one.org>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: rapidfuzz>=3.0.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: sqlmodel>=0.0.24
+Requires-Python: >=3.11
+Project-URL: Documentation, https://github.com/jm-rivera/resolvekit
+Project-URL: Homepage, https://github.com/jm-rivera/resolvekit
+Project-URL: Repository, https://github.com/jm-rivera/resolvekit
+Description-Content-Type: text/markdown
+
+# resolvekit
+An open offline resolver for places and entities

resolvekit-0.0.1/README.md

@@ -0,0 +1,2 @@
+# resolvekit
+An open offline resolver for places and entities

resolvekit-0.0.1/pyproject.toml

@@ -0,0 +1,214 @@
+[project]
+name = "resolvekit"
+version = "0.0.1"
+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"
+requires-python = ">=3.11"
+
+license = {text = "MIT"}
+readme = "README.md"
+authors = [
+    {name = "Jorge Rivera", email = "jorge.rivera@one.org"}
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Text Processing :: Linguistic",
+    "Typing :: Typed"
+]
+
+keywords = [
+    "entity-resolution",
+    "geocoding",
+    "place-names",
+    "data-commons",
+    "iso-codes",
+    "offline",
+    "disambiguation",
+    "normalization"
+]
+
+dependencies = [
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "rapidfuzz>=3.0.0",
+    "python-dateutil>=2.8.0",
+    "sqlalchemy>=2.0.0",
+    "sqlmodel>=0.0.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/jm-rivera/resolvekit"
+Repository = "https://github.com/jm-rivera/resolvekit"
+Documentation = "https://github.com/jm-rivera/resolvekit"
+
+[project.scripts]
+resolvekit = "resolvekit:main"
+
+[build-system]
+requires = ["uv_build>=0.8.22,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "uv-build>=0.8.22",
+    "pre-commit>=4.0.0",
+    "ruff>=0.14.0",
+    "mypy>=1.8.0",
+    "pandas-stubs>=2.3.2.250926",
+]
+test = [
+    "pytest>=8.0.0",
+    "pytest-benchmark>=5.1.0",
+    "pytest-cov>=4.1.0",
+    "pytest-xdist>=3.5.0",
+]
+
+[tool.ruff]
+# Set the maximum line length
+line-length = 88
+
+# Target Python 3.10+
+target-version = "py313"
+
+# Exclude common directories
+exclude = [
+    ".git",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "*.egg-info",
+    ".pytest_cache",
+    "htmlcov",
+]
+
+[tool.ruff.lint]
+# Enable recommended rules plus extras
+select = [
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "F",     # pyflakes
+    "I",     # isort
+    "N",     # pep8-naming
+    "UP",    # pyupgrade
+    "B",     # flake8-bugbear
+    "C4",    # flake8-comprehensions
+    "SIM",   # flake8-simplify
+    "PL",    # pylint
+    "RUF",   # ruff-specific rules
+]
+
+# Ignore specific rules that might be too strict
+ignore = [
+    "E501",    # Line too long (handled by formatter)
+    "PLR0913", # Too many arguments
+    "PLR2004", # Magic value used in comparison
+]
+
+# Allow autofix for all enabled rules
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+# Allow test files to have more relaxed rules
+"tests/**/*.py" = ["E501", "PLR2004"]
+# Allow imports not at top level in __init__.py (used to avoid circular imports)
+"src/resolvekit/__init__.py" = ["PLC0415"]
+
+[tool.ruff.format]
+# Use double quotes for strings
+quote-style = "double"
+
+# Use spaces for indentation
+indent-style = "space"
+
+# Like Black, respect magic trailing commas
+skip-magic-trailing-comma = false
+
+# Like Black, automatically detect line endings
+line-ending = "auto"
+
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+strict_equality = true
+
+[tool.pytest.ini_options]
+# Test discovery patterns
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+# Test execution options
+addopts = [
+    "-v",
+    "--strict-markers",
+    "--strict-config",
+    "--tb=short",
+    "--cov=src/resolvekit",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+    "--cov-branch",
+]
+
+# Custom markers for organizing tests
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+    "unit: marks tests as unit tests",
+    "matcher: marks tests related to matcher functionality",
+    "calibration: marks tests related to confidence calibration",
+    "temporal: marks tests related to temporal validation",
+]
+
+# Ignore patterns
+norecursedirs = [
+    ".git",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "*.egg-info",
+    ".pytest_cache",
+    "htmlcov",
+]
+
+[tool.coverage.run]
+source = ["src/resolvekit"]
+omit = [
+    "*/tests/*",
+    "*/__pycache__/*",
+    "*/__init__.py",
+]
+
+[tool.coverage.report]
+precision = 2
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]

resolvekit-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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)