enrichfold 0.2.0__tar.gz

enrichfold-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Test
+        run: |
+          python -m pip install --upgrade pip pytest
+          python -m pip install .
+          pytest -q

enrichfold-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

enrichfold-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+uv.lock

enrichfold-0.2.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.2.0 - 2026-08-20
+
+- Added provenance-bearing `Claim` contracts and deterministic claim
+  reconciliation.
+- Made contradictory values and inferred claims explicit `needs_review` gates.
+- Added offline, fail-closed company identity resolution for corporate email
+  domains and supplied websites.
+- Preserved the 0.1 provider protocol and the simple `EnrichmentPipeline` API;
+  pipeline results now expose `review_fields` when provider values disagree.
+
+## 0.1.0 - 2026-08-20
+
+- Initial provider-neutral, provenance-first enrichment core.

enrichfold-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mihail R.
+
+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.

enrichfold-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: enrichfold
+Version: 0.2.0
+Summary: Provider-neutral, provenance-first entity enrichment for people and companies.
+Project-URL: Homepage, https://github.com/Mihailorama/enrichfold
+Project-URL: Repository, https://github.com/Mihailorama/enrichfold
+Project-URL: Issues, https://github.com/Mihailorama/enrichfold/issues
+Author: Mihail R.
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Enrichfold
+
+Provider-neutral, provenance-first entity enrichment for people and companies.
+
+`enrichfold` is an offline-first core, not a scraping product: applications supply
+their own discovery providers and credentials. Every accepted attribute retains its
+source URL, observation time, and confidence, so downstream systems can decide
+whether a result is suitable for an automated action or requires review.
+
+```python
+from enrichfold import Entity, EnrichmentPipeline, Evidence
+
+class CompanyProvider:
+    def discover(self, entity):
+        return [Evidence(
+            source_url="https://example.com/team",
+            observed_at="2026-08-20T12:00:00Z",
+            confidence=0.94,
+            attributes={"industry": "software", "company_size": "51-200"},
+        )]
+
+company = Entity.company(domain="example.com")
+result = EnrichmentPipeline([CompanyProvider()]).enrich(company)
+print(result.attributes["industry"].value)  # software
+```
+
+## Evidence, conflicts, and review gates
+
+`enrichfold` keeps provider I/O outside the library. Its core turns supplied
+evidence into deterministic decisions while retaining disagreements for a human
+approval flow. A conflicting value is never silently accepted:
+
+```python
+from enrichfold import Claim, Evidence, reconcile_claims
+
+result = reconcile_claims([
+    Claim(
+        field="industry",
+        value="software",
+        evidence=Evidence(
+            source_url="https://acme.example/about",
+            observed_at="2026-08-20T12:00:00Z",
+            confidence=0.91,
+        ),
+    ),
+    Claim(
+        field="industry",
+        value="retail",
+        evidence=Evidence(
+            source_url="https://directory.example/acme",
+            observed_at="2026-08-20T12:00:00Z",
+            confidence=0.88,
+        ),
+    ),
+])
+
+industry = result.fields["industry"]
+assert industry.value == "software"          # stable suggested value
+assert industry.status == "needs_review"     # do not automate an action
+assert result.requires_review is True
+```
+
+`Claim(kind="inferred", ...)` also requires review even with no competing
+claim. This distinction makes it possible to keep model-produced hypotheses
+without presenting them as observed facts.
+
+## Company identity gate
+
+Before a caller enriches or acts on a company, use the offline identity gate.
+It is deliberately conservative: free mailboxes, invalid sites, domain
+conflicts, and corporate domains that do not exactly match the name receive a
+review status. Applications can pass separately verified site metadata when
+they have it.
+
+```python
+from enrichfold import derive_company_identity
+
+identity = derive_company_identity(
+    email="hello@acme.example",
+    company_name="Acme",
+    website="https://www.acme.example/about",
+)
+
+assert identity.status == "verified"
+assert identity.canonical_domain == "acme.example"
+```
+
+## Design boundaries
+
+- No network calls, scraping, credential handling, contact exporting, or outreach.
+- No inferred facts: a field is returned only when a provider supplies evidence.
+- Conflicts have a deterministic suggested value but are marked `needs_review`.
+- Inferred claims are always marked `needs_review`.
+- Company identity is verified only through an exact name/domain match or
+  caller-supplied, independently verified same-domain site metadata.
+- Bring your own providers for search engines, public data APIs, browser tools, or
+  internal approved sources.
+
+The package intentionally does not decide whether a review is approved or run
+an action after one; persistence, permissions, UI, and provider adapters stay
+with the host application.
+
+## Installation
+
+```bash
+pip install enrichfold
+```
+
+## Development
+
+```bash
+uv run --with pytest pytest -q
+python -m build
+```
+
+## License
+
+MIT.

