structverify 0.3.0__py3-none-any.whl

structverify/api.py

@@ -0,0 +1,804 @@
+"""structverify.api — the ergonomic, high-level public API.
+
+This is the "point-and-call" surface most users touch, inspired by the feel of
+libraries like ``transformers``: configure once, then call a method and read a
+plain boolean / result off the returned object.
+
+    >>> import structverify as sv
+    >>>
+    >>> # 규정 준수 검사 (conformance) — bring your own rulebook (PDF/txt)
+    >>> rules = sv.Ruleset.from_file("safety_standard.pdf", provider="upstage")
+    >>> v = rules.check("총납 함량은 120mg/kg으로 측정되었다")
+    >>> v.compliant          # False  ← plain True/False
+    False
+    >>> v.article            # "제3조 (총납) … 100mg/kg 이하"
+    >>> v.rule_value, v.claim_value, v.unit
+    (100.0, 120.0, 'mg/kg')
+    >>>
+    >>> # 사실 검증 (fact verification) against a data source
+    >>> report = sv.verify("과수농가 65세 이상 비율은 64.2%다", provider="upstage")
+    >>> report.ok            # no false claim detected?
+    >>> for r in report:
+    ...     r.ok, r.verdict, r.reason
+
+Everything here is synchronous by default (each call blocks and returns a
+result). Every sync method has an ``a``-prefixed async twin
+(``check``/``acheck``, ``verify``/``averify``) for use inside an event loop.
+"""
+from __future__ import annotations
+
+import asyncio
+import copy
+import os
+import re
+import tempfile
+import threading
+from typing import Any, Iterator
+
+from structverify.utils.logger import configure_logging  # re-export
+
+__all__ = [
+    "verify",
+    "Verifier",
+    "Ruleset",
+    "DataSource",
+    "Report",
+    "Result",
+    "Verdict",
+    "build_config",
+    "configure_logging",
+]
+
+
+# ── sync/async bridge ────────────────────────────────────────────────────────
+
+_loop: asyncio.AbstractEventLoop | None = None
+_loop_lock = threading.Lock()
+
+
+def _background_loop() -> asyncio.AbstractEventLoop:
+    """A single, long-lived event loop running in a daemon thread.
+
+    All sync calls run on this one loop, so stateful async resources created by
+    one call (e.g. an ``httpx.AsyncClient`` opened while indexing a ruleset)
+    stay bound to a live loop across subsequent calls — unlike ``asyncio.run``,
+    which opens and closes a fresh loop every time.
+    """
+    global _loop
+    if _loop is not None and not _loop.is_closed():
+        return _loop
+    with _loop_lock:
+        if _loop is None or _loop.is_closed():
+            loop = asyncio.new_event_loop()
+            threading.Thread(
+                target=loop.run_forever, name="structverify", daemon=True,
+            ).start()
+            _loop = loop
+    return _loop
+
+
+def _run(coro):
+    """Run an async coroutine to completion from synchronous code.
+
+    Works everywhere — including inside a notebook or an already-running event
+    loop — because the coroutine executes on a dedicated background loop and the
+    calling thread simply blocks on the result.
+    """
+    return asyncio.run_coroutine_threadsafe(coro, _background_loop()).result()
+
+
+# ── config building ──────────────────────────────────────────────────────────
+
+def _deep_merge(base: dict, overlay: dict) -> dict:
+    for k, v in overlay.items():
+        if isinstance(v, dict) and isinstance(base.get(k), dict):
+            _deep_merge(base[k], v)
+        else:
+            base[k] = v
+    return base
+
+
+class DataSource:
+    """A ground-truth data source for fact verification.
+
+    Point :class:`Verifier` at *your company's* data instead of (or alongside)
+    the public KOSIS statistics catalog.
+
+        >>> sv.Verifier(provider="upstage", data=sv.DataSource.csv("budget.csv"))
+        >>> sv.Verifier(provider="upstage", data="reference.csv")   # str is inferred
+
+    Factories:
+        * :meth:`csv`   — a tabular reference file (``indicator,…,value[,operator]``).
+        * :meth:`docs`  — company documents (PDF/txt) searched semantically.
+        * :meth:`kosis` — the built-in public statistics catalog.
+    """
+
+    __slots__ = ("name", "config")
+
+    def __init__(self, name: str, config: dict):
+        self.name = name
+        self.config = config
+
+    @classmethod
+    def csv(cls, path: str, *, columns: dict | None = None) -> "DataSource":
+        """A company CSV of reference values (rows of ``indicator,…,value``).
+
+        Args:
+            path: Path to the CSV file.
+            columns: Optional mapping of your column names onto the expected
+                fields, e.g. ``{"value": "amount", "operator": "op"}``.
+        """
+        cfg: dict[str, Any] = {"csv_path": path}
+        if columns:
+            cfg["column_mapping"] = columns
+        return cls("custom_csv", cfg)
+
+    @classmethod
+    def docs(cls, path: str, *, chunk_size: int = 120,
+             embedding: dict | None = None) -> "DataSource":
+        """Company documents (PDF/txt/md) used as searchable ground truth."""
+        cfg: dict[str, Any] = {"docs_path": path, "chunk_size": chunk_size}
+        if embedding:
+            cfg["embedding"] = embedding
+        return cls("custom_docs", cfg)
+
+    @classmethod
+    def db(cls, dsn: str, *, table: str | None = None, query: str | None = None,
+           columns: dict | None = None, agentic: bool = False,
+           tables: list | None = None, use_embedding: str | bool | None = None,
+           embed_threshold: int | None = None) -> "DataSource":
+        """A company SQL database table of reference values.
+
+        Works with any SQLAlchemy DSN — SQLite, PostgreSQL, Snowflake, MySQL, … .
+        Needs the ``[db]`` extra (``pip install "structverify[db]"``); Snowflake
+        additionally needs ``snowflake-sqlalchemy``.
+
+        Args:
+            dsn: SQLAlchemy connection string, e.g.
+                ``"postgresql://user:pw@host/db"`` or
+                ``"snowflake://user:pw@account/DB/SCHEMA?warehouse=WH"``.
+            table: Table to read (schema-qualified if needed).
+            query: A full SQL query to run instead of ``SELECT * FROM table``.
+            columns: Map your column names onto the expected fields, e.g.
+                ``{"indicator": "NAME", "value": "AMOUNT"}``.
+            agentic: Fully-agentic mode for **raw transactional tables**. Instead of
+                assuming a tidy ``(indicator, value, …)`` table, the agent inspects
+                the schema and writes an aggregation ``SELECT`` per claim (read-only,
+                guarded) — so ``"total revenue = SUM(...)"`` is defined automatically,
+                no config needed. Use for row-level data (orders, events, ledgers).
+            tables: (agentic) Optional whitelist of tables to inspect. If omitted,
+                tables are auto-discovered from the connection's schema.
+        """
+        cfg: dict[str, Any] = {"dsn": dsn}
+        if table:
+            cfg["table"] = table
+        if query:
+            cfg["query"] = query
+        if columns:
+            cfg["column_mapping"] = columns
+        if agentic:
+            # 에이전틱 모드: 원시 테이블 스키마를 조사해 claim마다 집계 SQL을 자동 생성.
+            # 지표 정의(총 매출=SUM(...))를 사람이 config에 줄 필요 없음.
+            cfg["agentic"] = True
+            if tables:
+                cfg["tables"] = list(tables)
+        # 임베딩 의미검색 제어 (정돈형 소스). auto(기본)=규모 기반, true/false=명시.
+        if use_embedding is not None:
+            cfg["use_embedding"] = use_embedding
+        if embed_threshold is not None:
+            cfg["embed_threshold"] = int(embed_threshold)
+        return cls("custom_db", cfg)
+
+    @classmethod
+    def kosis(cls) -> "DataSource":
+        """The built-in public KOSIS statistics catalog."""
+        return cls("kosis", {})
+
+    @classmethod
+    def _coerce(cls, data: "DataSource | str | None") -> "DataSource | None":
+        """Accept a DataSource, a path string (type inferred by extension), or None."""
+        if data is None or isinstance(data, cls):
+            return data
+        if isinstance(data, str):
+            ext = os.path.splitext(data)[1].lower()
+            if ext == ".csv":
+                return cls.csv(data)
+            if ext in (".pdf", ".txt", ".md", ".docx"):
+                return cls.docs(data)
+            raise ValueError(f"cannot infer a DataSource from path {data!r}; use DataSource.csv/docs()")
+        raise TypeError(f"data must be a DataSource or path string, got {type(data).__name__}")
+
+    def _overlay(self) -> dict:
+        """The ``data_sources`` config fragment that enables just this source.
+
+        Emits a *copy* of ``self.config`` so callers (e.g. ``build_config``)
+        can layer defaults onto the overlay without mutating this DataSource.
+        """
+        return {
+            "data_sources": {
+                "enabled": [self.name],
+                "default_source": self.name,
+                self.name: dict(self.config),
+            }
+        }
+
+    def __repr__(self) -> str:
+        return f"<DataSource {self.name!r} {self.config}>"
+
+
+def build_config(
+    *,
+    provider: str | None = None,
+    api_key: str | None = None,
+    model: str | None = None,
+    embedding_provider: str | None = None,
+    embedding_api_key: str | None = None,
+    tolerance: float | None = None,
+    data: "DataSource | str | None" = None,
+    extra: dict | None = None,
+) -> dict[str, Any]:
+    """Build a full engine config from a few high-level knobs.
+
+    Starts from the packaged defaults (``config/default.yaml``) and overlays only
+    what you pass. ``api_key`` is injected directly (``_direct_api_key``) so no
+    environment variable is required. When ``embedding_provider`` is omitted it
+    mirrors ``provider`` (and reuses ``api_key`` for embeddings).
+
+    Args:
+        provider: LLM provider — ``"upstage"`` | ``"openai"`` | ``"gemini"`` | ``"hcx"``.
+        api_key: API key for the LLM provider. If omitted, the provider's
+            environment variable is used.
+        model: Override the provider's default chat model.
+        embedding_provider: Embedding provider (defaults to ``provider``).
+        embedding_api_key: Embedding key (defaults to ``api_key`` when the
+            embedding provider matches the LLM provider).
+        tolerance: Numeric comparison tolerance in percent.
+        data: Ground-truth source for fact verification — a :class:`DataSource`
+            or a path string. Defaults to the config's existing source (KOSIS).
+        extra: Any additional deep-merge overrides for the raw config.
+
+    Returns:
+        A config dict ready to hand to :class:`Verifier` or the pipeline.
+    """
+    from structverify.core.config_loader import load_config
+
+    cfg = copy.deepcopy(load_config())
+
+    llm = cfg.setdefault("llm", {})
+    if provider:
+        llm["provider"] = provider
+    if api_key:
+        llm["_direct_api_key"] = api_key
+    if model:
+        # LLMClient resolves models per tier (heavy/light/structured); a single
+        # requested model overrides every tier.
+        llm["models"] = {"heavy": model, "light": model, "structured": model}
+
+    emb = cfg.setdefault("embedding", {})
+    emb_prov = embedding_provider or provider
+    if emb_prov:
+        emb["provider"] = emb_prov
+    # Reuse the LLM key for embeddings only when the resolved embedding provider
+    # is the *same* as the LLM provider (not merely when it was left unset).
+    ek = embedding_api_key or (api_key if emb_prov == provider else None)
+    if ek:
+        emb["_direct_api_key"] = ek
+
+    if tolerance is not None:
+        cfg.setdefault("verification", {})["tolerance_percent"] = tolerance
+
+    source = DataSource._coerce(data)
+    if source is not None:
+        # A company source needs the same embedding provider/key for search.
+        src_overlay = source._overlay()
+        # docs/csv/db 모두 임베딩 검색(지표 방대 시)을 쓸 수 있으므로 embedding 주입.
+        if source.name in ("custom_docs", "custom_csv", "custom_db"):
+            # Fresh dict so we never alias (nor mutate) cfg["embedding"].
+            src_overlay["data_sources"][source.name].setdefault("embedding", dict(cfg["embedding"]))
+        # 에이전틱 DB 소스는 fetch 시 claim마다 SQL을 생성하므로 LLM 설정이 필요.
+        # (소스는 data_sources.custom_db config로 생성되어 최상위 llm에 접근 못 하므로 주입.)
+        if source.name == "custom_db" and source.config.get("agentic"):
+            src_overlay["data_sources"]["custom_db"].setdefault("llm", dict(cfg["llm"]))
+        _deep_merge(cfg, src_overlay)
+
+    if extra:
+        _deep_merge(cfg, extra)
+    return cfg
+
+
+# ── result objects ───────────────────────────────────────────────────────────
+
+class Result:
+    """One verified claim from a :class:`Report`.
+
+    Truthy when the claim was confirmed by the evidence
+    (``bool(result) == result.ok``).
+
+    Attributes:
+        verdict: ``"match"`` | ``"mismatch"`` | ``"unverifiable"``.
+        claim: The claim sentence that was checked.
+        reason: Natural-language explanation of the verdict.
+        confidence: Model confidence in ``[0, 1]``.
+        value: The official/reference value found in the evidence, if any.
+        source: Name of the evidence source (e.g. ``"KOSIS"``).
+        unit: Unit of ``value``.
+    """
+
+    __slots__ = ("verdict", "claim", "reason", "confidence", "value", "source", "unit")
+
+    def __init__(self, verdict, claim, reason, confidence, value, source, unit):
+        self.verdict = verdict
+        self.claim = claim
+        self.reason = reason
+        self.confidence = confidence
+        self.value = value
+        self.source = source
+        self.unit = unit
+
+    @classmethod
+    def _from(cls, res, claim) -> "Result":
+        ev = getattr(res, "evidence", None)
+        verdict = res.verdict.value if hasattr(res.verdict, "value") else str(res.verdict)
+        return cls(
+            verdict=verdict,
+            claim=getattr(claim, "claim_text", None),
+            reason=res.explanation,
+            confidence=res.confidence,
+            value=getattr(ev, "official_value", None) if ev else None,
+            source=getattr(ev, "source_name", None) if ev else None,
+            unit=getattr(ev, "unit", None) if ev else None,
+        )
+
+    @property
+    def ok(self) -> bool:
+        """True when the claim was confirmed (``verdict == "match"``)."""
+        return self.verdict == "match"
+
+    @property
+    def is_match(self) -> bool:
+        return self.verdict == "match"
+
+    @property
+    def is_mismatch(self) -> bool:
+        return self.verdict == "mismatch"
+
+    @property
+    def is_unverifiable(self) -> bool:
+        return self.verdict == "unverifiable"
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "verdict": self.verdict,
+            "ok": self.ok,
+            "claim": self.claim,
+            "reason": self.reason,
+            "confidence": self.confidence,
+            "value": self.value,
+            "source": self.source,
+            "unit": self.unit,
+        }
+
+    def __repr__(self) -> str:
+        mark = {"match": "✓", "mismatch": "✗", "unverifiable": "?"}.get(self.verdict, "?")
+        claim = (self.claim or "").strip()
+        if len(claim) > 60:
+            claim = claim[:57] + "…"
+        return f"<Result {mark} {self.verdict} ({self.confidence:.2f}) — {claim!r}>"
+
+
+class Report:
+    """The outcome of verifying a document — an iterable collection of :class:`Result`.
+
+    Truthy when no false claim was found (``bool(report) == report.ok``), so a
+    document can be gated with a single ``if``::
+
+        if sv.verify(text, provider="upstage"):
+            print("no false claims detected")
+    """
+
+    __slots__ = ("results", "summary", "raw")
+
+    def __init__(self, results: list[Result], summary: str | None = None, raw=None):
+        self.results = results
+        self.summary = summary
+        self.raw = raw  # the underlying VerificationReport, for power users
+
+    @classmethod
+    def _from(cls, vr) -> "Report":
+        claims_by_id = {c.claim_id: c for c in vr.claims}
+        # NB: build the list directly — never filter by truthiness here, since a
+        # mismatch Result is *falsy* and would be silently dropped.
+        results = [Result._from(r, claims_by_id.get(r.claim_id)) for r in vr.results]
+        return cls(results=results, summary=vr.summary, raw=vr)
+
+    @property
+    def matches(self) -> list[Result]:
+        return [r for r in self.results if r.is_match]
+
+    @property
+    def mismatches(self) -> list[Result]:
+        """Claims contradicted by the evidence (the ones worth acting on)."""
+        return [r for r in self.results if r.is_mismatch]
+
+    @property
+    def unverifiable(self) -> list[Result]:
+        return [r for r in self.results if r.is_unverifiable]
+
+    @property
+    def ok(self) -> bool:
+        """True when no claim was contradicted by the evidence."""
+        return not self.mismatches
+
+    passed = ok  # readability alias when used as ``report.passed``
+
+    @property
+    def all_match(self) -> bool:
+        """Stricter than :attr:`ok`: every claim was positively confirmed."""
+        return bool(self.results) and all(r.is_match for r in self.results)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "total": len(self.results),
+            "matches": len(self.matches),
+            "mismatches": len(self.mismatches),
+            "unverifiable": len(self.unverifiable),
+            "summary": self.summary,
+            "results": [r.to_dict() for r in self.results],
+        }
+
+    def __iter__(self) -> Iterator[Result]:
+        return iter(self.results)
+
+    def __len__(self) -> int:
+        return len(self.results)
+
+    def __getitem__(self, i) -> Result:
+        return self.results[i]
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+    def __repr__(self) -> str:
+        return (
+            f"<Report ok={self.ok} claims={len(self.results)} "
+            f"match={len(self.matches)} mismatch={len(self.mismatches)} "
+            f"unverifiable={len(self.unverifiable)}>"
+        )
+
+
+class Verdict:
+    """A conformance decision for one statement against a :class:`Ruleset`.
+
+    Truthy when the statement complies (``bool(verdict) == verdict.compliant``).
+
+    Attributes:
+        verdict: ``"compliant"`` | ``"violation"`` | ``"unverifiable"``.
+        claim: The statement that was checked.
+        article: The rule/article that was applied.
+        rule_value: The threshold the rule requires.
+        claim_value: The value asserted in the statement.
+        unit: Unit shared by ``rule_value`` and ``claim_value``.
+        reason: Natural-language explanation.
+    """
+
+    __slots__ = ("verdict", "claim", "article", "rule_value", "claim_value",
+                 "unit", "reason", "iterations")
+
+    def __init__(self, verdict, claim, article, rule_value, claim_value, unit,
+                 reason, iterations=None):
+        self.verdict = verdict
+        self.claim = claim
+        self.article = article
+        self.rule_value = rule_value
+        self.claim_value = claim_value
+        self.unit = unit
+        self.reason = reason
+        self.iterations = iterations   # rounds taken by the agent loop (None = one-shot)
+
+    @classmethod
+    def _from(cls, d: dict, claim: str) -> "Verdict":
+        return cls(
+            verdict=d.get("verdict", "unverifiable"),
+            claim=claim,
+            article=d.get("applicable_article"),
+            rule_value=d.get("rule_value"),
+            claim_value=d.get("claim_value"),
+            unit=d.get("unit"),
+            reason=d.get("explanation"),
+            iterations=d.get("iterations"),
+        )
+
+    @property
+    def compliant(self) -> bool:
+        """True when the statement satisfies the applicable rule."""
+        return self.verdict == "compliant"
+
+    ok = compliant
+
+    @property
+    def violated(self) -> bool:
+        """True when the statement breaks the applicable rule."""
+        return self.verdict == "violation"
+
+    @property
+    def is_unverifiable(self) -> bool:
+        return self.verdict == "unverifiable"
+
+    def __bool__(self) -> bool:
+        return self.compliant
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "verdict": self.verdict,
+            "compliant": self.compliant,
+            "claim": self.claim,
+            "article": self.article,
+            "rule_value": self.rule_value,
+            "claim_value": self.claim_value,
+            "unit": self.unit,
+            "reason": self.reason,
+            "iterations": self.iterations,
+        }
+
+    def __repr__(self) -> str:
+        mark = {"compliant": "✓", "violation": "✗", "unverifiable": "?"}.get(self.verdict, "?")
+        return (
+            f"<Verdict {mark} {self.verdict} "
+            f"rule={self.rule_value} claim={self.claim_value} {self.unit or ''}>".replace("  ", " ")
+        )
+
+
+# ── fact verification ────────────────────────────────────────────────────────
+
+class Verifier:
+    """A reusable fact-verification engine.
+
+    Configure a provider once, then call :meth:`verify` as many times as you
+    like. Verification checks numeric/factual claims in a document against a
+    configured data source (e.g. a statistics catalog).
+
+        >>> v = sv.Verifier(provider="upstage", api_key="up_...")
+        >>> report = v.verify("...")
+        >>> report.ok
+
+    Point it at company data with ``data`` (defaults to the built-in KOSIS
+    catalog)::
+
+        >>> sv.Verifier(provider="upstage", data=sv.DataSource.csv("budget.csv"))
+    """
+
+    def __init__(
+        self,
+        *,
+        provider: str | None = None,
+        api_key: str | None = None,
+        model: str | None = None,
+        embedding_provider: str | None = None,
+        embedding_api_key: str | None = None,
+        tolerance: float | None = None,
+        data: "DataSource | str | None" = None,
+        config: dict | None = None,
+    ):
+        self.config = config or build_config(
+            provider=provider,
+            api_key=api_key,
+            model=model,
+            embedding_provider=embedding_provider,
+            embedding_api_key=embedding_api_key,
+            tolerance=tolerance,
+            data=data,
+        )
+
+    async def averify(self, text: str) -> Report:
+        """Async: verify a block of text, returning a :class:`Report`."""
+        from structverify.core.pipeline import VerificationPipeline
+
+        vr = await VerificationPipeline(self.config).run(text, "text")
+        return Report._from(vr)
+
+    def verify(self, text: str) -> Report:
+        """Verify a block of text, returning a :class:`Report`."""
+        return _run(self.averify(text))
+
+    # ``check`` reads naturally too.
+    check = verify
+
+    async def averify_file(self, path: str) -> Report:
+        from structverify.retrieval.chunking import read_document
+
+        return await self.averify(read_document(path))
+
+    def verify_file(self, path: str) -> Report:
+        """Verify a document file (PDF/DOCX/txt), returning a :class:`Report`."""
+        return _run(self.averify_file(path))
+
+
+def verify(
+    text: str,
+    *,
+    provider: str | None = None,
+    api_key: str | None = None,
+    model: str | None = None,
+    **kwargs: Any,
+) -> Report:
+    """One-shot fact verification — the quickest way in.
+
+        >>> import structverify as sv
+        >>> report = sv.verify("...", provider="upstage", api_key="up_...")
+        >>> if report:
+        ...     print("no false claims")
+
+    Equivalent to ``Verifier(provider=..., ...).verify(text)``.
+    """
+    return Verifier(provider=provider, api_key=api_key, model=model, **kwargs).verify(text)
+
+
+# ── conformance (규정 준수) ───────────────────────────────────────────────────
+
+# Only lines that carry a measurement (a number + a recognizable unit) are worth
+# checking against a rulebook; headers/dates are skipped.
+_UNIT = re.compile(
+    r"㎍/?g|μg/?g|mg/?kg|CFU|ppm|㎎|㎍|㎖|℃|kcal|mg|kg|mL|mL당|g당|g\b|%|"
+    r"원|개|명|건|시간|일|개월|년|회|㎡|배"
+)
+
+
+class Ruleset:
+    """A rulebook you bring yourself — a PDF/txt of regulations, standards, or
+    internal policy — that statements can be checked against for compliance.
+
+    The rulebook is chunked per article and embedded once; each
+    :meth:`check` semantically retrieves the applicable article(s) and returns a
+    deterministic :class:`Verdict`.
+
+        >>> rules = sv.Ruleset.from_file("safety_standard.pdf", provider="upstage")
+        >>> rules.check("총납 함량은 120mg/kg으로 측정되었다").compliant
+        False
+        >>> len(rules)          # number of indexed articles
+        10
+
+    For a **large** rulebook, enable the ReAct agent loop so retrieval becomes
+    adaptive (search → judge → reformulate → search again) instead of a single
+    top-k shot::
+
+        >>> rules = sv.Ruleset.from_file("big_rulebook.pdf", provider="upstage", agent=True)
+        >>> v = rules.check("…"); v.iterations      # rounds the agent took
+    """
+
+    def __init__(self, ds, config: dict, chunks: int, name: str | None = None,
+                 *, agent: bool = False):
+        self._ds = ds
+        self._config = config
+        self._chunks = chunks
+        self.name = name
+        self._use_agent = agent
+
+    # -- construction --------------------------------------------------------
+
+    @classmethod
+    async def afrom_file(
+        cls,
+        path: str,
+        *,
+        provider: str | None = None,
+        api_key: str | None = None,
+        embedding_provider: str | None = None,
+        embedding_api_key: str | None = None,
+        tolerance: float | None = None,
+        chunk_size: int = 120,
+        name: str | None = None,
+        agent: bool = False,
+    ) -> "Ruleset":
+        """Async: build a ruleset by indexing a regulation file (PDF/txt/md)."""
+        from structverify.retrieval.custom_docs_source import CustomDocsDataSource
+
+        config = build_config(
+            provider=provider,
+            api_key=api_key,
+            embedding_provider=embedding_provider,
+            embedding_api_key=embedding_api_key,
+            tolerance=tolerance,
+        )
+        ds = CustomDocsDataSource(
+            docs_path=path, chunk_size=chunk_size, embedding=config["embedding"],
+        )
+        n = await ds.build_index()
+        return cls(ds, config, n, name=name or os.path.basename(path), agent=agent)
+
+    @classmethod
+    def from_file(cls, path: str, **kwargs: Any) -> "Ruleset":
+        """Build a ruleset by indexing a regulation file (PDF/txt/md)."""
+        return _run(cls.afrom_file(path, **kwargs))
+
+    @classmethod
+    async def afrom_text(cls, text: str, **kwargs: Any) -> "Ruleset":
+        """Async: build a ruleset from an in-memory rulebook string."""
+        tmpdir = tempfile.mkdtemp(prefix="sv_ruleset_")
+        path = os.path.join(tmpdir, "rules.txt")
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(text)
+        kwargs.setdefault("name", "inline-rules")
+        return await cls.afrom_file(path, **kwargs)
+
+    @classmethod
+    def from_text(cls, text: str, **kwargs: Any) -> "Ruleset":
+        """Build a ruleset from an in-memory rulebook string."""
+        return _run(cls.afrom_text(text, **kwargs))
+
+    # -- checking ------------------------------------------------------------
+
+    async def acheck(
+        self, statement: str, *, top_k: int = 5, agent: bool | None = None,
+    ) -> Verdict:
+        """Async: check one statement for compliance, returning a :class:`Verdict`.
+
+        Set ``agent=True`` (or construct the ruleset with ``agent=True``) to run
+        the adaptive ReAct loop instead of a single retrieval — worthwhile for a
+        large rulebook where the applicable article may not be in the first
+        top-k results.
+        """
+        use_agent = self._use_agent if agent is None else agent
+        if use_agent:
+            from structverify.agent.conformance_agent import ConformanceAgent
+
+            d = await ConformanceAgent(
+                self._ds, self._config, top_k=top_k,
+            ).check(statement)
+            return Verdict._from(d, statement)
+
+        # one-shot: retrieve top-k once, then judge
+        from structverify.verification.conformance import judge_conformance
+
+        cands = await self._ds.search_catalog(statement, top_k=top_k)
+        articles: list[str] = []
+        for c in cands:
+            cid = c.get("id")
+            if cid is None:
+                continue
+            ev = await self._ds.fetch_evidence(cid)
+            if ev and ev.get("text"):
+                articles.append(ev["text"])
+        d = await judge_conformance(statement, "\n---\n".join(articles), self._config)
+        return Verdict._from(d, statement)
+
+    def check(self, statement: str, *, top_k: int = 5, agent: bool | None = None) -> Verdict:
+        """Check one statement for compliance, returning a :class:`Verdict`."""
+        return _run(self.acheck(statement, top_k=top_k, agent=agent))
+
+    async def acheck_document(
+        self, text: str, *, top_k: int = 5, agent: bool | None = None,
+    ) -> list[Verdict]:
+        """Async: check every measurement line in a document."""
+        lines = [
+            ln.strip() for ln in text.splitlines()
+            if ln.strip() and any(ch.isdigit() for ch in ln) and _UNIT.search(ln)
+        ]
+        out: list[Verdict] = []
+        for ln in lines:
+            out.append(await self.acheck(ln, top_k=top_k, agent=agent))
+        return out
+
+    def check_document(
+        self, text: str, *, top_k: int = 5, agent: bool | None = None,
+    ) -> list[Verdict]:
+        """Check every measurement line in a document for compliance.
+
+        Returns one :class:`Verdict` per measurement line found.
+        """
+        return _run(self.acheck_document(text, top_k=top_k, agent=agent))
+
+    def check_file(self, path: str, *, top_k: int = 5, agent: bool | None = None) -> list[Verdict]:
+        """Check every measurement line in a document file (PDF/txt)."""
+        from structverify.retrieval.chunking import read_document
+
+        return self.check_document(read_document(path), top_k=top_k, agent=agent)
+
+    def __len__(self) -> int:
+        return self._chunks
+
+    def __repr__(self) -> str:
+        return f"<Ruleset {self.name!r} articles={self._chunks}>"