linkedparticles-core 1.187.3__tar.gz → 1.192.2__tar.gz

{linkedparticles_core-1.187.3 → linkedparticles_core-1.192.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: linkedparticles-core
-Version: 1.187.3
+Version: 1.192.2
 Summary: Store-free client library for Particles: define, validate, serialize, and extract provenance-tracked belief particles
 Project-URL: Homepage, https://linkedparticles.org
 Project-URL: Documentation, https://docs.linkedparticles.org

{linkedparticles_core-1.187.3 → linkedparticles_core-1.192.2}/artifacts/schemas/context.jsonld

@@ -63,6 +63,8 @@
     "particleType": { "@id": "particles:particleType" },
     "assertionModality": { "@id": "particles:assertionModality" },
     "validUntil": { "@id": "psum:duration", "@type": "xsd:dateTime" },
+    "validFrom": { "@id": "particles:validFrom", "@type": "xsd:dateTime" },
+    "validKind": { "@id": "particles:validKind" },
     "supersedes": { "@id": "particles:supersedes", "@type": "@id" },
     "subjectIds": { "@id": "particles:subject", "@type": "@id", "@container": "@set" },
     "subjects": { "@id": "particles:subjects", "@container": "@list" },

{linkedparticles_core-1.187.3 → linkedparticles_core-1.192.2}/artifacts/schemas/interchange.schema.json

@@ -85,6 +85,8 @@
         },
         "uncertaintyKind": { "type": "string" },
         "validUntil": { "type": "string", "format": "date-time" },
+        "validFrom": { "type": "string", "format": "date-time" },
+        "validKind": { "type": "string", "enum": ["EVENT", "STATE"] },
         "supersedes": { "type": "string" },
         "basis": {
           "type": "object",

{linkedparticles_core-1.187.3 → linkedparticles_core-1.192.2}/artifacts/schemas/particle.schema.json

@@ -100,6 +100,16 @@
       "format": "date-time",
       "description": "Core: expiry for time-bounded claims (lazy query-time filter, §9.3)"
     },
+    "valid_from": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "Core: when the claim begins to hold in the world, the counterpart of valid_until; read by the window route (§9.3), never by reconciliation"
+    },
+    "valid_kind": {
+      "type": ["string", "null"],
+      "enum": ["EVENT", "STATE", null],
+      "description": "Core: how the world-time pair is read; EVENT is a moment (the point [valid_from, valid_from], never with a valid_until), STATE a span"
+    },
     "supersedes": {
       "type": ["string", "null"],
       "format": "uuid",

{linkedparticles_core-1.187.3 → linkedparticles_core-1.192.2}/artifacts/schemas/shacl/ParticleShape.ttl

@@ -112,6 +112,25 @@ particles:ParticleShape
         sh:message "assertion_modality, when present, must be FALSIFIABLE, EVALUATIVE, EXPERIENTIAL, or CONSTITUTIVE." ;
     ] ;
 
+    # validKind — optional reading of the world-time pair: EVENT is
+    # a moment, STATE a span. An EVENT never carries a validUntil — a
+    # cardinality across two properties the shape cannot express without a
+    # SPARQL constraint, so the Core model validator enforces it.
+    sh:property [
+        sh:path particles:validKind ;
+        sh:maxCount 1 ;
+        sh:datatype xsd:string ;
+        sh:in ( "EVENT" "STATE" ) ;
+        sh:message "valid_kind, when present, must be EVENT or STATE." ;
+    ] ;
+
+    sh:property [
+        sh:path particles:validFrom ;
+        sh:maxCount 1 ;
+        sh:datatype xsd:dateTime ;
+        sh:message "valid_from, when present, must be a single xsd:dateTime." ;
+    ] ;
+
     # canonicalForm — optional marker of which of the prose/structured pair is
     # the assertion; PROSE default. STRUCTURED additionally requires
     # a structuredClaim to be present — a cardinality the shape cannot express