enrichfold-0.2.0/README.md

@@ -0,0 +1,118 @@
+# Enrichfold
+
+Provider-neutral, provenance-first entity enrichment for people and companies.
+
+`enrichfold` is an offline-first core, not a scraping product: applications supply
+their own discovery providers and credentials. Every accepted attribute retains its
+source URL, observation time, and confidence, so downstream systems can decide
+whether a result is suitable for an automated action or requires review.
+
+```python
+from enrichfold import Entity, EnrichmentPipeline, Evidence
+
+class CompanyProvider:
+    def discover(self, entity):
+        return [Evidence(
+            source_url="https://example.com/team",
+            observed_at="2026-08-20T12:00:00Z",
+            confidence=0.94,
+            attributes={"industry": "software", "company_size": "51-200"},
+        )]
+
+company = Entity.company(domain="example.com")
+result = EnrichmentPipeline([CompanyProvider()]).enrich(company)
+print(result.attributes["industry"].value)  # software
+```
+
+## Evidence, conflicts, and review gates
+
+`enrichfold` keeps provider I/O outside the library. Its core turns supplied
+evidence into deterministic decisions while retaining disagreements for a human
+approval flow. A conflicting value is never silently accepted:
+
+```python
+from enrichfold import Claim, Evidence, reconcile_claims
+
+result = reconcile_claims([
+    Claim(
+        field="industry",
+        value="software",
+        evidence=Evidence(
+            source_url="https://acme.example/about",
+            observed_at="2026-08-20T12:00:00Z",
+            confidence=0.91,
+        ),
+    ),
+    Claim(
+        field="industry",
+        value="retail",
+        evidence=Evidence(
+            source_url="https://directory.example/acme",
+            observed_at="2026-08-20T12:00:00Z",
+            confidence=0.88,
+        ),
+    ),
+])
+
+industry = result.fields["industry"]
+assert industry.value == "software"          # stable suggested value
+assert industry.status == "needs_review"     # do not automate an action
+assert result.requires_review is True
+```
+
+`Claim(kind="inferred", ...)` also requires review even with no competing
+claim. This distinction makes it possible to keep model-produced hypotheses
+without presenting them as observed facts.
+
+## Company identity gate
+
+Before a caller enriches or acts on a company, use the offline identity gate.
+It is deliberately conservative: free mailboxes, invalid sites, domain
+conflicts, and corporate domains that do not exactly match the name receive a
+review status. Applications can pass separately verified site metadata when
+they have it.
+
+```python
+from enrichfold import derive_company_identity
+
+identity = derive_company_identity(
+    email="hello@acme.example",
+    company_name="Acme",
+    website="https://www.acme.example/about",
+)
+
+assert identity.status == "verified"
+assert identity.canonical_domain == "acme.example"
+```
+
+## Design boundaries
+
+- No network calls, scraping, credential handling, contact exporting, or outreach.
+- No inferred facts: a field is returned only when a provider supplies evidence.
+- Conflicts have a deterministic suggested value but are marked `needs_review`.
+- Inferred claims are always marked `needs_review`.
+- Company identity is verified only through an exact name/domain match or
+  caller-supplied, independently verified same-domain site metadata.
+- Bring your own providers for search engines, public data APIs, browser tools, or
+  internal approved sources.
+
+The package intentionally does not decide whether a review is approved or run
+an action after one; persistence, permissions, UI, and provider adapters stay
+with the host application.
+
+## Installation
+
+```bash
+pip install enrichfold
+```
+
+## Development
+
+```bash
+uv run --with pytest pytest -q
+python -m build
+```
+
+## License
+
+MIT.

