ontolith 1.0.0__py3-none-any.whl

ontolith/__init__.py

@@ -0,0 +1,47 @@
+"""Ontolith: A Python framework for collaborative knowledge bases.
+
+Where humans and AI agents are co-equal authors of a shared, governed ontology.
+"""
+
+from ontolith.core import Assertion, Entity, FixedClock, Namespace, SequentialIdProvider
+from ontolith.identity import Principal
+from ontolith.ontology import AsOfView, Ontology
+from ontolith.schema import (
+    JSON,
+    URI,
+    Boolean,
+    Concept,
+    Date,
+    DateTime,
+    Float,
+    Integer,
+    Property,
+    Ref,
+    Relation,
+    Text,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Ontology",
+    "AsOfView",
+    "Entity",
+    "Assertion",
+    "Namespace",
+    "Principal",
+    "FixedClock",
+    "SequentialIdProvider",
+    "Concept",
+    "Relation",
+    "Property",
+    "Ref",
+    "Text",
+    "Integer",
+    "Float",
+    "Boolean",
+    "Date",
+    "DateTime",
+    "URI",
+    "JSON",
+]

ontolith/core/__init__.py

@@ -0,0 +1,80 @@
+"""Core abstractions and ports for Ontolith.
+
+This module contains the fundamental building blocks:
+- Clock and IdProvider ports for deterministic behavior
+- Embedder port for hybrid retrieval (SPEC §11.3)
+- ObservabilitySink port for metrics/events/structured logs (SPEC §18, ADR-0044)
+- Error taxonomy for stable error handling
+- Entity and Assertion value objects
+
+The meta-model/IR/validation this docstring once listed as "Future" now
+lives in `ontolith.schema` (`SchemaIR`, `ConceptDef`/`PropertyDef`/
+`RelationDef`, the class DSL) — not `ontolith.core`, and shipped in M1/M3.
+"""
+
+from ontolith.core.assertion import Assertion, AssertionEvent
+from ontolith.core.clock import Clock, FixedClock, SystemClock
+from ontolith.core.embedder import Embedder, HashingEmbedder, LookupEmbedder
+from ontolith.core.entity import Entity
+from ontolith.core.errors import (
+    AuthError,
+    CapabilityError,
+    ConflictError,
+    NotFoundError,
+    OntolithError,
+    PluginError,
+    PolicyDenied,
+    SchemaError,
+    StorageError,
+    ValidationError,
+)
+from ontolith.core.ids import (
+    FixedIdProvider,
+    IdProvider,
+    SequentialIdProvider,
+    UlidProvider,
+)
+from ontolith.core.namespace import Namespace
+from ontolith.core.observability import (
+    NullObservabilitySink,
+    ObservabilitySink,
+    RecordingObservabilitySink,
+    StdlibLoggingSink,
+)
+
+__all__ = [
+    # Clock
+    "Clock",
+    "SystemClock",
+    "FixedClock",
+    # IDs
+    "IdProvider",
+    "UlidProvider",
+    "SequentialIdProvider",
+    "FixedIdProvider",
+    # Embedder
+    "Embedder",
+    "HashingEmbedder",
+    "LookupEmbedder",
+    # Observability
+    "ObservabilitySink",
+    "StdlibLoggingSink",
+    "NullObservabilitySink",
+    "RecordingObservabilitySink",
+    # Domain models
+    "Entity",
+    "Assertion",
+    "AssertionEvent",
+    "Namespace",
+    # Errors
+    "OntolithError",
+    "SchemaError",
+    "ValidationError",
+    "AuthError",
+    "CapabilityError",
+    "PolicyDenied",
+    "ConflictError",
+    "NotFoundError",
+    "StorageError",
+    "PluginError",
+]

ontolith/core/assertion.py