{linkedparticles_core-1.187.3 → linkedparticles_core-1.192.2}/particles/config.py

@@ -409,7 +409,9 @@ class ProviderSelection(BaseModel):
     """
 
     provider: str = "anthropic"
-    model: str = "claude-sonnet-4-6"
+    # The compiled default since 1.189.0, when it moved from claude-sonnet-4-6
+    # behind measurements registered before the runs.
+    model: str = "claude-sonnet-5-5"
 
 
 class OpenAICompatProviderConfig(BaseModel):
@@ -572,6 +574,27 @@ _LIST_PRICES_PER_MTOK: dict[str, tuple[float, float]] = {
 }
 
 
+# Measured estimate factors that ship for the compiled default and the model it
+# replaced, keyed like ``llm.price_per_mtok``. Characters per input
+# token follow the shipped convention: the old tokenizer's 4.0 rule of thumb
+# divided by the measured token ratio against claude-sonnet-4-6 (1.3437 on one
+# run's byte-identical extraction prompts, token-counting endpoint, 2026-10-13).
+# The output scale is relative to claude-sonnet-5, which the audit's per-call
+# figures were fitted on: claude-sonnet-5-5 wrote 59,760 output tokens on the
+# 2026-10 provider survey's 18 calls against claude-sonnet-5's 111,950 on the same
+# calls (0.534). The extraction figure is the memory benchmark's 6,700 scaled the
+# same way. The claude-sonnet-4-6 entries come from paired run
+# (docs/benchmarks/default-model-adr0317-2026-10-13.md).
+_SHIPPED_CHARS_PER_TOKEN: dict[str, float] = {"claude-sonnet-5-5": 2.98}
+_SHIPPED_OUTPUT_SCALE: dict[str, float] = {
+    "claude-sonnet-5-5": 0.534,
+    "claude-sonnet-4-6": 0.800,
+}
+_SHIPPED_EXTRACTION_OUTPUT_TOKENS: dict[str, int] = {
+    "claude-sonnet-5-5": 3_578,
+    "claude-sonnet-4-6": 5_363,
+}
+
 _T = TypeVar("_T")
 
 
@@ -591,6 +614,23 @@ def lookup_by_model(
     return None, None
 
 
+#: Every completion purpose, in the order the operator-facing lines print them.
+#: A literal here because config cannot import ``particles.llm``;
+#: tests/test_config.py pins it equal to ``particles.llm.LLMPurpose``.
+LLM_PURPOSES: tuple[str, ...] = (
+    "extraction",
+    "semantic_lint",
+    "verification",
+    "subject_resolution",
+    "query_response",
+    "synthesis",
+    "abstraction",
+    "benchmark",
+    "benchmark_answer",
+    "use_judge",
+)
+
+
 def _default_prices() -> dict[str, TokenPrice]:
     return {
         model: TokenPrice(input=inp, output=out)
@@ -603,9 +643,11 @@ class LLMConfig(BaseModel):
 
     ``default`` is the fallback pairing; each purpose may override it. The
     operator can thus route high-volume ``extraction`` to a cheap model while
-    keeping low-volume ``synthesis`` on a hosted one. All compiled defaults are
-    ``claude-sonnet-4-6`` so the out-of-the-box behaviour is unchanged from
-    before the port existed.
+    keeping low-volume ``synthesis`` on a hosted one. Every purpose falls back
+    to the compiled default, ``claude-sonnet-5-5`` since 1.189.0 (
+    ``claude-sonnet-4-6`` before), except ``use_judge``, which carries its own
+    compiled selection. ``particles config validate`` names the
+    default in force and where it came from.
 
     The legacy ``extraction.model`` / ``wiki.model`` keys are migrated into
     this section by ``_migrate_legacy_keys`` (``extraction.model`` →
@@ -712,6 +754,30 @@ class LLMConfig(BaseModel):
         override = getattr(self, purpose, None)
         return override if isinstance(override, ProviderSelection) else self.default
 
+    def selection_source(self, purpose: str) -> str:
+        """Where ``purpose``'s selection comes from, as an operator reads it.
+
+        ``"llm.<purpose>"`` when the configuration sets that purpose,
+        ``"compiled llm.<purpose>"`` for a purpose with its own compiled
+        selection that the configuration leaves alone (``use_judge``),
+        ``"llm.default"`` when the purpose falls back to a configured default,
+        and ``"compiled default"`` when nothing set it. ``"default"`` itself
+        reads as either of the last two.
+        """
+        if purpose != "default" and getattr(self, purpose, None) is not None:
+            if purpose in self.model_fields_set:
+                return f"llm.{purpose}"
+            return f"compiled llm.{purpose}"
+        return "llm.default" if "default" in self.model_fields_set else "compiled default"
+
+    def routed_elsewhere(self) -> dict[str, ProviderSelection]:
+        """The purposes whose selection differs from ``default``, in purpose order."""
+        return {
+            purpose: sel
+            for purpose in LLM_PURPOSES
+            if (sel := self.for_purpose(purpose)) != self.default
+        }
+
     @model_validator(mode="after")
     def _validate_provider_wiring(self) -> LLMConfig:
         """Fail dangling provider names / adapter kinds at config load.
