xtremeparse 0.1.0__py3-none-any.whl

xtremeparse/__init__.py

@@ -0,0 +1,34 @@
+"""XtremeParse: extreme-concurrency structured extraction — chunk, route, fan out, self-correct."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from xtremeparse.contracts import (
+    AgentResult,
+    AgentRunner,
+    ExtractionResult,
+    Issue,
+    JSONSchema,
+    Trace,
+    Validator,
+)
+from xtremeparse.extractor import Extractor
+from xtremeparse.scheduling import TaskScheduler, report_tokens, scheduler_from_spec
+
+try:
+    __version__ = version('xtremeparse')
+except PackageNotFoundError:
+    __version__ = '0.1.0'
+
+__all__ = [
+    'Extractor',
+    'AgentResult',
+    'AgentRunner',
+    'ExtractionResult',
+    'Issue',
+    'JSONSchema',
+    'Trace',
+    'Validator',
+    'TaskScheduler',
+    'report_tokens',
+    'scheduler_from_spec',
+]

xtremeparse/chunking.py

@@ -0,0 +1,83 @@
+"""Deterministic three-tier chunker: markdown structure, sentence
+punctuation, character windows.
+
+The same input always yields the same chunks, every chunk is an exact
+substring of the (newline-normalized) input in reading order, and any
+input — including a single line without punctuation — yields chunks.
+Chunk ids are list positions.
+"""
+
+from __future__ import annotations
+
+import re
+
+_HEADING = re.compile(r'^#{1,6}\s')
+_LIST_ITEM = re.compile(r'^\s*(?:[-*+]+\s+|•\s*|\d+[、)]\s*|\d+\.\s+)')
+_TABLE_ROW = re.compile(r'^\s*\|')
+# Sentence enders, CJK and latin; '.' only when not followed by a digit so
+# dates like 2015.3 never split.
+_SENTENCE_END = re.compile(r'(?<=[。．！？；!?;])|(?<=\.)(?!\d)')
+
+MAX_CHARS = 250
+
+
+def normalize_newlines(text: str) -> str:
+    """Owned at extraction entry: chunks and the shared prompt prefix
+    must agree on newlines."""
+    return text.replace('\r\n', '\n').replace('\r', '\n')
+
+
+def chunk_text(text: str, *, max_chars: int = MAX_CHARS) -> list[str]:
+    """Split text into chunks, numbered by position.
+
+    Tier 1 splits on structure: headings open blocks that absorb the plain
+    lines after them, list items and table rows stand alone, blank lines
+    end paragraphs. Tier 2 sentence-splits oversized blocks and greedily
+    packs fragments up to ``max_chars``. Tier 3 hard-slices whatever still
+    exceeds the ceiling (dense text without punctuation). Every chunk is
+    at most ``max_chars`` long.
+    """
+    if not (text := normalize_newlines(text)).strip():
+        return []
+    return [c for block in _blocks(text) for c in _pack(_SENTENCE_END.split(block), max_chars)]
+
+
+def _blocks(text: str) -> list[str]:
+    blocks, para = [], []
+
+    def flush():
+        if para:
+            blocks.append('\n'.join(para))
+            para.clear()
+
+    for line in text.split('\n'):
+        if _HEADING.match(line):
+            flush()
+            para.append(line)
+        elif not line.strip():
+            flush()
+        elif _LIST_ITEM.match(line) or _TABLE_ROW.match(line):
+            flush()
+            blocks.append(line)
+        else:
+            para.append(line)
+    flush()
+    return blocks
+
+
+def _pack(pieces: list[str], max_chars: int) -> list[str]:
+    chunks, current = [], ''
+    for piece in pieces:
+        if len(piece) > max_chars:
+            if current:
+                chunks.append(current)
+                current = ''
+            chunks.extend(piece[i:i + max_chars] for i in range(0, len(piece), max_chars))
+        elif len(current) + len(piece) > max_chars:
+            chunks.append(current)
+            current = piece
+        else:
+            current += piece
+    if current:
+        chunks.append(current)
+    return chunks

xtremeparse/contracts.py

@@ -0,0 +1,117 @@
+"""Neutral contracts between xtremeparse and the host application.
+
+The library never imports a schema vendor, an agent framework, or a
+validator. Everything crosses the border as plain data: JSON Schema in,
+JSON-shaped dict out, issues and agent calls behind the protocols below.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Protocol, Sequence, runtime_checkable
+
+# A plain JSON Schema mapping (``schema.to_json_schema()`` output, or any
+# hand-written schema with the same shape).
+JSONSchema = dict[str, Any]
+
+
+@runtime_checkable
+class Issue(Protocol):
+    """A validation problem found in extracted data.
+
+    Structural protocol: any object with these attributes satisfies it,
+    zero adapter code. ``expected``/``got`` are optional free-form context
+    (hosts pass lists for enums, arbitrary values, sentinels for absent).
+    """
+
+    path: str
+    message: str
+    code: str
+    expected: object
+    got: object
+
+
+# Validates complete extracted data, returns the issues the host considers
+# error-level. Feeding only errors is the host's severity policy: the
+# correction loop retries whatever it receives.
+Validator = Callable[[dict], Sequence[Issue]]
+
+
+@dataclass
+class AgentResult:
+    """One agent turn's outcome.
+
+    ``data`` is already coerced to the requested ``result_schema`` by the
+    adapter (e.g. PydanticAI structured output). ``history`` is the opaque
+    message history for multi-turn continuation; the library passes it back
+    verbatim on correction rounds. Usage/cost telemetry is deliberately not
+    here — the adapter layer instruments its own agent calls.
+    """
+
+    data: Any
+    history: list
+
+
+@runtime_checkable
+class AgentRunner(Protocol):
+    """The single agent-call abstraction the library owns.
+
+    The host adapts this to its agent framework (PydanticAI today, anything
+    else tomorrow). Prompt layout is frozen for cache reasons:
+    ``instructions`` carries the unit's semantic card and ``content`` the
+    shared, byte-identical payload (full text + full schema) that makes the
+    provider's KV cache hit across every call of one extraction;
+    ``scope`` carries this call's private slice — the routed chunks of one
+    group (None for the router). On ``history`` rounds the transcript
+    already carries the card and scope, so the caller passes ``''`` for
+    both — re-sending them would re-bill the same text, and only the
+    per-round ``feedback`` is fresh. ``result_schema`` is the JSON Schema the
+    returned ``data`` must satisfy; ``tools``/``history``/``feedback``
+    serve the multi-turn correction loop.
+    """
+
+    async def run(
+        self,
+        *,
+        instructions: str,
+        result_schema: JSONSchema,
+        content: str,
+        scope: Optional[str] = None,
+        tools: Optional[list] = None,
+        history: Optional[list] = None,
+        feedback: Optional[Sequence[Issue]] = None,
+    ) -> AgentResult:
+        ...
+
+
+@dataclass
+class Trace:
+    """Orchestration record: what was chunked, routed, run and retried.
+
+    Populated by the pipeline stages; read by eval suites and telemetry.
+    Token/latency accounting of agent calls stays with the adapter — this
+    trace records orchestration events only. ``prompts`` marks each
+    prompt slot 'default' or with a short hash of the host's override
+    template (see prompting.provenance) — regressions stay attributable
+    to whose prompt produced them.
+    """
+
+    chunks: list = field(default_factory=list)
+    router: Optional[dict] = None
+    groups: list = field(default_factory=list)
+    corrections: list = field(default_factory=list)
+    prompts: dict = field(default_factory=dict)
+
+
+@dataclass
+class ExtractionResult:
+    """Extraction never raises on bad data — it reports.
+
+    ``data`` is the best-effort merged result (missing pieces stay absent),
+    ``issues`` the unresolved error-level issues from the last validation,
+    both lenient by design. Strictness is the caller's policy.
+    """
+
+    data: dict
+    issues: list
+    trace: Trace

