nomark-engine 0.1.0__py3-none-any.whl

nomark_engine/__init__.py

@@ -0,0 +1,51 @@
+"""NOMARK Engine — open-core agent outcome quality resolver."""
+
+__version__ = "0.1.0"
+
+from .schema import (
+    Context, Outcome, RequestType, PatternType, RubricStage, SignalType, Scope,
+    ContextCounts, OutcomeCounts,
+    SigPref, SigMap, SigAsn, SigMeta, SigRub,
+    LedgerEntryMeta, LedgerEntryPref, LedgerEntryMap, LedgerEntryAsn, LedgerEntryRub,
+    LedgerEntry,
+    parse_ledger_entry,
+)
+from .decay import compute_decay, effective_weight
+from .ledger import (
+    parse_ledger, write_ledger, parse_ledger_line, format_ledger_line,
+    count_by_type, check_capacity, estimate_tokens,
+    ENTRY_CAPS, TOTAL_CAP,
+)
+from .utility import utility_score, is_protected, prune_to_capacity
+from .classifier import classify, ClassificationResult, InputTier
+from .resolver import (
+    scope_specificity, scope_matches, resolver_score,
+    resolve_dimension, match_meaning_maps, find_defaults,
+    create_resolver, Resolver, ResolverConfig, ResolverResult,
+    DimensionResult, MeaningMapMatch, DefaultMatch, ScoredPref, ScoringFactors, ResolverMeta,
+)
+
+__all__ = [
+    # Schema types
+    "Context", "Outcome", "RequestType", "PatternType", "RubricStage", "SignalType", "Scope",
+    "ContextCounts", "OutcomeCounts",
+    "SigPref", "SigMap", "SigAsn", "SigMeta", "SigRub",
+    "LedgerEntryMeta", "LedgerEntryPref", "LedgerEntryMap", "LedgerEntryAsn", "LedgerEntryRub",
+    "LedgerEntry",
+    "parse_ledger_entry",
+    # Decay
+    "compute_decay", "effective_weight",
+    # Ledger
+    "parse_ledger", "write_ledger", "parse_ledger_line", "format_ledger_line",
+    "count_by_type", "check_capacity", "estimate_tokens",
+    "ENTRY_CAPS", "TOTAL_CAP",
+    # Utility
+    "utility_score", "is_protected", "prune_to_capacity",
+    # Classifier
+    "classify", "ClassificationResult", "InputTier",
+    # Resolver
+    "scope_specificity", "scope_matches", "resolver_score",
+    "resolve_dimension", "match_meaning_maps", "find_defaults",
+    "create_resolver", "Resolver", "ResolverConfig", "ResolverResult",
+    "DimensionResult", "MeaningMapMatch", "DefaultMatch", "ScoredPref", "ScoringFactors", "ResolverMeta",
+]

nomark_engine/classifier.py