@@ -976,6 +1042,16 @@ class ModalityRegenerationConfig(BaseModel):
     commit_interval: int = Field(default=25, ge=1)
 
 
+class ValidityBackfillConfig(BaseModel):
+    """Defaults for ``particles validity``, the prose-date default for ``valid_from``.
+
+    The pass makes no model call, so it has no rate limit; ``commit_interval``
+    is how often it commits, so an interrupt costs seconds of work.
+    """
+
+    commit_interval: int = Field(default=200, ge=1)
+
+
 class ExtractionPolarityConfig(BaseModel):
     """LLM-semantic claim-polarity classification of candidates (cap. 1).
 
@@ -1020,10 +1096,18 @@ class ExtractionValidityConfig(BaseModel):
     a structural decision (does a boundary exist?), never the stored
     ``confidence.value``. ``enabled: false`` reproduces the pre-0197
     behaviour exactly (no candidate ever carries ``valid_until`` from extraction).
+
+    ``session_source_types`` names the source types a harness deposits as a
+    session transcript. For those, the extractor may anchor a
+    past-tense claim reporting an act performed *in the session* at the
+    reference date as an ``EVENT`` under the ``session`` basis, so a window
+    read finds what a session did; for every other source a past-tense claim
+    with no date gets no start. Empty disables the rule.
     """
 
     enabled: bool = True
     min_boundary_confidence: float = 0.75
+    session_source_types: list[str] = Field(default_factory=lambda: ["CONVERSATION"])
 
 
 class StructuredClaimConfig(BaseModel):
@@ -1777,6 +1861,10 @@ class SubjectsConfig(BaseModel):
     # claude-sonnet-4-6; on an ordinary-prose gold set, 0.898 to 0.918 against
     # 0.735, 45 of 49 names judged at about US$0.20 per 100 names, no correct
     # link lost on either (docs/benchmarks/subject-resolution-judge-2026-10-01.md).
+    # Re-measured 2026-10-13 on claude-sonnet-5-5, the compiled default since
+    # 1.189.0, at 7 hits: 1.000 on the suite and 0.939 on the ordinary-prose
+    # set, no correct link lost, at about US$0.09 and US$0.20 per 100 names
+    # (docs/benchmarks/default-model-adr0317-2026-10-13.md).
     # With no LLM key, an open breaker, or an unusable reply it takes the top
     # hit, so `top_hit` is also what an offline store gets. Set `top_hit` to
     # resolve with no model call at all.