xtremeparse/corrections.py

@@ -0,0 +1,166 @@
+"""Correction loop: whole-data validation, issue routing, bounded re-runs.
+
+The injected validator defines severity — whatever it feeds is retried.
+Issues route back to the specialist call that owns their path (per-item
+calls only when the item index is derivable), and re-runs carry the call's
+conversation history plus the routed feedback. Stops on clean, budget
+(default 2 rounds), or no progress (issue paths identical to the previous
+round). Never raises on bad data; unresolved issues return with the data.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from xtremeparse.contracts import AgentRunner, Validator
+from xtremeparse.paths import resolve, resolve_list
+from xtremeparse.executor import Call, Execution, dispatch_specialist, values_from_calls
+from xtremeparse.merge import merge
+from xtremeparse.prompting import json_len
+from xtremeparse.scheduling import TaskScheduler
+from xtremeparse.units import MISC
+
+MAX_ROUNDS = 2
+
+
+@dataclass
+class Round:
+    """One correction round's trace material."""
+
+    unit_path: str
+    item: Optional[int]
+    issue_paths: list
+
+
+async def correct(runner: AgentRunner, execution: Execution, *, validator: Validator,
+                  payload: str, scheduler: TaskScheduler,
+                  max_rounds: int = MAX_ROUNDS,
+                  specialist_instructions: str = None) -> tuple:
+    """Re-run failing calls with feedback until clean, budgeted, or
+    stuck. Returns ``(data, issues, rounds)`` — always lenient. Call
+    results mutate in place; re-merge from ``execution.calls`` rather
+    than the now-stale ``execution.values``. ``specialist_instructions``
+    must be the same override the first round ran with — a correction
+    round continues that call's conversation history."""
+    calls = execution.calls
+    data = merge(values_from_calls(calls))
+    issues = list(validator(data) or [])
+    rounds, seen = [], None
+    for _ in range(max_rounds):
+        paths = {i.path for i in issues}
+        if not issues or paths == seen:
+            break
+        seen = paths
+        routed = _route(calls, issues)
+        if not routed:
+            break
+        rounds.extend(Round(call.unit.path, call.item, [i.path for i in feedback])
+                      for call, feedback in routed)
+        tasks = [await dispatch_specialist(
+            runner, call.unit, payload=payload, scope=call.scope,
+            whole=call.strategy == 'whole', scheduler=scheduler,
+            specialist_instructions=specialist_instructions,
+            history=call.result.history if call.result else None,
+            feedback=feedback)
+            for call, feedback in routed]
+        for (call, _), result in zip(routed, await asyncio.gather(*tasks)):
+            call.result = result
+        data = merge(values_from_calls(calls))
+        issues = list(validator(data) or [])
+    return data, issues, rounds
+
+
+def _route(calls: list, issues: list) -> list:
+    """Map issues to owning calls. Longest unit path wins; per-item calls
+    match only their item; $misc is the fallback for unmatched paths."""
+    grouped = {}
+    for issue in issues:
+        if call := _owner(calls, issue.path):
+            grouped.setdefault(id(call), (call, []))[1].append(issue)
+    return list(grouped.values())
+
+
+def _owner(calls: list, path: str):
+    covering = [c for c in calls if c.unit.path != MISC and _under(path, c.unit.path)]
+    exact = [c for c in covering if c.item is None and not c.batch
+             or c.item is not None and _under(path, f'{c.unit.path}[{c.item}]')
+             or c.batch and (_item_index(path, c.unit.path) or -1) in c.batch]
+    pool = exact or [c for c in calls if c.unit.path == MISC]
+    return max(pool, key=lambda c: len(c.unit.path), default=None)
+
+
+def _item_index(path: str, unit_path: str):
+    m = re.fullmatch(rf'{re.escape(unit_path)}\[(\d+)\](\..*)?', path)
+    return int(m.group(1)) if m else None
+
+
+def _under(path: str, root: str) -> bool:
+    """``path`` is ``root`` itself or a proper child of it."""
+    return path == root or path.startswith(f'{root}.') or path.startswith(f'{root}[')
+
+
+def item_chars(budgets: dict, data: dict) -> dict:
+    """Per budgeted path: ``[(key, arranged, chars)]`` — one entry per
+    item for lists, one for the whole value otherwise, each carrying
+    its own arranged budget (a lone number covers every item; a short
+    list's last value covers items beyond it). The counting surface for
+    budget reads (trace, eval audits); the unit is the compact
+    serialized item JSON (keys and punctuation included) — exactly what
+    a specialist types and pays decode for. Overruns are ACCEPTED,
+    never retried: a retry costs a full extra decode, the very thing
+    budgets exist to save — budgets shape batch scheduling only."""
+    out = {}
+    for path, arranged in budgets.items():
+        if (value := resolve(data, path)) is None:
+            continue
+        values = arranged if isinstance(arranged, list) else [arranged]
+        entries = []
+        for i, item in (enumerate(value) if isinstance(value, list)
+                        else [(None, value)]):
+            budget = values[i] if i is not None and i < len(values) else values[-1]
+            entries.append((f'{path}[{i}]' if i is not None else path,
+                            budget, json_len(item)))
+        out[path] = entries
+    return out
+
+
+@dataclass
+class _CountIssue:
+    """A routed item count the merged data does not honour — typically a
+    whole-array call that collapsed instances into fewer entries."""
+
+    path: str
+    code: str = 'item_count'
+    message: str = ''
+    expected: int = None
+    got: int = None
+
+
+def count_issues(counts: dict, data: dict) -> list:
+    """The router's declared counts (map-validated ground truth) against
+    the merged arrays. A short array means instances were collapsed or
+    dropped — silent to schema validation (nothing declares minItems).
+    Items concatenate in item-index order, so a short array is missing
+    its tail: each missing index becomes its own issue and routes to the
+    call that owns it (a batch member or a single). One that survives a
+    retry stops via the no-progress rule."""
+    issues = []
+    for path, declared in counts.items():
+        actual = len(resolve_list(data, path))
+        if actual < declared:
+            issues += [_CountIssue(
+                f'{path}[{i}]', expected=declared, got=actual,
+                message=f'{path} is missing item {i} of {declared} — the '
+                        f'array holds {actual}; return every instance as '
+                        'its own entry, without splitting or duplicating')
+                       for i in range(actual, declared)]
+        elif actual > declared:
+            issues.append(_CountIssue(
+                path, expected=declared, got=actual,
+                message=f'declared {declared} items but the array holds '
+                        f'{actual} — merge the duplicates'))
+    return issues
+