@@ -0,0 +1,132 @@
+"""Assertion value object - atomic unit of knowledge.
+
+Per SPEC §5.3: Assertions are append-only. Only status, valid_to, and
+supersedes links may be modified after creation.
+"""
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class Assertion(BaseModel):
+    """Atomic unit of knowledge with full provenance.
+
+    Attributes:
+        id: Unique identifier (ULID)
+        namespace: Namespace slug
+        subject: Entity ID this assertion is about
+        predicate: Qualified property/relation name (e.g., "Person.name")
+        value_kind: Whether value is a literal or entity reference
+        value_type: Type of literal value (if value_kind is "literal")
+        value: The actual value (literal or entity ID)
+        author: Principal ID who made this assertion
+        acting_as: Principal ID if delegated (optional)
+        source: Source of information (URI or description)
+        confidence: Author's stated belief (0.0-1.0)
+        rationale: Why this assertion was made
+        model: Model family+version for AI authors
+        asserted_at: When we learned this fact
+        valid_from: When the fact became/becomes true (defaults to asserted_at)
+        valid_to: When the fact stopped being true (NULL = still valid)
+        status: Current lifecycle state
+        proposal_id: Proposal that introduced this assertion
+        supersedes: Previous assertion ID if this supersedes another
+        metadata: Open JSON blob for future evolution
+    """
+
+    # Core identity
+    id: str
+    namespace: str
+    subject: str
+    predicate: str
+
+    # Value
+    value_kind: Literal["literal", "ref"]
+    value_type: str | None = None  # Required when value_kind="literal"
+    value: str  # Literal value or entity ID
+
+    # Provenance
+    author: str
+    acting_as: str | None = None
+    source: str | None = None
+    confidence: float | None = Field(None, ge=0.0, le=1.0)
+    rationale: str | None = None
+    model: str | None = None  # Required for AI authors
+
+    # Temporal
+    asserted_at: datetime
+    valid_from: datetime | None = None  # Defaults to asserted_at if not provided
+    valid_to: datetime | None = None
+
+    # Lifecycle
+    status: Literal["active", "superseded", "retracted", "flagged"] = "active"
+    proposal_id: str | None = None
+    supersedes: str | None = None
+
+    # Future evolution
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def set_defaults_and_validate(cls, values: dict[str, Any]) -> dict[str, Any]:
+        """Set valid_from default and validate value_type based on value_kind."""
+        # Default valid_from to asserted_at (SPEC §5.3)
+        if "valid_from" not in values or values["valid_from"] is None:
+            values["valid_from"] = values.get("asserted_at")
+
+        # Validate value_type based on value_kind
+        value_kind = values.get("value_kind")
+        value_type = values.get("value_type")
+
+        if value_kind == "literal" and value_type is None:
+            raise ValueError("value_type is required when value_kind is 'literal'")
+        if value_kind == "ref" and value_type is not None:
+            raise ValueError("value_type must be None when value_kind is 'ref'")
+
+        return values
+
+    model_config = ConfigDict(
+        frozen=True,  # Immutable by default
+        # Only status, valid_to, supersedes can be "mutated" via copy(update={...})
+    )
+
+
+class AssertionEvent(BaseModel):
+    """Append-only audit record of an assertion status mutation.
+
+    Assertions themselves are append-only (only status/valid_to/supersedes
+    mutate in place) — this event log makes each such mutation independently
+    attributable and timestamped, since the assertion row itself is
+    overwritten in place and doesn't retain who caused a given transition
+    or when it happened (only its current status).
+
+    Attributes:
+        id: Unique event ID (ULID)
+        assertion_id: Assertion this event was recorded against
+        actor: Principal ID accountable for the transition — the author of
+            the assertion that triggered supersession/contradiction during
+            conflict routing, or the principal who explicitly retracted/
+            resolved it
+        action: Which status transition this event records
+        at: When the transition occurred
+        successor_id: For action="superseded", the id of the assertion that
+            caused this supersession. Assertion.supersedes only records the
+            first predecessor when one incoming assertion supersedes several
+            concurrently-overlapping ones (KI-008) — querying events by
+            successor_id recovers the full predecessor set. None for other
+            actions.
+    """
+
+    id: str
+    assertion_id: str
+    actor: str
+    action: Literal["superseded", "flagged", "retracted", "reactivated"]
+    at: datetime
+    successor_id: str | None = None
+
+    model_config = ConfigDict(frozen=True)
+
+
+__all__ = ["Assertion", "AssertionEvent"]

ontolith/core/clock.py