@@ -0,0 +1,134 @@
+"""Input classification (MEE Spec Section 1.1).
+
+Ports packages/engine/src/classifier.ts.
+
+Tier 0: Pass-through — already resolved. Confirmations, selections, JSON, exit codes.
+Tier 1: Routing — match to established pattern. Skill invocations, continuations, corrections.
+Tier 2: Extraction — full intent reconstruction through resolver + gate.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+
+InputTier = Literal[0, 1, 2]
+
+
+@dataclass(frozen=True)
+class ClassificationResult:
+    tier: InputTier
+    reason: str
+
+
+class ClassifierRule(Protocol):
+    tier: InputTier
+    reason: str
+
+    def test(self, input: str) -> bool: ...
+
+
+@dataclass(frozen=True)
+class _Rule:
+    tier: InputTier
+    reason: str
+    _test: object  # callable
+
+    def test(self, input: str) -> bool:
+        return self._test(input)  # type: ignore[operator]
+
+
+def _is_confirmation(s: str) -> bool:
+    return bool(re.match(
+        r"^(y|yes|no|n|ok|done|skip|cancel|approve|reject|confirm|confirmed)$",
+        s.strip(), re.IGNORECASE,
+    ))
+
+
+def _is_numeric(s: str) -> bool:
+    return bool(re.match(r"^[0-9]+$", s.strip()))
+
+
+def _is_json(s: str) -> bool:
+    t = s.strip()
+    if not (t.startswith("{") or t.startswith("[")):
+        return False
+    try:
+        json.loads(s)
+        return True
+    except (json.JSONDecodeError, ValueError):
+        return False
+
+
+def _is_exit(s: str) -> bool:
+    return bool(re.match(r"^(exit|quit|bye|stop)\s*$", s.strip(), re.IGNORECASE))
+
+
+def _is_hash(s: str) -> bool:
+    return bool(re.match(r"^[a-f0-9]{6,40}$", s.strip(), re.IGNORECASE))
+
+
+def _is_skill(s: str) -> bool:
+    return bool(re.match(r"^/\w", s.strip()))
+
+
+def _is_continuation(s: str) -> bool:
+    return bool(re.match(
+        r"^(continue|go ahead|proceed|next|keep going|resume)\s*$",
+        s.strip(), re.IGNORECASE,
+    ))
+
+
+def _is_correction(s: str) -> bool:
+    t = s.strip()
+    return bool(
+        re.match(r"^(no[,.]?\s+(not that|wrong|different|the other|I meant))", t, re.IGNORECASE)
+        or re.match(r"^(actually|wait|hold on|scratch that|never\s?mind)", t, re.IGNORECASE)
+    )
+
+
+def _is_letter_selection(s: str) -> bool:
+    t = s.strip()
+    return 0 < len(t) <= 3 and bool(re.match(r"^[a-z]$", t, re.IGNORECASE))
+
+
+_TIER_0_RULES: list[_Rule] = [
+    _Rule(0, "confirmation", _is_confirmation),
+    _Rule(0, "numeric_selection", _is_numeric),
+    _Rule(0, "json_data", _is_json),
+    _Rule(0, "exit_signal", _is_exit),
+    _Rule(0, "hash_or_id", _is_hash),
+]
+
+_TIER_1_RULES: list[_Rule] = [
+    _Rule(1, "skill_invocation", _is_skill),
+    _Rule(1, "continuation", _is_continuation),
+    _Rule(1, "correction", _is_correction),
+    _Rule(1, "letter_selection", _is_letter_selection),
+]
+
+
+def classify(input: str, custom_rules: list[_Rule] | None = None) -> ClassificationResult:
+    """Classify input into Tier 0 (pass-through), Tier 1 (routing), or Tier 2 (extraction)."""
+    trimmed = input.strip()
+
+    if not trimmed:
+        return ClassificationResult(tier=0, reason="empty_input")
+
+    if custom_rules:
+        for rule in custom_rules:
+            if rule.test(trimmed):
+                return ClassificationResult(tier=rule.tier, reason=rule.reason)
+
+    for rule in _TIER_0_RULES:
+        if rule.test(trimmed):
+            return ClassificationResult(tier=rule.tier, reason=rule.reason)
+
+    for rule in _TIER_1_RULES:
+        if rule.test(trimmed):
+            return ClassificationResult(tier=rule.tier, reason=rule.reason)
+
+    return ClassificationResult(tier=2, reason="substantive_input")

nomark_engine/decay.py

@@ -0,0 +1,46 @@
+"""Continuous decay computation (MEE Spec Section 8).
+
+Ports packages/engine/src/decay.ts.
+
+Base: max(0.1, 0.98^(days/30))
+Contradiction acceleration: decay * 0.85 when recent_contradictions >= 2
+Reinforcement recovery: decay * 1.1 (capped 1.0) when reinforced within 7 days
+Floor: 0.1 — never total erasure
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def compute_decay(
+    last_date: str,
+    _contradictions: int,
+    recent_contradictions: int,
+    recent_reinforcement: bool,
+    now: datetime | None = None,
+) -> float:
+    if now is None:
+        now = datetime.now(timezone.utc)
+
+    last = datetime.fromisoformat(last_date)
+    if last.tzinfo is None:
+        last = last.replace(tzinfo=timezone.utc)
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+
+    days_since_last = max(0.0, (now - last).total_seconds() / 86400)
+
+    decay = max(0.1, 0.98 ** (days_since_last / 30))
+
+    if recent_contradictions >= 2:
+        decay = max(0.1, decay * 0.85)
+
+    if recent_reinforcement:
+        decay = min(1.0, decay * 1.1)
+
+    return round(decay * 1000) / 1000
+
+
+def effective_weight(w: float, decay: float) -> float:
+    return round(w * decay * 1000) / 1000