xtremeparse/evalkit.py

@@ -0,0 +1,43 @@
+"""Eval support: plain-data reads over the orchestration trace.
+
+The lib keeps the reads its shipped evaluators (the ``evals`` extra)
+need: the executor's calling conventions (per_item_budgets) and the
+router's contract (router_overlap). Hosts own their general eval
+tooling — digest projections, anchor checks, assertion DSLs are each
+host's selection.
+"""
+
+from __future__ import annotations
+
+
+def per_item_budgets(groups: list) -> dict:
+    """Trace groups → the per-path budget map ``item_chars`` reads: one
+    number or the item-index-ordered list."""
+    whole, by_item = {}, {}
+    for g in groups:
+        if not g.get('budget'):
+            continue
+        items = g.get('batch') or ([g['item']] if g['item'] is not None else None)
+        if items is None:  # whole-array call: its list is document-ordered
+            whole[g['unit']] = g['budget']
+            continue
+        values = g['budget'] if isinstance(g['budget'], list) else None
+        for k, i in enumerate(items):
+            by_item.setdefault(g['unit'], {})[i] = values[k] if values else g['budget']
+    return whole | {unit: [items[i] for i in sorted(items)]
+                    for unit, items in by_item.items()}
+
+
+def router_overlap(router, groups: list) -> tuple:
+    """(overlap, items_lost) between the router's assignments and the
+    executed calls; only per-item executions are held to item presence
+    (whole-strategy coalescing is legitimate)."""
+    assignments = router['assignments'] if router else []
+    raw = sum(len(a['chunks']) for a in assignments)
+    present = {(g['unit'], i) for g in groups
+               for i in (g.get('batch') or [g['item']])}
+    per_item_units = {g['unit'] for g in groups if g['strategy'] == 'per-item'}
+    declared = {(a['unit'], a.get('item')) for a in assignments
+                if a['unit'] in per_item_units}
+    return (raw - sum(len(g['chunk_ids']) for g in groups),
+            len(declared - present))

