our-models 0.1.0__tar.gz

our_models-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '*.md'
+      - 'docs/**'
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    uses: ourochronos/our-infra/.github/workflows/lint.yml@main
+    with:
+      extra-install: "git+https://github.com/ourochronos/our-confidence.git"
+  test:
+    needs: lint
+    uses: ourochronos/our-infra/.github/workflows/test.yml@main
+    with:
+      extra-install: "git+https://github.com/ourochronos/our-confidence.git"

our_models-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,13 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    uses: ourochronos/our-infra/.github/workflows/release.yml@main
+    secrets: inherit

our_models-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Type checking
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

our_models-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: []
+        args: [--config-file=pyproject.toml]
+        stages: [commit]
+        language: system
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.7.8
+    hooks:
+      - id: bandit
+        args: ['-q', '--severity-level', 'medium']
+        exclude: tests/

our_models-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project structure

our_models-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Jacobs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

our_models-0.1.0/Makefile

@@ -0,0 +1,38 @@
+.PHONY: help install dev lint format test test-unit test-int test-cov clean
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install package
+	pip install -e .
+
+dev: ## Install package with dev dependencies
+	pip install -e ".[dev]"
+	pre-commit install
+
+lint: ## Run linters (ruff + mypy)
+	ruff check src/ tests/
+	ruff format --check src/ tests/
+	mypy src/
+
+format: ## Auto-format code
+	ruff check --fix src/ tests/
+	ruff format src/ tests/
+
+test: test-unit ## Run tests (unit only by default)
+
+test-unit: ## Run unit tests
+	pytest tests/ -m "not integration and not slow" -v
+
+test-int: ## Run integration tests
+	pytest tests/ -m integration -v --timeout=60
+
+test-all: ## Run all tests
+	pytest tests/ -v --timeout=120
+
+test-cov: ## Run tests with coverage report
+	pytest tests/ -m "not integration and not slow" --cov --cov-report=term-missing --cov-report=html
+
+clean: ## Remove build artifacts and caches
+	rm -rf build/ dist/ *.egg-info .pytest_cache .mypy_cache .ruff_cache htmlcov .coverage
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

our_models-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: our-models
+Version: 0.1.0
+Summary: Data models with temporal validity and dimensional confidence for the ourochronos ecosystem
+Project-URL: Homepage, https://github.com/ourochronos/our-models
+Project-URL: Repository, https://github.com/ourochronos/our-models
+Author: Chris Jacobs
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: our-confidence>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+pip install our-models
+```
+
+Requires `our-confidence>=0.1.0`.
+
+## Usage
+
+### Beliefs
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+# 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
+
+| 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 |
+
+### Conversation Models
+
+| 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 |
+
+### Temporal
+
+| 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 |
+
+### Enums
+
+`BeliefStatus`, `EntityType`, `EntityRole`, `SessionStatus`, `Platform`, `ExchangeRole`, `PatternStatus`, `TensionType`, `TensionSeverity`, `TensionStatus`
+
+## Development
+
+```bash
+# 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](https://github.com/ourochronos/valence) knowledge substrate. See [our-infra](https://github.com/ourochronos/our-infra) for ourochronos conventions.
+
+## License
+
+MIT

our_models-0.1.0/README.md

@@ -0,0 +1,170 @@
+# 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
+
+```bash
+pip install our-models
+```
+
+Requires `our-confidence>=0.1.0`.
+
+## Usage
+
+### Beliefs
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+# 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
+
+| 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 |
+
+### Conversation Models
+
+| 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 |
+
+### Temporal
+
+| 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 |
+
+### Enums
+
+`BeliefStatus`, `EntityType`, `EntityRole`, `SessionStatus`, `Platform`, `ExchangeRole`, `PatternStatus`, `TensionType`, `TensionSeverity`, `TensionStatus`
+
+## Development
+
+```bash
+# 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](https://github.com/ourochronos/valence) knowledge substrate. See [our-infra](https://github.com/ourochronos/our-infra) for ourochronos conventions.
+
+## License
+
+MIT

our_models-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "our-models"
+version = "0.1.0"
+description = "Data models with temporal validity and dimensional confidence for the ourochronos ecosystem"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Chris Jacobs" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "our-confidence>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ourochronos/our-models"
+Repository = "https://github.com/ourochronos/our-models"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=4.0",
+    "pytest-mock>=3.12",
+    "ruff>=0.4",
+    "mypy>=1.10",
+    "pre-commit>=3.7",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/our_models"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "C4"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["our_models"]
+
+[tool.mypy]
+python_version = "3.11"
+disallow_untyped_defs = true
+strict_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = ["our_confidence", "our_confidence.*"]
+ignore_missing_imports = true
+follow_untyped_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "unit: Unit tests (no external dependencies)",
+    "integration: Integration tests (require external services)",
+    "slow: Slow tests (>5s)",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["src/our_models"]
+
+[tool.coverage.report]
+show_missing = true

our_models-0.1.0/src/our_models/__init__.py

@@ -0,0 +1,57 @@
+"""our-models -- Data models with temporal validity and dimensional confidence for the ourochronos ecosystem."""
+
+__version__ = "0.1.0"
+
+from .models import (
+    Belief,
+    BeliefEntity,
+    BeliefStatus,
+    Entity,
+    EntityRole,
+    EntityType,
+    Exchange,
+    ExchangeRole,
+    Pattern,
+    PatternStatus,
+    Platform,
+    Session,
+    SessionInsight,
+    SessionStatus,
+    Source,
+    Tension,
+    TensionSeverity,
+    TensionStatus,
+    TensionType,
+)
+from .temporal import (
+    SupersessionChain,
+    TemporalValidity,
+    calculate_freshness,
+    freshness_label,
+)
+
+__all__ = [
+    "Belief",
+    "BeliefEntity",
+    "BeliefStatus",
+    "Entity",
+    "EntityRole",
+    "EntityType",
+    "Exchange",
+    "ExchangeRole",
+    "Pattern",
+    "PatternStatus",
+    "Platform",
+    "Session",
+    "SessionInsight",
+    "SessionStatus",
+    "Source",
+    "SupersessionChain",
+    "TemporalValidity",
+    "Tension",
+    "TensionSeverity",
+    "TensionStatus",
+    "TensionType",
+    "calculate_freshness",
+    "freshness_label",
+]

our_models-0.1.0/src/our_models/interface.py

@@ -0,0 +1,15 @@
+"""Public interface for our-models.
+
+This brick provides data models (dataclasses) and enums rather than
+abstract interfaces. The models themselves ARE the public contract.
+
+Core types:
+    - Belief, Entity, Source, Tension -- knowledge substrate models
+    - Session, Exchange, Pattern, SessionInsight -- conversation tracking models
+    - TemporalValidity, SupersessionChain -- temporal utilities
+    - calculate_freshness, freshness_label -- freshness scoring
+
+All types are re-exported from the package root:
+
+    from our_models import Belief, TemporalValidity
+"""