nomark_engine/ledger.py

@@ -0,0 +1,91 @@
+"""Ledger JSONL parser/writer with capacity constraints.
+
+Ports packages/engine/src/ledger.ts.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from .schema import LedgerEntry, SignalType, parse_ledger_entry
+
+ENTRY_CAPS: dict[SignalType, int] = {
+    "meta": 1,
+    "pref": 20,
+    "map": 10,
+    "asn": 5,
+    "rub": 4,
+}
+
+TOTAL_CAP = 40
+
+_SIGNAL_PREFIX_RE = re.compile(r"^\[sig:(\w+)\]\s+(.+)$")
+
+
+def parse_ledger_line(line: str) -> LedgerEntry | None:
+    """Parse a single ledger line: `[sig:type] {json}`. Returns None for empty or unparseable lines."""
+    trimmed = line.strip()
+    if not trimmed:
+        return None
+
+    match = _SIGNAL_PREFIX_RE.match(trimmed)
+    if not match:
+        return None
+
+    signal_type = match.group(1)
+    try:
+        data = json.loads(match.group(2))
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+    return parse_ledger_entry(signal_type, data)
+
+
+def format_ledger_line(entry: LedgerEntry) -> str:
+    """Format a ledger entry back to `[sig:type] {json}` string."""
+    return f"[sig:{entry.type}] {json.dumps(entry.data.model_dump(exclude_none=True))}"
+
+
+def parse_ledger(content: str) -> list[LedgerEntry]:
+    """Parse a full ledger JSONL string into typed entries."""
+    results: list[LedgerEntry] = []
+    for line in content.split("\n"):
+        entry = parse_ledger_line(line)
+        if entry is not None:
+            results.append(entry)
+    return results
+
+
+def write_ledger(entries: list[LedgerEntry]) -> str:
+    """Serialize ledger entries to JSONL string with typed prefixes."""
+    return "\n".join(format_ledger_line(e) for e in entries) + "\n"
+
+
+def count_by_type(entries: list[LedgerEntry]) -> dict[SignalType, int]:
+    """Count entries by type."""
+    counts: dict[SignalType, int] = {"meta": 0, "pref": 0, "map": 0, "asn": 0, "rub": 0}
+    for entry in entries:
+        counts[entry.type] += 1
+    return counts
+
+
+def check_capacity(entries: list[LedgerEntry]) -> list[str]:
+    """Check if ledger exceeds capacity constraints. Returns violations or empty list."""
+    violations: list[str] = []
+    counts = count_by_type(entries)
+
+    if len(entries) > TOTAL_CAP:
+        violations.append(f"total {len(entries)} exceeds cap {TOTAL_CAP}")
+
+    for signal_type, cap in ENTRY_CAPS.items():
+        count = counts.get(signal_type, 0)
+        if count > cap:
+            violations.append(f"{signal_type} count {count} exceeds cap {cap}")
+
+    return violations
+
+
+def estimate_tokens(entries: list[LedgerEntry]) -> int:
+    """Estimate token count for ledger entries (~75 tokens per entry)."""
+    return len(entries) * 75

nomark_engine/resolver.py

@@ -0,0 +1,304 @@
+"""MEE Resolver — intent resolution from preference ledger.
+
+Ports packages/engine/src/resolver.ts.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from .schema import LedgerEntry, SigPref, SigMap, SigAsn, LedgerEntryPref, LedgerEntryMap, LedgerEntryAsn
+from .decay import effective_weight
+from .ledger import parse_ledger
+
+
+def scope_specificity(scope: str) -> float:
+    if scope == "*":
+        return 0.3
+    if "+" in scope:
+        return 1.0
+    return 0.7
+
+
+def scope_matches(scope: str, context: str | None = None, topic: str | None = None) -> bool:
+    if scope == "*":
+        return True
+
+    for part in scope.split("+"):
+        kv = part.split(":", 1)
+        if len(kv) != 2:
+            continue
+        key, value = kv
+        if key == "context" and context and value != context:
+            return False
+        if key == "topic" and topic and value != topic:
+            return False
+
+    return True
+
+
+@dataclass(frozen=True)
+class ScoringFactors:
+    specificity: float
+    evidence: float
+    recency: float
+    stability: float
+    portability: float
+    contradiction_penalty: float
+
+
+@dataclass(frozen=True)
+class ScoredPref:
+    pref: SigPref
+    score: float
+    effective_w: float
+    factors: ScoringFactors
+
+
+def resolver_score(pref: SigPref, now: datetime | None = None) -> ScoredPref:
+    """Score a preference entry using the five-factor weighted formula."""
+    if now is None:
+        now = datetime.now(timezone.utc)
+
+    last = datetime.fromisoformat(pref.last)
+    if last.tzinfo is None:
+        last = last.replace(tzinfo=timezone.utc)
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+
+    days_since_last = max(0.0, (now - last).total_seconds() / 86400)
+
+    specificity = scope_specificity(pref.scope)
+    evidence = min(1.0, pref.n / 20)
+    recency = max(0.0, 1.0 - days_since_last / 180)
+    stability = (1.0 - (pref.ctd / pref.n)) if pref.n > 0 else 0.5
+
+    portability = 0.0
+    if pref.src:
+        src_dict = pref.src.model_dump(exclude_none=True)
+        portability = sum(1 for v in src_dict.values() if isinstance(v, (int, float)) and v > 0) / 3
+
+    contradiction_penalty = pref.ctd * 0.15
+
+    score = (
+        (specificity * 0.30)
+        + (evidence * 0.25)
+        + (recency * 0.20)
+        + (stability * 0.15)
+        + (portability * 0.10)
+        - contradiction_penalty
+    )
+
+    return ScoredPref(
+        pref=pref,
+        score=round(score * 1000) / 1000,
+        effective_w=effective_weight(pref.w, pref.decay),
+        factors=ScoringFactors(
+            specificity=specificity,
+            evidence=evidence,
+            recency=recency,
+            stability=stability,
+            portability=portability,
+            contradiction_penalty=contradiction_penalty,
+        ),
+    )
+
+
+@dataclass(frozen=True)
+class DimensionResult:
+    dimension: str
+    winner: ScoredPref | None
+    runner_up: ScoredPref | None
+    unstable: bool
+    action: str  # 'use_winner' | 'ask'
+    candidates: int
+
+
+@dataclass(frozen=True)
+class MeaningMapMatch:
+    trigger: str
+    intent: list[str]
+    confidence: float
+    scope: str
+
+
+@dataclass(frozen=True)
+class DefaultMatch:
+    field: str
+    default: str
+    accuracy: float
+
+
+@dataclass(frozen=True)
+class ResolverMeta:
+    entry_count: int
+    estimated_tokens: int
+
+
+@dataclass(frozen=True)
+class ResolverResult:
+    dimensions: dict[str, DimensionResult]
+    meaning_maps: list[MeaningMapMatch]
+    defaults: list[DefaultMatch]
+    meta: ResolverMeta
+
+
+def resolve_dimension(
+    entries: list[LedgerEntry],
+    dimension: str,
+    context: str | None = None,
+    topic: str | None = None,
+    now: datetime | None = None,
+) -> DimensionResult:
+    if now is None:
+        now = datetime.now(timezone.utc)
+
+    candidates = [
+        resolver_score(e.data, now)
+        for e in entries
+        if e.type == "pref" and e.data.dim == dimension and scope_matches(e.data.scope, context, topic)
+    ]
+    candidates.sort(key=lambda c: c.score, reverse=True)
+
+    if not candidates:
+        return DimensionResult(
+            dimension=dimension, winner=None, runner_up=None,
+            unstable=False, action="ask", candidates=0,
+        )
+
+    winner = candidates[0]
+    runner_up = candidates[1] if len(candidates) > 1 else None
+    unstable = winner.score < 0.4
+
+    return DimensionResult(
+        dimension=dimension, winner=winner, runner_up=runner_up,
+        unstable=unstable, action="ask" if unstable else "use_winner",
+        candidates=len(candidates),
+    )
+
+
+def match_meaning_maps(
+    entries: list[LedgerEntry],
+    input_text: str,
+    context: str | None = None,
+    topic: str | None = None,
+) -> list[MeaningMapMatch]:
+    normalized = input_text.lower().strip()
+
+    results: list[MeaningMapMatch] = []
+    for e in entries:
+        if e.type != "map":
+            continue
+        data: SigMap = e.data
+        entry_scope = data.scope or "*"
+        if normalized.find(data.trigger.lower()) == -1:
+            continue
+        if not scope_matches(entry_scope, context, topic):
+            continue
+        results.append(MeaningMapMatch(
+            trigger=data.trigger,
+            intent=data.intent,
+            confidence=data.conf,
+            scope=entry_scope,
+        ))
+
+    return results
+
+
+def find_defaults(entries: list[LedgerEntry]) -> list[DefaultMatch]:
+    return [
+        DefaultMatch(field=e.data.field, default=e.data.default, accuracy=e.data.accuracy)
+        for e in entries
+        if e.type == "asn"
+    ]
+
+
+_SIGNAL_PREFIX_RE = re.compile(r"^\[sig:(\w+)\]\s+(.+)$")
+
+
+def _parse_ledger_content(content: str) -> list[LedgerEntry]:
+    return parse_ledger(content)
+
+
+@dataclass
+class ResolverConfig:
+    ledger_path: str | None = None
+    ledger_content: str | None = None
+    entries: list[LedgerEntry] | None = None
+    context: str | None = None
+    topic: str | None = None
+    now: datetime | None = None
+
+
+def _load_entries(config: ResolverConfig) -> list[LedgerEntry]:
+    if config.entries is not None:
+        return config.entries
+    if config.ledger_content is not None:
+        return _parse_ledger_content(config.ledger_content)
+    return []
+
+
+class Resolver:
+    """Resolver instance created from configuration."""
+
+    def __init__(self, config: ResolverConfig) -> None:
+        self._entries = _load_entries(config)
+        self._now = config.now or datetime.now(timezone.utc)
+        self._context = config.context
+        self._topic = config.topic
+
+    def resolve(self, dimension: str) -> DimensionResult:
+        return resolve_dimension(self._entries, dimension, self._context, self._topic, self._now)
+
+    def resolve_all(self) -> ResolverResult:
+        dimensions: set[str] = set()
+        for entry in self._entries:
+            if entry.type == "pref":
+                dimensions.add(entry.data.dim)
+
+        results: dict[str, DimensionResult] = {}
+        for dim in dimensions:
+            results[dim] = resolve_dimension(self._entries, dim, self._context, self._topic, self._now)
+
+        return ResolverResult(
+            dimensions=results,
+            meaning_maps=[],
+            defaults=find_defaults(self._entries),
+            meta=ResolverMeta(
+                entry_count=len(self._entries),
+                estimated_tokens=len(self._entries) * 75,
+            ),
+        )
+
+    def resolve_input(self, input_text: str) -> ResolverResult:
+        dimensions: set[str] = set()
+        for entry in self._entries:
+            if entry.type == "pref":
+                dimensions.add(entry.data.dim)
+
+        dim_results: dict[str, DimensionResult] = {}
+        for dim in dimensions:
+            dim_results[dim] = resolve_dimension(self._entries, dim, self._context, self._topic, self._now)
+
+        return ResolverResult(
+            dimensions=dim_results,
+            meaning_maps=match_meaning_maps(self._entries, input_text, self._context, self._topic),
+            defaults=find_defaults(self._entries),
+            meta=ResolverMeta(
+                entry_count=len(self._entries),
+                estimated_tokens=len(self._entries) * 75,
+            ),
+        )
+
+    def get_entries(self) -> list[LedgerEntry]:
+        return list(self._entries)
+
+
+def create_resolver(config: ResolverConfig | None = None, **kwargs) -> Resolver:
+    """Create a resolver instance from configuration."""
+    if config is None:
+        config = ResolverConfig(**kwargs)
+    return Resolver(config)