xtremeparse/evals.py

@@ -0,0 +1,97 @@
+"""pydantic-evals adapters over the trace reads — install the ``evals``
+extra (``pip install xtremeparse[evals]``). The evaluators accept any
+output carrying ``.trace`` and ``.data`` the way ``ExtractionResult``
+does; hosts keep their domain evaluators beside these.
+"""
+
+from __future__ import annotations
+
+import json
+
+from pydantic_evals.evaluators import Evaluator, EvaluatorContext, EvaluationReason
+
+from xtremeparse.corrections import item_chars
+from xtremeparse.evalkit import per_item_budgets, router_overlap
+from xtremeparse.judging import JUDGE_PLACEHOLDERS, judge
+from xtremeparse.prompting import check_placeholders
+
+
+class RouterOverlap(Evaluator):
+    """Invariant tripwire: router validation makes overlap and phantom
+    items structurally impossible — a red here means the router contract
+    regressed, not a flaky model."""
+
+    def evaluate(self, ctx: EvaluatorContext):
+        overlap, lost = router_overlap(ctx.output.trace.router,
+                                       ctx.output.trace.groups)
+        return EvaluationReason(lost == 0, f'overlap={overlap}, items_lost={lost}')
+
+
+class BudgetFit(Evaluator):
+    """Allocation audit: the model ARRANGES each budget — its estimate
+    of the characters an item's output JSON will run to, resolved by
+    code against the routed material — so actuals should land near
+    the arranged number. The lower edge is loose on purpose: an idle
+    estimate on a naturally short item is harmless (output runs at
+    natural size either way). The upper edge flags arrangements so
+    far off the router clearly wasn't counting. Per item: a mean
+    would hide spread."""
+
+    BAND = (0.4, 2.0)
+
+    def evaluate(self, ctx: EvaluatorContext):
+        ratios, wild = {}, []
+        budgets = per_item_budgets(ctx.output.trace.groups)
+        for path, entries in item_chars(budgets, ctx.output.data).items():
+            unit = path.rsplit('.', 1)[-1]
+            judged = [e for e in entries if e[1] and e[2]]  # budgeted, non-empty
+            if rs := [round(chars / budget, 2) for _, budget, chars in judged]:
+                ratios[unit] = f'{min(rs)}' if len(rs) == 1 else f'{min(rs)}-{max(rs)}'
+            wild += [key.rsplit('.', 1)[-1] for key, budget, chars in judged
+                     if not self.BAND[0] <= chars / budget <= self.BAND[1]]
+        return EvaluationReason(
+            not wild, f'act/budget {ratios or "no budgets declared"}'
+                      + (f', wild: {wild}' if wild else ''))
+
+
+class RubricJudge(Evaluator):
+    """One rubric call through an injected AgentRunner (see
+    xtremeparse.judging) — the judge runs on whatever framework the
+    host adapted, where pydantic-evals' own LLMJudge ties the harness
+    to a pydantic-ai model. ``source`` is the judged material's
+    document, held at construction; ``output_of`` projects the case
+    output into what the rubric asks about (e.g. a digest projection
+    for containment questions) — see docs/prompting.md for the
+    measured judge guidance. The judge's own model settings are
+    recommendations carried at the adapter."""
+
+    def __init__(self, runner, rubric: str, source: str = '', *,
+                 output_of=None, instructions: str = None):
+        if instructions is not None:
+            check_placeholders(instructions, JUDGE_PLACEHOLDERS, 'instructions')
+        self.runner = runner
+        self.rubric = rubric
+        self.source = source
+        self.output_of = output_of
+        self.instructions = instructions
+
+    async def evaluate(self, ctx: EvaluatorContext):
+        output = _text(self.output_of(ctx.output) if self.output_of
+                       else ctx.output)
+        verdict = await judge(self.runner, rubric=self.rubric,
+                              source=self.source, output=output,
+                              instructions=self.instructions)
+        return EvaluationReason(verdict.ok, verdict.reason)
+
+
+def _text(value) -> str:
+    """Stable judge-facing text: an ExtractionResult-shaped value is
+    judged by its data; a plain string stays verbatim (JSON-escaping a
+    document-sized string would bury its structure); the rest
+    serializes compactly (``default=str`` absorbs harness objects like
+    Path)."""
+    if hasattr(value, 'data'):
+        value = value.data
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, default=str)