This library has been vendored into Valence as of v1.2.0. This repo is archived for reference only. All future development happens in the Valence monorepo.
Data models with temporal validity, dimensional confidence, and conversation tracking for the ourochronos ecosystem.
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.
pip install our-modelsRequires our-confidence>=0.1.0.
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,
)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))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"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 timefrom 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?",
)# All models support database round-tripping
d = belief.to_dict() # JSON-serializable dict
belief = Belief.from_row(db_row) # Reconstruct from database row| Class | Description |
|---|---|
Belief |
Knowledge claim with confidence, domain path, and temporal validity |
Entity |
Person, tool, concept, etc. that beliefs reference |
Source |
Provenance information (type, URL, content hash) |
Tension |
Contradiction between beliefs with severity and resolution status |
BeliefEntity |
Junction linking a belief to an entity with a role |
| Class | Description |
|---|---|
Session |
A conversation session with platform, themes, metadata |
Exchange |
A single turn (user/assistant/system) |
Pattern |
Behavioral pattern observed across sessions |
SessionInsight |
Link between a session and an extracted belief |
| Symbol | Description |
|---|---|
TemporalValidity |
Time-bounded validity with factory methods and queries |
SupersessionChain |
Tracks belief evolution through supersessions |
calculate_freshness() |
Exponential decay scoring (configurable half-life) |
freshness_label() |
Human-readable freshness labels |
BeliefStatus, EntityType, EntityRole, SessionStatus, Platform, ExchangeRole, PatternStatus, TensionType, TensionSeverity, TensionStatus
# Install with dev dependencies
make dev
# Run linters
make lint
# Run tests
make test
# Run tests with coverage
make test-cov
# Auto-format
make formatNone directly. This package defines data shapes — state is owned by the database layer (our-db) and the substrate that persists these models.
This brick is part of the Valence knowledge substrate. See our-infra for ourochronos conventions.
MIT