@@ -0,0 +1,116 @@
+"""Clock abstraction for deterministic time handling.
+
+The Clock port ensures bitemporal logic is reproducible in tests by injecting
+time rather than using datetime.now() directly in domain logic.
+"""
+
+from abc import ABC, abstractmethod
+from datetime import UTC, datetime, timedelta
+
+
+class Clock(ABC):
+    """Abstract clock for deterministic time handling."""
+
+    @abstractmethod
+    def now(self) -> datetime:
+        """Return the current time.
+
+        Returns:
+            Current datetime in UTC.
+        """
+        ...
+
+
+class SystemClock(Clock):
+    """Production clock using system time."""
+
+    def now(self) -> datetime:
+        """Return the current system time in UTC.
+
+        Returns:
+            Current datetime in UTC timezone.
+        """
+        return datetime.now(UTC)
+
+
+class FixedClock(Clock):
+    """Test clock that returns a fixed time.
+
+    Useful for testing time-sensitive logic without flakiness.
+
+    Args:
+        fixed_time: The time to always return, or current time if None.
+
+    Example:
+        >>> clock = FixedClock("2025-01-01T00:00:00Z")
+        >>> clock.now()
+        datetime.datetime(2025, 1, 1, 0, 0, tzinfo=datetime.timezone.utc)
+        >>> clock.advance(days=1)
+        >>> clock.now()
+        datetime.datetime(2025, 1, 2, 0, 0, tzinfo=datetime.timezone.utc)
+    """
+
+    def __init__(self, fixed_time: str | datetime | None = None) -> None:
+        """Initialize with a fixed time.
+
+        Args:
+            fixed_time: ISO-8601 string, datetime, or None for current time.
+        """
+        if fixed_time is None:
+            self._time = datetime.now(UTC)
+        elif isinstance(fixed_time, str):
+            self._time = datetime.fromisoformat(fixed_time.replace("Z", "+00:00"))
+        else:
+            self._time = fixed_time
+
+        # Ensure timezone-aware
+        if self._time.tzinfo is None:
+            self._time = self._time.replace(tzinfo=UTC)
+
+    def now(self) -> datetime:
+        """Return the fixed time.
+
+        Returns:
+            The configured fixed datetime.
+        """
+        return self._time
+
+    def set(self, time: str | datetime) -> None:
+        """Set the clock to a new time.
+
+        Args:
+            time: ISO-8601 string or datetime to set.
+        """
+        if isinstance(time, str):
+            self._time = datetime.fromisoformat(time.replace("Z", "+00:00"))
+        else:
+            self._time = time
+
+        if self._time.tzinfo is None:
+            self._time = self._time.replace(tzinfo=UTC)
+
+    def advance(
+        self,
+        *,
+        days: int = 0,
+        hours: int = 0,
+        minutes: int = 0,
+        seconds: int = 0,
+    ) -> None:
+        """Advance the clock by the specified duration.
+
+        Args:
+            days: Number of days to advance.
+            hours: Number of hours to advance.
+            minutes: Number of minutes to advance.
+            seconds: Number of seconds to advance.
+        """
+        self._time += timedelta(
+            days=days,
+            hours=hours,
+            minutes=minutes,
+            seconds=seconds,
+        )
+
+
+__all__ = ["Clock", "SystemClock", "FixedClock"]

ontolith/core/embedder.py