@@ -3001,6 +3089,15 @@ class AuditConfig(BaseModel):
     # 0 probes nothing (disclosed the same way). `particles lint` is not
     # affected: cost gating is the audit's concern, lint stays exhaustive.
     max_contradiction_probes: int = Field(default=50, ge=0)
+    # (the ruling, order, do not drop): under a probe
+    # cap the census probes the pairs some single reader sees first (the
+    # observer precondition reconciles or reviews them) and
+    # reserves this share of the cap for cross-scope pairs, two projects'
+    # claims the precondition declines, so a contradiction between projects
+    # is still discovered and recorded as OBSERVER_DIVERGENCE. A share neither
+    # side fills goes to the other. An ordering, never a filter; a store that
+    # was never rescoped, and uncapped `particles lint`, are not reordered.
+    cross_scope_probe_share: float = Field(default=0.2, ge=0.0, le=1.0)
     # read each pair the probe flagged a second time, on
     # ``llm.verification``, with each claim's source passage, note name and
     # note date, and count only the confirmed pairs in the headline. The report
@@ -3061,7 +3158,12 @@ class AuditConfig(BaseModel):
     # measured ~3,600 output tokens per memory-note call on claude-haiku-4-5
     # against ~6,700 on claude-sonnet-5, so routing ``llm.extraction`` to haiku
     # warrants an entry of about 0.55. A model with no entry is scaled by 1.
-    estimate_output_scale_by_model: dict[str, float] = Field(default_factory=dict)
+    # Ships with measured entries for the compiled default and the model it
+    # replaced (``_SHIPPED_OUTPUT_SCALE``); operator entries merge
+    # over them key by key.
+    estimate_output_scale_by_model: dict[str, float] = Field(
+        default_factory=lambda: dict(_SHIPPED_OUTPUT_SCALE)
+    )
     # Each call's output is taken to fall anywhere within this fraction of its
     # expected figure. The expected range runs from every call at (1 - spread)
     # to every call at (1 + spread), and a call whose output would pass
@@ -3108,6 +3210,14 @@ class AuditConfig(BaseModel):
     # Wall time per second reading: the measured runs read 22 flags in ~41 s.
     estimate_seconds_per_verification: float = Field(default=2.0, ge=0.0)
 
+    @field_validator("estimate_output_scale_by_model", mode="before")
+    @classmethod
+    def _merge_over_shipped_scales(cls, value: Any) -> Any:
+        """Operator entries replace the shipped ones key by key; the rest stay."""
+        if isinstance(value, dict):
+            return {**_SHIPPED_OUTPUT_SCALE, **value}
+        return value
+
     @field_validator("estimate_output_scale_by_model")
     @classmethod
     def _non_negative_output_scale(cls, value: dict[str, float]) -> dict[str, float]:
@@ -3524,8 +3634,10 @@ class MemoryBenchmarkConfig(BaseModel):
     # on claude-sonnet-5 but ~3.6k on claude-haiku-4-5 — so an arm routing
     # ``llm.extraction`` elsewhere is mis-estimated ~2x on the write side
     # without an entry here. The rendered estimate says which source it used.
+    # Ships with measured entries for the compiled default and the model it
+    # replaced; operator entries merge over them key by key.
     estimate_output_tokens_per_extraction_call_by_model: dict[str, int] = Field(
-        default_factory=dict
+        default_factory=lambda: dict(_SHIPPED_EXTRACTION_OUTPUT_TOKENS)
     )
     # Characters per input token — the factor the estimate and the pre-flight
     # context-window check divide prompt bytes by. The scalar is the classic
@@ -3536,8 +3648,30 @@ class MemoryBenchmarkConfig(BaseModel):
     # lookup as ``llm.price_per_mtok`` — is what keeps their input projection and
     # their window verdict honest. The write side is keyed on the extraction
     # model, the answer side and the window check on the answer model.