enrichfold-0.2.0/SECURITY.md

@@ -0,0 +1,5 @@
+# Security policy
+
+Please report vulnerabilities privately through GitHub Security Advisories for
+this repository. Do not include credentials, private contact data, or raw
+provider responses in public issues.

enrichfold-0.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "enrichfold"
+version = "0.2.0"
+description = "Provider-neutral, provenance-first entity enrichment for people and companies."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Mihail R." }]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.urls]
+Homepage = "https://github.com/Mihailorama/enrichfold"
+Repository = "https://github.com/Mihailorama/enrichfold"
+Issues = "https://github.com/Mihailorama/enrichfold/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/enrichfold"]

enrichfold-0.2.0/src/enrichfold/__init__.py

@@ -0,0 +1,47 @@
+"""Provider-neutral, provenance-first entity enrichment."""
+
+from .identity import (
+    DEFAULT_FREE_EMAIL_DOMAINS,
+    DEFAULT_GENERIC_COMPANY_NAMES,
+    CompanyIdentity,
+    SiteIdentity,
+    canonical_website_domain,
+    company_email_domain,
+    company_name_matches_domain,
+    derive_company_identity,
+    is_free_email_domain,
+    is_generic_company_name,
+)
+from .models import (
+    Claim,
+    EnrichmentResult,
+    Entity,
+    Evidence,
+    FieldResolution,
+    ReconciliationResult,
+    ResolvedAttribute,
+)
+from .pipeline import DiscoveryProvider, EnrichmentPipeline, reconcile_claims
+
+__all__ = [
+    "Claim",
+    "CompanyIdentity",
+    "DEFAULT_FREE_EMAIL_DOMAINS",
+    "DEFAULT_GENERIC_COMPANY_NAMES",
+    "DiscoveryProvider",
+    "EnrichmentPipeline",
+    "EnrichmentResult",
+    "Entity",
+    "Evidence",
+    "FieldResolution",
+    "ReconciliationResult",
+    "ResolvedAttribute",
+    "SiteIdentity",
+    "canonical_website_domain",
+    "company_email_domain",
+    "company_name_matches_domain",
+    "derive_company_identity",
+    "is_free_email_domain",
+    "is_generic_company_name",
+    "reconcile_claims",
+]

enrichfold-0.2.0/src/enrichfold/identity.py