nomark_engine/schema.py

@@ -0,0 +1,189 @@
+"""Schema types and validation for NOMARK ledger entries.
+
+Ports packages/engine/src/schema.ts — Pydantic v2 models instead of Zod.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Literal, Union
+
+from pydantic import BaseModel, Field, field_validator
+
+# --- String literal unions (match TS types) ---
+
+Context = Literal["chat", "cowork", "code"]
+Outcome = Literal["accepted", "edited", "corrected", "rejected", "abandoned", "unknown"]
+RequestType = Literal["question", "task", "brainstorm", "decision", "critique", "creative", "continuation", "reaction"]
+PatternType = Literal["rewrite_request", "scope_change", "quality_complaint", "format_request", "style_override", "abort"]
+RubricStage = Literal["ephemeral", "pending", "proven", "trusted"]
+SignalType = Literal["meta", "pref", "map", "asn", "rub"]
+
+# Scope is a free-form string: '*' | 'context:{ctx}' | 'topic:{topic}' | compound
+Scope = str
+
+_ISO_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+_ISO_DATETIME_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}")
+
+
+def _validate_iso_date(v: str) -> str:
+    if not _ISO_DATE_RE.match(v):
+        raise ValueError(f"Expected ISO date (YYYY-MM-DD), got {v!r}")
+    return v
+
+
+# --- Context counts ---
+
+class ContextCounts(BaseModel):
+    chat: int | None = None
+    code: int | None = None
+    cowork: int | None = None
+
+
+# --- Signal data models ---
+
+class SigPref(BaseModel):
+    dim: str
+    target: str
+    w: float = Field(ge=0, le=1)
+    n: int = Field(ge=0)
+    src: ContextCounts
+    ctd: int = Field(ge=0)
+    scope: str
+    decay: float = Field(ge=0, le=1)
+    last: str
+    staged: bool | None = None
+    note: str | None = None
+
+    @field_validator("last")
+    @classmethod
+    def _check_last(cls, v: str) -> str:
+        return _validate_iso_date(v)
+
+
+class SigMap(BaseModel):
+    trigger: str
+    pattern_type: PatternType
+    intent: list[str]
+    neg: list[str] | None = None
+    conf: float = Field(ge=0, le=1)
+    n: int = Field(ge=0)
+    scope: str | None = None
+    last: str
+
+    @field_validator("last")
+    @classmethod
+    def _check_last(cls, v: str) -> str:
+        return _validate_iso_date(v)
+
+
+class SigAsn(BaseModel):
+    field: str
+    default: str
+    accuracy: float = Field(ge=0, le=1)
+    total: int = Field(ge=0)
+    correct: int = Field(ge=0)
+    last: str
+
+    @field_validator("last")
+    @classmethod
+    def _check_last(cls, v: str) -> str:
+        return _validate_iso_date(v)
+
+
+class OutcomeCounts(BaseModel):
+    accepted: int | None = None
+    edited: int | None = None
+    corrected: int | None = None
+    rejected: int | None = None
+    abandoned: int | None = None
+
+
+class SigMeta(BaseModel):
+    profile: dict[str, object]
+    signals: int = Field(ge=0)
+    by_ctx: ContextCounts
+    by_out: OutcomeCounts
+    avg_conf: float = Field(ge=0, le=1)
+    avg_q: float = Field(ge=0)
+    updated: str
+
+    @field_validator("updated")
+    @classmethod
+    def _check_updated(cls, v: str) -> str:
+        return _validate_iso_date(v)
+
+
+class SigRub(BaseModel):
+    id: str
+    fmt: str
+    stage: RubricStage
+    uses: int = Field(ge=0)
+    accepts: int = Field(ge=0)
+    avg_ed: float = Field(ge=0)
+    dims: dict[str, float]
+    min: float
+    ref: str | None = None
+    last: str
+
+    @field_validator("last")
+    @classmethod
+    def _check_last(cls, v: str) -> str:
+        return _validate_iso_date(v)
+
+
+# --- Ledger entry (discriminated union) ---
+
+class LedgerEntryMeta(BaseModel):
+    type: Literal["meta"] = "meta"
+    data: SigMeta
+
+
+class LedgerEntryPref(BaseModel):
+    type: Literal["pref"] = "pref"
+    data: SigPref
+
+
+class LedgerEntryMap(BaseModel):
+    type: Literal["map"] = "map"
+    data: SigMap
+
+
+class LedgerEntryAsn(BaseModel):
+    type: Literal["asn"] = "asn"
+    data: SigAsn
+
+
+class LedgerEntryRub(BaseModel):
+    type: Literal["rub"] = "rub"
+    data: SigRub
+
+
+LedgerEntry = Union[LedgerEntryMeta, LedgerEntryPref, LedgerEntryMap, LedgerEntryAsn, LedgerEntryRub]
+
+_SIGNAL_TYPE_MAP: dict[str, type[BaseModel]] = {
+    "meta": LedgerEntryMeta,
+    "pref": LedgerEntryPref,
+    "map": LedgerEntryMap,
+    "asn": LedgerEntryAsn,
+    "rub": LedgerEntryRub,
+}
+
+_SIGNAL_DATA_MAP: dict[str, type[BaseModel]] = {
+    "meta": SigMeta,
+    "pref": SigPref,
+    "map": SigMap,
+    "asn": SigAsn,
+    "rub": SigRub,
+}
+
+
+def parse_ledger_entry(signal_type: str, data: dict) -> LedgerEntry | None:
+    """Parse a signal type + data dict into a typed LedgerEntry. Returns None on validation failure."""
+    entry_cls = _SIGNAL_TYPE_MAP.get(signal_type)
+    if entry_cls is None:
+        return None
+    try:
+        return entry_cls.model_validate({"type": signal_type, "data": data})  # type: ignore[return-value]
+    except Exception:
+        return None

nomark_engine/utility.py

@@ -0,0 +1,122 @@
+"""Utility scoring and capacity-bounded pruning (MEE Spec Section 7.3).
+
+Ports packages/engine/src/utility.ts.
+
+U = (F x 0.25) + (I x 0.25) + (R x 0.20) + (P x 0.15) + (T x 0.15)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from .schema import LedgerEntry
+from .ledger import ENTRY_CAPS, TOTAL_CAP
+
+
+def utility_score(
+    entry_data: dict,
+    now: datetime | None = None,
+) -> float:
+    """Compute utility score for a ledger entry data dict."""
+    if now is None:
+        now = datetime.now(timezone.utc)
+
+    last_str = entry_data.get("last", "")
+    last = datetime.fromisoformat(last_str) if last_str else now
+    if last.tzinfo is None:
+        last = last.replace(tzinfo=timezone.utc)
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+
+    days_since_last = max(0.0, (now - last).total_seconds() / 86400)
+
+    frequency = min(1.0, (entry_data.get("_uses_30d", 0)) / 10)
+    impact = entry_data.get("_impact", 0.5)
+    recency = max(0.0, 1.0 - days_since_last / 180)
+
+    n = entry_data.get("n", entry_data.get("total", 0))
+    ctd = entry_data.get("ctd", 0)
+
+    portability = 0.0
+    src = entry_data.get("src")
+    if src and isinstance(src, dict):
+        portability = sum(1 for v in src.values() if isinstance(v, (int, float)) and v > 0) / 3
+
+    stability = (1.0 - (ctd / n)) if n > 0 else 0.5
+
+    return (frequency * 0.25) + (impact * 0.25) + (recency * 0.20) + (portability * 0.15) + (stability * 0.15)
+
+
+def is_protected(entry: LedgerEntry) -> bool:
+    """Check if an entry is protected from pruning."""
+    if entry.type == "meta":
+        return True
+    if entry.type == "rub" and entry.data.stage in ("proven", "trusted"):
+        return True
+    if entry.type == "pref" and entry.data.n >= 15 and entry.data.ctd == 0:
+        return True
+    return False
+
+
+def _entry_data_dict(entry: LedgerEntry) -> dict:
+    """Get entry data as a plain dict for utility scoring."""
+    return entry.data.model_dump(exclude_none=True)
+
+
+def prune_to_capacity(
+    entries: list[LedgerEntry],
+    now: datetime | None = None,
+) -> tuple[list[LedgerEntry], list[LedgerEntry]]:
+    """Prune entries to fit within capacity constraints.
+
+    Returns (kept, evicted). Removes lowest-utility entries first, never removes protected entries.
+    """
+    if now is None:
+        now = datetime.now(timezone.utc)
+
+    kept = list(entries)
+    evicted: list[LedgerEntry] = []
+
+    # Group by type
+    by_type: dict[str, list[tuple[int, LedgerEntry, float]]] = {}
+    for i, entry in enumerate(kept):
+        t = entry.type
+        if t not in by_type:
+            by_type[t] = []
+        by_type[t].append((i, entry, utility_score(_entry_data_dict(entry), now)))
+
+    # Enforce per-type caps
+    to_remove: set[int] = set()
+    for signal_type, items in by_type.items():
+        cap = ENTRY_CAPS.get(signal_type, 0)  # type: ignore[arg-type]
+        if len(items) <= cap:
+            continue
+        items.sort(key=lambda x: x[2])  # sort by utility ascending
+        removed = 0
+        for idx, entry, _ in items:
+            if len(items) - removed <= cap:
+                break
+            if not is_protected(entry):
+                to_remove.add(idx)
+                removed += 1
+
+    # Remove in reverse order
+    for idx in sorted(to_remove, reverse=True):
+        evicted.append(kept.pop(idx))
+
+    # Enforce total cap
+    while len(kept) > TOTAL_CAP:
+        lowest_idx = -1
+        lowest_utility = float("inf")
+        for i, entry in enumerate(kept):
+            if is_protected(entry):
+                continue
+            u = utility_score(_entry_data_dict(entry), now)
+            if u < lowest_utility:
+                lowest_utility = u
+                lowest_idx = i
+        if lowest_idx == -1:
+            break
+        evicted.append(kept.pop(lowest_idx))
+
+    return kept, evicted