+    # The map ships one entry, for the compiled default, and the
+    # scalar stays the old tokenizer's 4.0, so a model with no entry (a local
+    # or OpenAI-compatible one included) keeps the factor it always had.
+    # Operator entries merge over the shipped one key by key.
     chars_per_token: float = Field(default=4.0, gt=0.0)
-    chars_per_token_by_model: dict[str, float] = Field(default_factory=dict)
+    chars_per_token_by_model: dict[str, float] = Field(
+        default_factory=lambda: dict(_SHIPPED_CHARS_PER_TOKEN)
+    )
+
+    @field_validator("estimate_output_tokens_per_extraction_call_by_model", mode="before")
+    @classmethod
+    def _merge_over_shipped_output_tokens(cls, value: Any) -> Any:
+        """Operator entries replace the shipped ones key by key; the rest stay."""
+        if isinstance(value, dict):
+            return {**_SHIPPED_EXTRACTION_OUTPUT_TOKENS, **value}
+        return value
+
+    @field_validator("chars_per_token_by_model", mode="before")
+    @classmethod
+    def _merge_over_shipped_chars_per_token(cls, value: Any) -> Any:
+        """Operator entries replace the shipped ones key by key; the rest stay."""
+        if isinstance(value, dict):
+            return {**_SHIPPED_CHARS_PER_TOKEN, **value}
+        return value
 
     @field_validator("estimate_output_tokens_per_extraction_call_by_model")
     @classmethod
@@ -3735,6 +3869,31 @@ class LeakageBenchmarkConfig(BaseModel):
     confirm_call_threshold: int = Field(default=50, ge=0)
 
 
