Skip to content

README.md

Latest commit

 

History

History
108 lines (80 loc) · 4.75 KB

README.md

File metadata and controls

108 lines (80 loc) · 4.75 KB
Raw

Timonelo

Evidence-first cruise intelligence.

Explainable knowledge about ships, cabins, routes and ports — with provenance, uncertainty and geometry kept visible.

Trust is part of the product. UNKNOWN is a valid answer.

Evidence → Knowledge → Geometry → Graph → Intelligence → Explainability → User

Timonelo is an experimental Cruise Intelligence Platform built to answer not only what is true, but why the system believes it is true.

1. What Timonelo Is

Timonelo is a Cruise Intelligence Platform. Its purpose is to provide explainable, evidence-based answers about ships, cabins, routes and ports.

Every passenger-facing statement is grounded in verifiable evidence. If a fact cannot be traced to physical evidence or deterministic derivation, it is explicitly rendered as UNKNOWN.

Core governing principle:

Timonelo must be able to say “we do not know” before it is allowed to say “this is true.”

2. Canonical Architecture

Evidence
    ↓  (Physical artifacts, byte verification, SHA-256)
Knowledge
    ↓  (Truth statements, multi-axial epistemic model, authority matrix)
Geometry
    ↓  (Proven coordinate envelopes, vector slices, scale transforms)
Graph
    ↓  (W3C BOT topology, lift shafts, vertical core transit, adjacencies)
Intelligence
    ↓  (Acoustics, sightlines, solar orientation, distance calculations)
Explainability
    ↓  (Why-trace, evidence citations, epistemic badges, review history)
User
       (Passenger-facing digital twin and intelligence interface)

Knowledge flows downward only. No downstream layer may silently manufacture canonical truth.

3. Scientific Epistemic Model (ADR-0002)

Dimension Canonical Values Meaning
Method DIRECT, CALCULATED, INFERRED How the statement was formed.
Derivation LOCAL, SISTER_SHIP, REFERENCE_MODEL, GENERATED The origin of the underlying data.
Review State DRAFT, SUBMITTED, CURATOR_REVIEWED, PUBLISHED Governance workflow status.
Conflict UNRESOLVED, RESOLVED Independent conflict tracking (no auto-resolving).
Geometry Provenance DIRECT_SOURCE_GEOMETRY, TRANSFORMED_SOURCE_GEOMETRY, DERIVED_GEOMETRY, SYNTHETIC_GEOMETRY, UNKNOWN_PROVENANCE Provenance of spatial coordinates.
Confidence Computed dynamic metric $\in [0.0, 1.0]$ Never a stored literal in ground truth.

4. Governance & Role Separation

  • Evidence Gatekeeper: Absolute trust gate. Verifies SHA-256 of physical bytes on disk, enforces epistemic ceilings, and blocks publication if unverified synthetic data or unresolved conflicts exist.
  • Bridge Officer Tim: Orchestration and operational coordination only. It may request audits, summarize evidence, and expose uncertainty. It may NOT declare facts true, approve conflicts on its own, publish canonical knowledge, manufacture provenance, or override the Evidence Gatekeeper.
  • Quarantined Hypothesis Tools: Legacy patch engines and archetype generators (src/timonelo/factory/patch_engine.py, src/timonelo/factory/archetype_generator.py) operate strictly in data/hypotheses/ and are prohibited from authoring canonical truth in knowledge/ships/.

5. Repository Structure

timonelo/
├── knowledge/           # Canonical ground truth & physical evidence vault
│   ├── ships/           # Vessel knowledge (msc-bellissima, etc.)
│   ├── evidence/        # Physical artifacts with verified SHA-256
│   └── reports/         # Audits and architectural verification reports
├── src/timonelo/        # Backend Python package
│   ├── evidence/        # Evidence Gatekeeper, candidate bridge, harvester
│   ├── ontology/        # Canonical Pydantic models (BOT, Epistemology)
│   ├── database/        # Compiler, Bridge Officer orchestrator
│   └── factory/         # Quarantined hypothesis tools
├── frontend/            # Vite + React + TypeScript web application
│   └── src/
│       ├── living-deck/ # Living Deck Plan spatial viewer
│       ├── knowledge/   # Knowledge repository & pipeline gatekeeper
│       ├── intelligence/# Acoustic & distance calculation engines
│       └── explainability/ # Why-Trace & evidence inspector
├── docs/                # Architectural canon (ADR-0001 .. ADR-0004, etc.)
└── tests/               # Pytest suite & truth verification tests

6. Verification & Pre-flight Checks

# Backend pytest suite (100% green required)
python -m pytest tests/ -v

# Frontend TypeScript type check (strict, 0 errors required)
npm.cmd --prefix frontend run typecheck

# Frontend production build
npm.cmd --prefix frontend run build