our-models

Data models with temporal validity, dimensional confidence, and conversation tracking for the ourochronos ecosystem.

Overview

our-models provides the Python dataclasses and enums that represent the Valence knowledge substrate. It bridges the PostgreSQL schema and application code with structured types for beliefs, entities, sessions, exchanges, patterns, and tensions. Key features include time-bounded validity on knowledge claims, exponential freshness decay, and supersession chains that track belief evolution.

Install

pip install our-models

Requires our-confidence>=0.1.0.

Usage

Beliefs

from uuid import uuid4
from datetime import datetime
from our_models import Belief, BeliefStatus
from our_confidence import DimensionalConfidence

belief = Belief(
    id=uuid4(),
    content="Python 3.12 adds incremental GC",
    confidence=DimensionalConfidence(overall=0.9),
    domain_path=["tech", "python"],
    valid_from=datetime.now(),
    status=BeliefStatus.ACTIVE,
)

Temporal Validity

from our_models import TemporalValidity

# Valid for a specific range
tv = TemporalValidity.range(start, end)
tv.is_valid_at(some_date)  # True/False
tv.is_expired()
tv.remaining()  # timedelta or None

# Always valid
tv = TemporalValidity.always_valid()

# Valid from now for 30 days
tv = TemporalValidity.for_duration(timedelta(days=30))

Freshness Scoring

from our_models import calculate_freshness, freshness_label

score = calculate_freshness(belief.created_at, half_life_days=30)
# 1.0 = just created, decays exponentially

label = freshness_label(score)
# "very fresh" | "fresh" | "aging" | "stale" | "very stale"

Supersession Chains

from our_models import SupersessionChain

chain = SupersessionChain(entries=[...])
chain.original_id    # first belief in the chain
chain.current_id     # latest belief
chain.revision_count
chain.get_at_time(some_date)  # belief that was current at that time

Sessions and Exchanges

from our_models import Session, Exchange, Platform, ExchangeRole

session = Session(
    id=uuid4(),
    platform=Platform.CLAUDE_CODE,
    project_context="valence",
    themes=["refactoring", "testing"],
)

exchange = Exchange(
    session_id=session.id,
    sequence=1,
    role=ExchangeRole.USER,
    content="How do I add a new MCP tool?",
)

Serialization

# All models support database round-tripping
d = belief.to_dict()        # JSON-serializable dict
belief = Belief.from_row(db_row)  # Reconstruct from database row

API

Knowledge Models

Conversation Models

Temporal

Enums

BeliefStatus, EntityType, EntityRole, SessionStatus, Platform, ExchangeRole, PatternStatus, TensionType, TensionSeverity, TensionStatus

Development

# Install with dev dependencies
make dev

# Run linters
make lint

# Run tests
make test

# Run tests with coverage
make test-cov

# Auto-format
make format

State Ownership

None directly. This package defines data shapes — state is owned by the database layer (our-db) and the substrate that persists these models.

Part of Valence

This brick is part of the Valence knowledge substrate. See our-infra for ourochronos conventions.

License

MIT