nomark_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: nomark-engine
+Version: 0.1.0
+Summary: NOMARK Engine — open-core agent outcome quality resolver
+Project-URL: Homepage, https://github.com/nomark-dev/nomark
+Project-URL: Repository, https://github.com/nomark-dev/nomark
+Author: Reece Frazier
+License-Expression: Apache-2.0
+Keywords: agent,ai,intent,nomark,preferences,quality,trust
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.0
+Description-Content-Type: text/markdown
+
+# nomark-engine
+
+Open-core agent outcome quality resolver. Understands what a human means from incomplete input by learning preferences across sessions and platforms.
+
+## Install
+
+```bash
+pip install nomark-engine
+```
+
+## Quick start
+
+```python
+from nomark_engine import create_resolver, parse_ledger, ResolverConfig
+
+# Parse a NOMARK ledger
+entries = parse_ledger(open("nomark-ledger.jsonl").read())
+
+# Create resolver
+resolver = create_resolver(ResolverConfig(entries=entries))
+
+# Resolve all preference dimensions
+result = resolver.resolve_all()
+for dim, res in result.dimensions.items():
+    if res.winner:
+        print(f"{dim}: {res.winner.pref.target} (score: {res.winner.score})")
+
+# Resolve intent from natural language
+result = resolver.resolve_input("make it shorter")
+for match in result.meaning_maps:
+    print(f"Matched: {match.trigger} -> {match.intent}")
+```
+
+## Modules
+
+- **Schema** — Pydantic v2 models for all signal types (pref, map, asn, meta, rub)
+- **Classifier** — Input tier classification (pass-through, routing, extraction)
+- **Resolver** — MEE weighted scoring with scope matching and instability detection
+- **Ledger** — JSONL parser/writer with capacity constraints
+- **Decay** — Time-based decay with contradiction acceleration
+- **Utility** — Multi-factor utility scoring and capacity-bounded pruning
+
+## License
+
+Apache 2.0