@@ -0,0 +1,141 @@
+"""Embedder port for hybrid retrieval (SPEC §11.3, §14).
+
+The Embedder port converts text into vectors for semantic search over the
+vector store (StorageBackend.vector_upsert/vector_search). It is a pure
+text-to-vector transform with no knowledge of KB state — the same shape as
+Clock and IdProvider, not a capability-scoped plugin actor like Importer or
+Exporter (see plugins/ports.py's docstring for that distinction).
+
+Every Embedder implementation MUST return L2-unit-normalized vectors: this
+makes ranking by ascending L2 distance equivalent to ranking by descending
+cosine similarity (for unit vectors u, v: ||u-v||^2 = 2 - 2*cos_sim(u, v)),
+which lets StorageBackend.vector_search use one distance metric consistently
+across backends without an explicit similarity-function parameter.
+"""
+
+import hashlib
+import math
+import re
+from typing import Protocol
+
+_TOKEN_RE = re.compile(r"\w+")
+
+
+class Embedder(Protocol):
+    """Converts text into L2-unit-normalized embedding vectors."""
+
+    name: str
+    dim: int
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        """Embed a batch of texts.
+
+        Args:
+            texts: Texts to embed.
+
+        Returns:
+            One L2-unit-normalized vector of length `dim` per input text, in
+            the same order. A text with no extractable signal (empty or
+            whitespace-only) yields the zero vector, not an error.
+        """
+        ...
+
+
+class HashingEmbedder:
+    """Deterministic, dependency-free default Embedder.
+
+    Implements the feature-hashing trick (Weinberger et al., 2009): each
+    token hashes to a bucket index and a sign, avoiding the need for a
+    pre-built vocabulary or any numeric library. This is a placeholder for
+    real semantic quality, not a substitute for a model-backed Embedder —
+    it guarantees deterministic, reproducible vectors for a given text, not
+    meaningful semantic similarity between unrelated texts.
+
+    Uses hashlib.sha256, not Python's built-in hash(), because str hashing
+    is randomly salted per process (PYTHONHASHSEED) and would break
+    determinism across runs.
+    """
+
+    name = "hashing-embedder"
+
+    def __init__(self, dim: int = 256) -> None:
+        """Initialize with a fixed output dimensionality.
+
+        Args:
+            dim: Length of each output vector.
+        """
+        self.dim = dim
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        """Embed a batch of texts via feature hashing.
+
+        Args:
+            texts: Texts to embed.
+
+        Returns:
+            One L2-unit-normalized vector of length `dim` per input text.
+        """
+        return [self._embed_one(text) for text in texts]
+
+    def _embed_one(self, text: str) -> list[float]:
+        """Embed a single text via feature hashing."""
+        vec = [0.0] * self.dim
+        for token in _TOKEN_RE.findall(text.lower()):
+            digest = hashlib.sha256(token.encode("utf-8")).digest()
+            bucket = int.from_bytes(digest[:8], "big") % self.dim
+            sign = 1.0 if digest[8] & 1 else -1.0
+            vec[bucket] += sign
+
+        norm = math.sqrt(sum(v * v for v in vec))
+        if norm == 0.0:
+            return vec
+        return [v / norm for v in vec]
+
+
+class LookupEmbedder:
+    """Deterministic test double backed by an explicit text-to-vector map.
+
+    Unlike HashingEmbedder, output is fully predictable — use this in tests
+    that need to assert exact rank order from semantic search.
+    """
+
+    name = "lookup-embedder"
+
+    def __init__(
+        self, mapping: dict[str, list[float]], dim: int, default: list[float] | None = None
+    ) -> None:
+        """Initialize with an explicit text-to-vector mapping.
+
+        Args:
+            mapping: Exact text to vector lookup.
+            dim: Length of vectors in `mapping` and `default`.
+            default: Vector to return for unmapped texts, or None to raise.
+        """
+        self._mapping = mapping
+        self.dim = dim
+        self._default = default
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        """Look up each text's vector.
+
+        Args:
+            texts: Texts to look up.
+
+        Returns:
+            The mapped (or default) vector per input text.
+
+        Raises:
+            KeyError: A text is not in `mapping` and no `default` was given.
+        """
+        result = []
+        for text in texts:
+            if text in self._mapping:
+                result.append(self._mapping[text])
+            elif self._default is not None:
+                result.append(self._default)
+            else:
+                raise KeyError(f"LookupEmbedder: no vector mapped for {text!r}")
+        return result
+
+
+__all__ = ["Embedder", "HashingEmbedder", "LookupEmbedder"]

ontolith/core/entity.py

@@ -0,0 +1,34 @@
+"""Entity value object - concrete individual of a concept.
+
+Per SPEC §5.2: Entities carry no attribute values directly - all attributes
+are Assertions about the entity.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Entity(BaseModel):
+    """Concrete individual of a concept.
+
+    Attributes:
+        id: Unique identifier (ULID)
+        namespace: Namespace slug
+        concept: Concept name (e.g., "Person", "Organization")
+        natural_key: Optional unique key within (namespace, concept)
+        created_at: When this entity was created
+        created_by: Principal ID who created this entity
+    """
+
+    id: str
+    namespace: str
+    concept: str
+    natural_key: str | None = None
+    created_at: datetime
+    created_by: str
+
+    model_config = ConfigDict(frozen=True)  # Immutable
+
+
+__all__ = ["Entity"]