@@ -0,0 +1,233 @@
+"""Offline company identity checks that fail closed when evidence is weak."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Collection, Literal
+from urllib.parse import urlsplit
+
+
+DEFAULT_FREE_EMAIL_DOMAINS = frozenset(
+    {
+        "gmail.com",
+        "googlemail.com",
+        "outlook.com",
+        "hotmail.com",
+        "icloud.com",
+        "proton.me",
+        "protonmail.com",
+        "yahoo.com",
+    }
+)
+DEFAULT_GENERIC_COMPANY_NAMES = frozenset({"company", "unknown", "unknown company"})
+_DOMAIN_RE = re.compile(
+    r"^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])$",
+    re.IGNORECASE,
+)
+
+IdentityStatus = Literal["verified", "needs_review"]
+
+
+@dataclass(frozen=True)
+class SiteIdentity:
+    """A caller-verified identity read from a supplied website."""
+
+    name: str
+    domain: str
+
+
+@dataclass(frozen=True)
+class CompanyIdentity:
+    """An identity decision that is safe to gate before enrichment or actions."""
+
+    status: IdentityStatus
+    name: str | None
+    canonical_domain: str | None
+    website: str | None
+    slug: str | None
+    reason: str
+
+    @property
+    def requires_review(self) -> bool:
+        return self.status == "needs_review"
+
+
+def company_email_domain(email: str) -> str | None:
+    local, separator, domain = email.strip().lower().rpartition("@")
+    if not separator or not local or not _DOMAIN_RE.fullmatch(domain):
+        return None
+    return domain
+
+
+def canonical_website_domain(website: str | None) -> str | None:
+    if not website or not website.strip():
+        return None
+    value = website.strip()
+    parsed = urlsplit(value if re.match(r"^https?://", value, re.IGNORECASE) else f"https://{value}")
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        return None
+    hostname = parsed.hostname.lower().removeprefix("www.")
+    return hostname if _DOMAIN_RE.fullmatch(hostname) else None
+
+
+def is_free_email_domain(domain: str, *, free_email_domains: Collection[str] = DEFAULT_FREE_EMAIL_DOMAINS) -> bool:
+    return domain.lower() in {item.lower() for item in free_email_domains}
+
+
+def is_generic_company_name(name: str | None, *, generic_names: Collection[str] = DEFAULT_GENERIC_COMPANY_NAMES) -> bool:
+    normalized = re.sub(r"\s+", " ", (name or "").strip().casefold())
+    return not normalized or normalized in {item.strip().casefold() for item in generic_names}
+
+
+def slugify(value: str) -> str:
+    """Locale-safe readable slug; applications may replace it for their own URLs."""
+
+    return "-".join(part for part in re.split(r"[^\w]+", value.casefold(), flags=re.UNICODE) if part)
+
+
+def _domains_match(left: str, right: str) -> bool:
+    return left == right or left.endswith(f".{right}") or right.endswith(f".{left}")
+
+
+def company_name_matches_domain(name: str, domain: str) -> bool:
+    """Match only the registrable-looking first label; never substring-match."""
+
+    labels = domain.lower().removeprefix("www.").split(".")
+    if len(labels) != 2:
+        return False
+    normalized_name = re.sub(r"[^a-z0-9]", "", name.lower())
+    return bool(normalized_name) and normalized_name == labels[0].replace("-", "")
+
+
+def _identity(
+    *,
+    status: IdentityStatus,
+    name: str | None,
+    domain: str | None,
+    slug: str | None,
+    reason: str,
+) -> CompanyIdentity:
+    return CompanyIdentity(
+        status=status,
+        name=name,
+        canonical_domain=domain,
+        website=f"https://{domain}" if domain else None,
+        slug=slug,
+        reason=reason,
+    )
+
+
+def derive_company_identity(
+    *,
+    email: str,
+    company_name: str | None,
+    website: str | None,
+    verified_site_identity: SiteIdentity | None = None,
+    free_email_domains: Collection[str] = DEFAULT_FREE_EMAIL_DOMAINS,
+    generic_names: Collection[str] = DEFAULT_GENERIC_COMPANY_NAMES,
+) -> CompanyIdentity:
+    """Derive an identity without network access and require review by default.
+
+    A corporate domain is only verified when it exactly matches the company
+    name, or when a caller supplies independently verified same-domain site
+    metadata. Free mailboxes and conflicts never become automatically verified.
+    """
+
+    name = None if is_generic_company_name(company_name, generic_names=generic_names) else company_name.strip()
+    slug = slugify(name) if name else None
+    email_domain = company_email_domain(email)
+    website_domain = canonical_website_domain(website)
+
+    if not name:
+        return _identity(
+            status="needs_review",
+            name=None,
+            domain=website_domain or email_domain,
+            slug=None,
+            reason="missing_company_name",
+        )
+    if not email_domain:
+        return _identity(
+            status="needs_review",
+            name=name,
+            domain=website_domain,
+            slug=slug,
+            reason="invalid_email",
+        )
+    if website and not website_domain:
+        return _identity(
+            status="needs_review",
+            name=name,
+            domain=None,
+            slug=slug,
+            reason="invalid_website",
+        )
+    if website_domain and not is_free_email_domain(email_domain, free_email_domains=free_email_domains) and not _domains_match(email_domain, website_domain):
+        return _identity(
+            status="needs_review",
+            name=name,
+            domain=website_domain,
+            slug=slug,
+            reason="domain_conflict",
+        )
+    if website_domain and is_free_email_domain(email_domain, free_email_domains=free_email_domains):
+        return _identity(
+            status="needs_review",
+            name=name,
+            domain=website_domain,
+            slug=slug,
+            reason="free_email_with_unverified_website",
+        )
+    if (
+        website_domain
+        and verified_site_identity
+        and verified_site_identity.name.strip() == name
+        and _domains_match(website_domain, verified_site_identity.domain.lower().removeprefix("www."))
+    ):
+        return _identity(
+            status="verified",
+            name=name,
+            domain=website_domain,
+            slug=slug,
+            reason="corporate_email_domain_site_metadata",
+        )
+    if website_domain and company_name_matches_domain(name, website_domain):
+        return _identity(
+            status="verified",
+            name=name,
+            domain=website_domain,
+            slug=slug,
+            reason="matching_email_and_website",
+        )
+    if website_domain:
+        return _identity(
+            status="needs_review",
+            name=name,
+            domain=website_domain,
+            slug=slug,
+            reason="corporate_email_domain_unverified",
+        )
+    if is_free_email_domain(email_domain, free_email_domains=free_email_domains):
+        return _identity(
+            status="needs_review",
+            name=name,
+            domain=None,
+            slug=slug,
+            reason="free_email_without_website",
+        )
+    if company_name_matches_domain(name, email_domain):
+        return _identity(
+            status="verified",
+            name=name,
+            domain=email_domain,
+            slug=slug,
+            reason="corporate_email_domain",
+        )
+    return _identity(
+        status="needs_review",
+        name=name,
+        domain=email_domain,
+        slug=slug,
+        reason="corporate_email_domain_unverified",
+    )

enrichfold-0.2.0/src/enrichfold/models.py

@@ -0,0 +1,127 @@
+"""Immutable, provenance-first data contracts for enrichment."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Literal, Mapping
+
+
+EntityKind = Literal["person", "company"]
+ClaimKind = Literal["observed", "inferred"]
+ReviewStatus = Literal["accepted", "needs_review"]
+
+
+@dataclass(frozen=True)
+class Entity:
+    """A person or company identified by one or more non-empty identifiers."""
+
+    kind: EntityKind
+    identifiers: Mapping[str, str]
+
+    def __post_init__(self) -> None:
+        normalized = {
+            key.strip(): value.strip()
+            for key, value in self.identifiers.items()
+            if key.strip() and value.strip()
+        }
+        if not normalized:
+            raise ValueError("an entity requires at least one non-empty identifier")
+        object.__setattr__(self, "identifiers", normalized)
+
+    @classmethod
+    def person(cls, **identifiers: str) -> Entity:
+        return cls(kind="person", identifiers=identifiers)
+
+    @classmethod
+    def company(cls, **identifiers: str) -> Entity:
+        return cls(kind="company", identifiers=identifiers)
+
+
+@dataclass(frozen=True)
+class Evidence:
+    """A provider-observed source. The library never fetches it itself."""
+
+    source_url: str
+    observed_at: str
+    confidence: float
+    attributes: Mapping[str, Any] = field(default_factory=dict)
+    source_title: str | None = None
+    source_date: str | None = None
+    provider: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.source_url.startswith(("https://", "http://")):
+            raise ValueError("evidence requires an http(s) source_url")
+        if not 0.0 <= self.confidence <= 1.0:
+            raise ValueError("confidence must be between 0 and 1")
+
+
+@dataclass(frozen=True)
+class Claim:
+    """One value asserted for a field, with an immutable evidence reference.
+
+    ``inferred`` claims are intentionally never silently auto-approved by the
+    reconciliation API; callers must record their review decision.
+    """
+
+    field: str
+    value: Any
+    evidence: Evidence
+    kind: ClaimKind = "observed"
+
+    def __post_init__(self) -> None:
+        if not self.field.strip():
+            raise ValueError("a claim requires a non-empty field")
+
+
+@dataclass(frozen=True)
+class ResolvedAttribute:
+    """One chosen attribute and the evidence that supports it."""
+
+    value: Any
+    source_url: str
+    observed_at: str
+    confidence: float
+
+
+@dataclass(frozen=True)
+class FieldResolution:
+    """A deterministic choice plus alternatives that require human review."""
+
+    value: Any
+    evidence: Evidence
+    kind: ClaimKind
+    status: ReviewStatus
+    alternatives: tuple[Claim, ...] = ()
+
+
+@dataclass(frozen=True)
+class ReconciliationResult:
+    """Field-level decisions from one or more independently supplied claims."""
+
+    fields: Mapping[str, FieldResolution]
+
+    @property
+    def review_fields(self) -> tuple[str, ...]:
+        return tuple(name for name, value in self.fields.items() if value.status == "needs_review")
+
+    @property
+    def requires_review(self) -> bool:
+        return bool(self.review_fields)
+
+
+@dataclass(frozen=True)
+class EnrichmentResult:
+    """Resolved attributes plus requested fields for which no evidence exists."""
+
+    entity: Entity
+    attributes: Mapping[str, ResolvedAttribute]
+    missing: tuple[str, ...]
+    review_fields: tuple[str, ...] = ()
+
+
+def canonical_value(value: Any) -> str:
+    """Stable value identity for deterministic grouping and conflict detection."""
+
+    return json.dumps(value, sort_keys=True, ensure_ascii=False, default=str, separators=(",", ":"))