nomark_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+nomark_engine/__init__.py,sha256=DMUE6ad1p6V71SbQKtoQfj7eyKHnaWrrDtvBgBwOyMo,2110
+nomark_engine/classifier.py,sha256=02X0FVNaseR4cP4NFanPc2l_U5M6_OaPKR0KdP-JPU4,3614
+nomark_engine/decay.py,sha256=1vAdS5emQvnqyu3ArOqsc3MGsP1vLYj9uYRU2XcQKhM,1230
+nomark_engine/ledger.py,sha256=Q4fAzONp3R6VQx7sCNZs65bOVTm0V4kco5HK45FzuPw,2627
+nomark_engine/resolver.py,sha256=o1v2MaBn5Yh-X0bIFQOloToiOU8uF1mj8yEevGv7pyA,8527
+nomark_engine/schema.py,sha256=7s4BuA_8OQjdKLvqn9ucm4xy2kdYA2gsYfQDh0l3-N8,4740
+nomark_engine/utility.py,sha256=4rzQmiaYNgYSl_uDpIRbb1ClLXErmjgLtn4moysl67o,3865
+nomark_engine-0.1.0.dist-info/METADATA,sha256=S7Xf8LLQwTqrANQAApRzW1jT_bu_VucrcZevzLKrIxc,2284
+nomark_engine-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+nomark_engine-0.1.0.dist-info/RECORD,,

nomark_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any