+class UpdateGateBenchmarkConfig(BaseModel):
+    """The trip-versus-move case and the update-gate pair sets.
+
+    Run counts and safety margins only. The pipeline under test runs the
+    compiled defaults with every purpose pinned to the chosen model: nothing
+    here re-tunes extraction, reconciliation or consolidation. There is no
+    confirm threshold: every live run asks before its first call, because
+    neither suite has a free live path.
+    """
+
+    # The record's protocol (item 5): the bar is stated only when a
+    # run uses these counts.
+    move_runs: int = Field(default=3, ge=0)
+    trip_alone_runs: int = Field(default=2, ge=0)
+    # Samples per pair in the update-gate replay; the sets were registered at 3.
+    samples: int = Field(default=3, ge=1)
+    # The per-run ceiling --max-usd defaults to, as a multiple of a measured
+    # estimate (a profile or the 2026-10-12 record). An upper-bound estimate is
+    # already a ceiling and is used as is.
+    max_usd_multiplier: float = Field(default=4.0, ge=1.0)
+    # How long one run's child may take before it is stopped and reported
+    # incomplete. A live run took a few minutes on 2026-10-12.
+    run_timeout_seconds: float = Field(default=1800.0, gt=0.0)
+
+
 class BenchmarkConfig(BaseModel):
     """Benchmark-harness run persistence (family).
 
@@ -3903,6 +4062,7 @@ class ParticlesConfig(BaseModel):
     extraction_stance: ExtractionStanceConfig = Field(default_factory=ExtractionStanceConfig)
     extraction_polarity: ExtractionPolarityConfig = Field(default_factory=ExtractionPolarityConfig)
     extraction_validity: ExtractionValidityConfig = Field(default_factory=ExtractionValidityConfig)
+    validity_backfill: ValidityBackfillConfig = Field(default_factory=ValidityBackfillConfig)
     extraction_vision: ExtractionVisionConfig = Field(default_factory=ExtractionVisionConfig)
     structured_claim: StructuredClaimConfig = Field(default_factory=StructuredClaimConfig)
     rdf: RdfConfig = Field(default_factory=RdfConfig)
@@ -3956,6 +4116,9 @@ class ParticlesConfig(BaseModel):
         default_factory=RelevanceFloorBenchmarkConfig
     )
     benchmark_leakage: LeakageBenchmarkConfig = Field(default_factory=LeakageBenchmarkConfig)
+    benchmark_update_gate: UpdateGateBenchmarkConfig = Field(
+        default_factory=UpdateGateBenchmarkConfig
+    )
     benchmark: BenchmarkConfig = Field(default_factory=BenchmarkConfig)
     refetch_floors: dict[str, int] = Field(default_factory=lambda: dict(_DEFAULT_REFETCH_FLOORS))
     local_refresh: LocalRefreshConfig = Field(default_factory=LocalRefreshConfig)
@@ -4130,6 +4293,15 @@ _ENV_OVERRIDES: list[tuple[str, str, str]] = [
 ]
 
 
+def env_override_names() -> frozenset[str]:
+    """Every environment variable that overrides a config field.
+
+    A benchmark that runs the SDK in a child process with a private environment
+    removes these, so no override of the operator's reaches the run.
+    """
+    return frozenset(name for name, _section, _field in _ENV_OVERRIDES)
+
+
 # ---------------------------------------------------------------------------
 # Loader
 # ---------------------------------------------------------------------------

{linkedparticles_core-1.187.3 → linkedparticles_core-1.192.2}/particles/conformance/contract.py

@@ -103,6 +103,16 @@ CONTRACT: list[FieldContract] = [
     ),
     FieldContract("uncertainty_kind", FieldTier.OPTIONAL, "Extension A free-text label"),
     FieldContract("valid_until", FieldTier.OPTIONAL, "Time-bounded claims only"),
+    FieldContract(
+        "valid_from",
+        FieldTier.OPTIONAL,
+        "Claims with a stated world-time start; the window route's input",
+    ),
+    FieldContract(
+        "valid_kind",
+        FieldTier.OPTIONAL,
+        "EVENT (a moment) or STATE (a span); how valid_from and valid_until are read",
+    ),
     FieldContract("supersedes", FieldTier.OPTIONAL, "Set by reindex, not by extractors"),
     FieldContract(
         "tags",

{linkedparticles_core-1.187.3 → linkedparticles_core-1.192.2}/particles/core/conflict_resolution.py

@@ -699,6 +699,10 @@ def decide_ladder(
 # written and no cascade runs.
 RETIRED_VALUE_KEY = "conflict:retired_value"
 
+#: The ``properties`` key naming the ladder rung whose verdict opened an
+#: INCONSISTENCY record, ``name@version``.
+DECIDED_BY_KEY = "conflict:decided_by"
+
 
 def build_inconsistency_particle(
     existing: Particle,
@@ -709,6 +713,7 @@ def build_inconsistency_particle(
     asserted_by: str = "extract-pipeline",
     trigger_ref_type: ProvenanceRefType = ProvenanceRefType.SOURCE,
     retired_twin: bool = False,
+    decided_by: str | None = None,
 ) -> Particle:
     """Construct the INCONSISTENCY ``Particle`` for an unresolvable pair.
 
@@ -752,6 +757,10 @@ def build_inconsistency_particle(
         headline says so, and :data:`RETIRED_VALUE_KEY` carries the twin's
         ``status_reason`` in ``properties`` so Review can tell the two kinds
         of record apart.
+      - ``decided_by``: the stamp of the ladder rung whose
+        verdict opened the record, carried in ``properties`` under
+        :data:`DECIDED_BY_KEY`; ``None`` leaves it unstamped (a fail-closed
+        record no rung decided, or a retired-value hold).
     """
     # Inherit subject_ids from the existing particle (Particle A). Fall back
     # to the new particle's set if existing has none.
@@ -773,6 +782,8 @@ def build_inconsistency_particle(
             f"Particle A: {existing.id} — {existing.content[:120]}\n"
             f"Particle B (new): {new.content[:120]}"
         )
+    if decided_by is not None:
+        properties = {**(properties or {}), DECIDED_BY_KEY: decided_by}
 
     return Particle(
         content=inc_content,