enrichfold-0.2.0/src/enrichfold/pipeline.py

@@ -0,0 +1,110 @@
+"""Provider orchestration and review-safe deterministic reconciliation."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from typing import Protocol
+
+from .models import (
+    Claim,
+    EnrichmentResult,
+    Entity,
+    Evidence,
+    FieldResolution,
+    ReconciliationResult,
+    ResolvedAttribute,
+    canonical_value,
+)
+
+
+class DiscoveryProvider(Protocol):
+    """A caller-owned adapter that returns externally observed evidence."""
+
+    def discover(self, entity: Entity) -> Iterable[Evidence]: ...
+
+
+Provider = DiscoveryProvider | Callable[[Entity], Iterable[Evidence]]
+
+
+def _rank(claim: Claim) -> tuple[int, float, str, str]:
+    """Rank observed evidence before inference, then use reproducible tie-breaks."""
+
+    return (
+        0 if claim.kind == "observed" else 1,
+        -claim.evidence.confidence,
+        claim.evidence.source_url,
+        canonical_value(claim.value),
+    )
+
+
+def reconcile_claims(claims: Iterable[Claim]) -> ReconciliationResult:
+    """Resolve claims deterministically while failing closed on disagreement.
+
+    Multiple claims for the same canonical value reinforce one another. Distinct
+    values are retained as alternatives and make the field ``needs_review``;
+    an inferred winning value also requires review. This lets an application
+    choose its own approval workflow without losing provenance.
+    """
+
+    by_field: dict[str, list[Claim]] = {}
+    for claim in claims:
+        by_field.setdefault(claim.field.strip(), []).append(claim)
+
+    fields: dict[str, FieldResolution] = {}
+    for name, field_claims in by_field.items():
+        by_value: dict[str, list[Claim]] = {}
+        for claim in field_claims:
+            by_value.setdefault(canonical_value(claim.value), []).append(claim)
+
+        representatives = [min(group, key=_rank) for group in by_value.values()]
+        chosen = min(representatives, key=_rank)
+        alternatives = tuple(
+            claim
+            for claim in sorted(representatives, key=_rank)
+            if canonical_value(claim.value) != canonical_value(chosen.value)
+        )
+        status = "needs_review" if alternatives or chosen.kind == "inferred" else "accepted"
+        fields[name] = FieldResolution(
+            value=chosen.value,
+            evidence=chosen.evidence,
+            kind=chosen.kind,
+            status=status,
+            alternatives=alternatives,
+        )
+    return ReconciliationResult(fields=fields)
+
+
+class EnrichmentPipeline:
+    """Combine provider evidence without making network calls itself."""
+
+    def __init__(self, providers: Sequence[Provider]) -> None:
+        self._providers = tuple(providers)
+
+    def enrich(self, entity: Entity, *, requested_fields: Iterable[str] = ()) -> EnrichmentResult:
+        claims: list[Claim] = []
+        for provider in self._providers:
+            discovered = provider.discover(entity) if hasattr(provider, "discover") else provider(entity)
+            for evidence in discovered:
+                claims.extend(
+                    Claim(field=attribute, value=value, evidence=evidence)
+                    for attribute, value in evidence.attributes.items()
+                )
+
+        reconciled = reconcile_claims(claims)
+        resolved = {
+            attribute: ResolvedAttribute(
+                value=resolution.value,
+                source_url=resolution.evidence.source_url,
+                observed_at=resolution.evidence.observed_at,
+                confidence=resolution.evidence.confidence,
+            )
+            for attribute, resolution in reconciled.fields.items()
+        }
+        requested = tuple(dict.fromkeys(field.strip() for field in requested_fields if field.strip()))
+        missing = tuple(field for field in requested if field not in resolved)
+        return EnrichmentResult(
+            entity=entity,
+            attributes=resolved,
+            missing=missing,
+            review_fields=reconciled.review_fields,
+        )

enrichfold-0.2.0/tests/test_pipeline.py

@@ -0,0 +1,171 @@
+from enrichfold import (
+    Claim,
+    Entity,
+    EnrichmentPipeline,
+    Evidence,
+    derive_company_identity,
+    reconcile_claims,
+)
+
+
+class CompanyProvider:
+    def discover(self, entity: Entity) -> list[Evidence]:
+        assert entity.identifiers == {"domain": "example.com"}
+        return [
+            Evidence(
+                source_url="https://example.com/team",
+                observed_at="2026-08-20T12:00:00Z",
+                confidence=0.94,
+                attributes={"industry": "software", "company_size": "51-200"},
+            )
+        ]
+
+
+def test_enriches_a_company_with_provenance() -> None:
+    result = EnrichmentPipeline([CompanyProvider()]).enrich(Entity.company(domain="example.com"))
+
+    assert result.attributes["industry"].value == "software"
+    assert result.attributes["industry"].source_url == "https://example.com/team"
+    assert result.attributes["industry"].confidence == 0.94
+    assert result.missing == ()
+
+
+def test_uses_stronger_evidence_for_a_conflicting_value() -> None:
+    weak = Evidence(
+        source_url="https://directory.example/acme",
+        observed_at="2026-08-20T12:00:00Z",
+        confidence=0.30,
+        attributes={"industry": "retail"},
+    )
+    strong = Evidence(
+        source_url="https://acme.example/about",
+        observed_at="2026-08-20T12:00:00Z",
+        confidence=0.90,
+        attributes={"industry": "software"},
+    )
+
+    result = EnrichmentPipeline([lambda entity: [weak, strong]]).enrich(Entity.company(domain="acme.example"))
+
+    assert result.attributes["industry"].value == "software"
+    assert result.attributes["industry"].source_url == "https://acme.example/about"
+
+
+def test_identity_requires_review_for_an_unverified_corporate_domain() -> None:
+    identity = derive_company_identity(
+        email="partnerships@parent-company.example",
+        company_name="Acme Labs",
+        website=None,
+    )
+
+    assert identity.status == "needs_review"
+    assert identity.canonical_domain == "parent-company.example"
+    assert identity.reason == "corporate_email_domain_unverified"
+
+
+def test_identity_accepts_matching_corporate_domain_and_site() -> None:
+    identity = derive_company_identity(
+        email="hello@acme.example",
+        company_name="Acme",
+        website="https://www.acme.example/about",
+    )
+
+    assert identity.status == "verified"
+    assert identity.canonical_domain == "acme.example"
+    assert identity.website == "https://acme.example"
+    assert identity.reason == "matching_email_and_website"
+
+
+def test_identity_does_not_trust_a_free_mailbox_with_a_supplied_site() -> None:
+    identity = derive_company_identity(
+        email="person@gmail.com",
+        company_name="Acme",
+        website="https://acme.example",
+    )
+
+    assert identity.status == "needs_review"
+    assert identity.reason == "free_email_with_unverified_website"
+
+
+def test_identity_detects_a_corporate_domain_conflict() -> None:
+    identity = derive_company_identity(
+        email="hello@acme.example",
+        company_name="Acme",
+        website="https://unrelated.example",
+    )
+
+    assert identity.status == "needs_review"
+    assert identity.reason == "domain_conflict"
+
+
+def test_reconciliation_marks_differing_observations_for_review() -> None:
+    result = reconcile_claims(
+        [
+            Claim(
+                field="industry",
+                value="software",
+                evidence=Evidence(
+                    source_url="https://acme.example/about",
+                    observed_at="2026-08-20T12:00:00Z",
+                    confidence=0.91,
+                    attributes={},
+                ),
+            ),
+            Claim(
+                field="industry",
+                value="retail",
+                evidence=Evidence(
+                    source_url="https://directory.example/acme",
+                    observed_at="2026-08-20T12:00:00Z",
+                    confidence=0.88,
+                    attributes={},
+                ),
+            ),
+        ]
+    )
+
+    resolution = result.fields["industry"]
+    assert resolution.status == "needs_review"
+    assert resolution.value == "software"
+    assert len(resolution.alternatives) == 1
+
+
+def test_reconciliation_requires_review_for_an_inferred_claim() -> None:
+    result = reconcile_claims(
+        [
+            Claim(
+                field="market",
+                value="Europe",
+                kind="inferred",
+                evidence=Evidence(
+                    source_url="https://acme.example/press",
+                    observed_at="2026-08-20T12:00:00Z",
+                    confidence=0.99,
+                    attributes={},
+                ),
+            )
+        ]
+    )
+
+    assert result.requires_review is True
+    assert result.review_fields == ("market",)
+    assert result.fields["market"].status == "needs_review"
+
+
+def test_pipeline_exposes_conflicts_without_dropping_deterministic_value() -> None:
+    first = Evidence(
+        source_url="https://acme.example/about",
+        observed_at="2026-08-20T12:00:00Z",
+        confidence=0.91,
+        attributes={"industry": "software"},
+    )
+    second = Evidence(
+        source_url="https://directory.example/acme",
+        observed_at="2026-08-20T12:00:00Z",
+        confidence=0.88,
+        attributes={"industry": "retail"},
+    )
+
+    result = EnrichmentPipeline([lambda entity: [first, second]]).enrich(Entity.company(domain="acme.example"))
+
+    assert result.attributes["industry"].value == "software"
+    assert result.review_fields == ("industry",)