kairopsis 0.1.0__py3-none-any.whl

kairopsis/__init__.py

@@ -0,0 +1,20 @@
+"""Relative-value idea generation powered by metapyle."""
+
+
+def main() -> None:
+    """Launch the installed application without runtime dependency resolution."""
+    import logging
+    from logging.handlers import RotatingFileHandler
+
+    import uvicorn
+
+    from .app import create_app
+    from .config import load_settings
+
+    settings = load_settings()
+    for path in (settings.config_dir, settings.cache_dir, settings.log_dir):
+        path.mkdir(parents=True, exist_ok=True)
+    logging.getLogger("kairopsis").addHandler(RotatingFileHandler(
+        settings.log_dir / "kairopsis.log", maxBytes=1_000_000, backupCount=2, encoding="utf-8"
+    ))
+    uvicorn.run(create_app(settings), host=settings.host, port=settings.port)

kairopsis/analytics.py

@@ -0,0 +1,160 @@
+"""Exact-date metrics, input risk normalization and intercept OLS."""
+from bisect import bisect_right
+from datetime import date, datetime
+from math import fsum, isfinite
+from typing import cast
+from .frequencies import expected_session, horizon_target, previous_session, shift_years
+from .risk import transform_inputs
+from .models import AdjustmentEstimate, DataRequest, DataResponse, Evaluation, Fit, MetricPoint, ResolvedDefinition
+
+
+def condition_rules(definition: ResolvedDefinition, unit: str, percentile: float | None, change: float | None, eligible: bool) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    reasons, keys = [], []
+    settings = definition.settings
+    if eligible and percentile is not None and (percentile >= settings.upper_percentile or percentile <= 100 - settings.upper_percentile):
+        reasons.append(f"Historical standing {percentile:.1f}th percentile / {settings.history_years}y")
+        keys.append("upper" if percentile >= settings.upper_percentile else "lower")
+    if eligible and change is not None and settings.move_threshold is not None and abs(change) >= settings.move_threshold:
+        reasons.append(f"{change:+.2f} {unit} / {settings.horizon} meets configured {settings.move_threshold:g} {unit} rule")
+        keys.append("move")
+    return tuple(reasons), tuple(keys)
+
+
+def regression(points: list[MetricPoint], current: date, definition: ResolvedDefinition, years: int) -> Fit | None:
+    start = shift_years(current, -years)
+    sample = [p for p in points if p.eligible and start <= p.date < current]
+    if len(sample) < definition.settings.minimum_fit or (sample[0].date - start).days > 7 or (previous_session(current) - sample[-1].date).days > 7:
+        return None
+    xs = [cast(float, (p.transformed_inputs or p.inputs)[1]) for p in sample]
+    ys = [cast(float, (p.transformed_inputs or p.inputs)[0]) for p in sample]
+    xm, ym = fsum(xs) / len(xs), fsum(ys) / len(ys)
+    xx = fsum((x - xm) ** 2 for x in xs)
+    if not xx:
+        return None
+    slope = fsum((x - xm) * (y - ym) for x, y in zip(xs, ys)) / xx
+    intercept = ym - slope * xm
+    yy = fsum((y - ym) ** 2 for y in ys)
+    sse = fsum((y - intercept - slope * x) ** 2 for x, y in zip(xs, ys))
+    if not all(isfinite(v) for v in (slope, intercept, sse, yy)):
+        return None
+    return Fit(slope=slope, intercept=intercept, r_squared=1-sse/yy if yy else None,
+               sample_count=len(sample), start=sample[0].date, end=sample[-1].date, x_min=min(xs), x_max=max(xs))
+
+
+def evaluate(definition: ResolvedDefinition, data: DataResponse, request: DataRequest, now: datetime) -> Evaluation:
+    results = {s.binding.id: s for s in data.series}
+    bindings = (*definition.inputs, *definition.references)
+    if data.failures or any(b.id not in results for b in bindings):
+        raise ValueError("Retrieval incomplete: " + "; ".join(f.message for f in data.failures))
+    all_rows = {}
+    for binding in bindings:
+        result = results[binding.id]
+        if result.binding != binding:
+            raise ValueError("Provider returned a different resolved binding")
+        dates = [p.date for p in result.observations]
+        if len(dates) != len(set(dates)):
+            raise ValueError("Duplicate daily observations")
+        all_rows[binding.id] = {p.date: p for p in result.observations if request.start <= p.date <= request.end}
+    rows = [all_rows[b.id] for b in definition.inputs]
+    days = sorted(set().union(*(r.keys() for r in rows)))
+    transformed: dict[date, tuple[float | None, ...]] = {}
+    scales: dict[date, tuple[float | None, ...]] = {}
+    starts: dict[date, tuple[date | None, ...]] = {}
+    input_units = tuple(b.unit for b in definition.inputs)
+    estimates: tuple[AdjustmentEstimate, ...] = ()
+    if definition.settings.measure != "level":
+        transformed, scales, starts, input_units, estimates = transform_inputs(definition, all_rows, days)
+    method = definition.calculation
+    if method == "difference" and input_units[0] != input_units[1]:
+        raise ValueError("Difference requires matching units; no implicit conversion")
+    unit = input_units[0]
+    if method == "ratio":
+        unit = "×" if unit == input_units[1] else f"{unit}/{input_units[1]}"
+    points = []
+    limits = []
+    for day in days:
+        inputs = tuple(r[day].value if day in r else None for r in rows)
+        observed = tuple(r[day].observed_on if day in r else None for r in rows)
+        measured = transformed.get(day, inputs)
+        usable = all(v is not None for v in measured)
+        eligible = usable and all(d == day for d in observed) and day.weekday() < 5
+        value = None
+        if usable:
+            left = cast(float, measured[0])
+            if method in ("level", "regression"):
+                value = left
+            elif method == "difference":
+                value = left - cast(float, measured[1])
+            elif measured[1]:
+                value = left / cast(float, measured[1])
+        if value is not None and not isfinite(value):
+            value = None
+        points.append(MetricPoint(date=day, value=value, inputs=inputs, observed_on=observed, eligible=eligible and value is not None,
+            transformed_inputs=transformed.get(day, ()), risk_scales=scales.get(day, ()), period_start=starts.get(day, ())))
+    fit = None
+    sensitivity = []
+    current_day = points[-1].date if points else None
+    if method == "regression" and current_day:
+        fit = regression(points, current_day, definition, definition.settings.fit_years)
+        if not fit:
+            limits.append("Fit unavailable: insufficient full-window history or constant explanatory input")
+        else:
+            limits.append("Residual history uses the current fit retrospectively; association is descriptive")
+            x = (points[-1].transformed_inputs or points[-1].inputs)[1]
+            if x is not None and not fit.x_min <= x <= fit.x_max:
+                limits.append("Current explanatory input is outside fit range (extrapolation)")
+            selected = (points[-1].transformed_inputs or points[-1].inputs)[0]
+            for years in (1, 5):
+                alternative = regression(points, current_day, definition, years)
+                if not alternative:
+                    sensitivity.append(f"{years}y comparison unavailable: insufficient fit history")
+                elif selected is not None and x is not None:
+                    a = selected - fit.intercept - fit.slope * x
+                    b = selected - alternative.intercept - alternative.slope * x
+                    if a * b < 0:
+                        sensitivity.append(f"Residual direction changes under {years}y fit")
+        points = [p.model_copy(update={"value": (cast(float, (p.transformed_inputs or p.inputs)[0]) - fit.intercept - fit.slope * cast(float, (p.transformed_inputs or p.inputs)[1]))
+            if fit and all(v is not None for v in (p.transformed_inputs or p.inputs)) else None,
+            "eligible": p.eligible and fit is not None}) for p in points]
+    current = points[-1] if points else None
+    for binding, estimate in zip(definition.inputs, estimates):
+        if estimate.limitation:
+            limits.append(f"{binding.name}: {estimate.limitation}")
+    percentile = change = None
+    change_start = None
+    eligible = bool(current and current.eligible and current.date == expected_session(request.end))
+    if not current or current.value is None:
+        limits.append("Current calculation unavailable (missing input or zero denominator)")
+    elif not current.eligible:
+        limits.append("Missing, carried, unknown or mismatched native observations; excluded from findings")
+    if current and current.date < expected_session(request.end):
+        limits.append(f"Stale observations: latest row {current.date}; requested as of {request.end}")
+    if data.outcome not in ("synthetic", "fresh"):
+        eligible = False
+        limits.append("Upstream retrieval freshness unverified; excluded from findings")
+    if current and current.value is not None:
+        value = current.value
+        history = [p.value for p in points if p.eligible and p.value is not None and shift_years(current.date, -definition.settings.history_years) <= p.date < current.date]
+        if len(history) >= definition.settings.minimum_history:
+            percentile = 100 * (sum(v < value for v in history) + .5 * sum(v == value for v in history)) / len(history)
+        else:
+            eligible = False
+            limits.append(f"Insufficient reference history: {len(history)}; require {definition.settings.minimum_history}")
+        target = horizon_target(current.date, definition.settings.horizon)
+        valid = [p for p in points if p.eligible and p.value is not None]
+        idx = bisect_right([p.date for p in valid], target) - 1
+        if definition.settings.measure != "level" and current.eligible:
+            change = value
+            change_start = min((d for d in current.period_start if d is not None), default=None)
+        elif idx >= 0 and (target - valid[idx].date).days <= (0 if definition.settings.horizon == "day" else 3) and current.eligible:
+            change = value - cast(float, valid[idx].value)
+            change_start = valid[idx].date
+        else:
+            limits.append(f"{definition.settings.horizon.title()} change unavailable: missing eligible baseline")
+    reasons, keys = condition_rules(definition, unit, percentile, change, eligible)
+    return Evaluation(definition=definition, request=request, data=data, evaluated_at=now, points=tuple(points), unit=unit,
+        input_units=input_units, adjustment_estimates=estimates,
+        current=current.value if current else None, observation_date=current.date if current else None,
+        input_dates=current.observed_on if current else (), percentile=percentile, change=change, change_start=change_start,
+        eligible=eligible, limitations=tuple(limits), fit=fit, sensitivity=tuple(sensitivity), reasons=reasons, conditions=reasons, condition_keys=keys,
+        finding="condition" if reasons else "quiet" if eligible else "unavailable")

kairopsis/app.py

@@ -0,0 +1,235 @@
+"""One supported three-destination application; all evidence passes real persistence."""
+import base64
+import hashlib
+from collections.abc import Callable
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Literal
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse, Response
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from pydantic import BaseModel, Field
+
+from .catalogue import Catalogue
+from .config import Settings
+from .fixtures import MockMarketData
+from .metapyle_adapter import MetapyleMarketData
+from .models import AnalysisDefinition, DisplaySettings, SeriesBinding
+from .repository import Repository
+from .service import MarketData, Research
+
+
+class CaptureRequest(BaseModel):
+    evaluation_id: str
+    display: DisplaySettings = Field(default_factory=DisplaySettings)
+    image: str = Field(max_length=16_000_000)
+    title: str = Field(default="", max_length=200)
+    thought: str = Field(default="", max_length=50000)
+    idea_id: str | None = None
+    note: str = Field(default="", max_length=50000)
+    mode: Literal["saved", "latest", "investigation"] = "investigation"
+
+    def png(self) -> bytes:
+        try:
+            return base64.b64decode(self.image.removeprefix("data:image/png;base64,"), validate=True)
+        except ValueError:
+            raise ValueError("Invalid PNG encoding") from None
+
+
+class IdeaEdit(BaseModel):
+    title: str | None = Field(default=None, min_length=1, max_length=200)
+    thought: str | None = Field(default=None, max_length=50000)
+    shortlisted: bool | None = None
+    archived: bool | None = None
+
+
+class NoteEdit(BaseModel):
+    text: str = Field(max_length=50000)
+
+
+def create_app(settings: Settings | None = None, market_data: MarketData | None = None,
+               clock: Callable[[], datetime] | None = None) -> FastAPI:
+    settings = settings or Settings()
+    clock = clock or (lambda: datetime.now(timezone.utc))
+    repository = Repository(settings.workspace, settings.mode)
+    catalogue = Catalogue(repository)
+    provider = market_data or (MockMarketData(clock) if settings.mode == "mock" else MetapyleMarketData(settings, clock))
+    research = Research(repository, catalogue, provider, clock, settings.timezone)
+    app = FastAPI(title="Kairopsis", docs_url=None, redoc_url=None)
+    app.state.repository, app.state.research = repository, research
+    app.state.settings = settings
+    package = Path(__file__).resolve().parent
+    templates = Jinja2Templates(directory=package / "templates")
+    app.mount("/static", StaticFiles(directory=package / "static"), name="static")
+
+    def asset_url(name: str) -> str:
+        version = hashlib.sha256((package / "static" / name).read_bytes()).hexdigest()[:16]
+        return f"/static/{name}?v={version}"
+
+    templates.env.globals["asset_url"] = asset_url
+
+    @app.exception_handler(FileNotFoundError)
+    async def missing(request: Request, error: FileNotFoundError):
+        return JSONResponse(status_code=404, content={"detail": "Record not found; existing evidence preserved"})
+
+    @app.exception_handler(ValueError)
+    async def invalid(request: Request, error: ValueError):
+        return JSONResponse(status_code=422, content={"detail": str(error)})
+
+    @app.exception_handler(OSError)
+    async def write_failed(request: Request, error: OSError):
+        return JSONResponse(status_code=503, content={"detail": "Evidence could not be read/saved. Check writable workspace and free disk space; retry. Export is incomplete."})
+
+    def page(request, name):
+        research.first_open()
+        return templates.TemplateResponse(request=request, name="app.html", context={"page": name, "mode": settings.mode})
+
+    @app.get("/", response_class=HTMLResponse)
+    def root():
+        return RedirectResponse("/analyses")
+
+    @app.get("/analyses", response_class=HTMLResponse)
+    def analyses_page(request: Request):
+        return page(request, "analyses")
+
+    @app.get("/analyses/{key}", response_class=HTMLResponse)
+    def chart_page(request: Request, key: str):
+        catalogue.resolve(key)
+        return page(request, "chart")
+
+    @app.get("/ideas", response_class=HTMLResponse)
+    def ideas_page(request: Request):
+        return page(request, "ideas")
+
+    @app.get("/ideas/{key}", response_class=HTMLResponse)
+    def idea_page(request: Request, key: str):
+        repository.get_idea(key)
+        return page(request, "idea")
+
+    @app.get("/library", response_class=HTMLResponse)
+    def library_page(request: Request):
+        return page(request, "library")
+
+    @app.get("/api/analyses")
+    def rows(scope: Literal["all", "flagged"] = "flagged", q: str = "", kind: Literal["all", "standalone", "pair"] = "all"):
+        research.first_open()
+        return research.rows(scope, q, kind)
+
+    @app.post("/api/refresh")
+    def refresh():
+        return research.refresh()
+
+    @app.get("/api/library")
+    def library():
+        return catalogue.records()
+
+    @app.post("/api/library/series")
+    def save_series(record: SeriesBinding):
+        return catalogue.save("series", record)
+
+    @app.post("/api/library/analyses")
+    def save_analysis(record: AnalysisDefinition):
+        return catalogue.save("analyses", record)
+
+    @app.delete("/api/library/{kind}/{key}")
+    def delete_catalogue(kind: Literal["series", "analyses"], key: str):
+        catalogue.delete(kind, key)
+        return {"ok": True}
+
+    @app.post("/api/analyses/{key}/preview")
+    def preview(key: str, options: dict):
+        return research.preview(key, options)
+
+    @app.get("/api/evaluations/{key}")
+    def evaluation(key: str):
+        return repository.get_evaluation(key)
+
+    @app.post("/api/ideas")
+    def add_chart(body: CaptureRequest):
+        evaluation = repository.get_evaluation(body.evaluation_id)
+        return repository.add_chart(evaluation, body.display, body.png(), clock(), body.title, body.thought, body.idea_id, body.note)
+
+    @app.get("/api/ideas")
+    def ideas(q: str = "", scope: Literal["active", "shortlist", "archived"] = "active"):
+        found = []
+        for idea in repository.list_ideas():
+            text = " ".join([idea.title, idea.thought, *[n.text for n in idea.notes], *[c.note for c in idea.charts]])
+            if q.casefold() not in text.casefold():
+                continue
+            if idea.archived != (scope == "archived") or (scope == "shortlist" and not idea.shortlisted):
+                continue
+            found.append({"idea": idea.model_dump(mode="json"), "changes": research.idea_changes(idea)})
+        return found
+
+    @app.get("/api/ideas/{key}")
+    def idea(key: str):
+        result = repository.get_idea(key)
+        return {"idea": result.model_dump(mode="json"), "snapshots": {c.id: repository.get_snapshot(key, c.snapshot_id).model_dump(mode="json") for c in result.charts},
+                "changes": research.idea_changes(result)}
+
+    @app.patch("/api/ideas/{key}")
+    def edit_idea(key: str, body: IdeaEdit):
+        return repository.update_idea(key, body.model_dump(exclude_none=True), clock())
+
+    @app.post("/api/ideas/{key}/notes")
+    def add_note(key: str, body: NoteEdit):
+        now = clock()
+        return repository.modify_idea(key, lambda idea: idea.add_note(body.text, now), now)
+
+    @app.patch("/api/ideas/{key}/notes/{note_id}")
+    def edit_note(key: str, note_id: str, body: NoteEdit):
+        now = clock()
+        return repository.modify_idea(key, lambda idea: idea.change_note(note_id, body.text, now), now)
+
+    @app.delete("/api/ideas/{key}/notes/{note_id}")
+    def delete_note(key: str, note_id: str):
+        now = clock()
+        return repository.modify_idea(key, lambda idea: idea.change_note(note_id, None, now), now)
+
+    @app.patch("/api/ideas/{key}/charts/{entry_id}")
+    def chart_note(key: str, entry_id: str, body: NoteEdit):
+        now = clock()
+        return repository.modify_idea(key, lambda idea: idea.annotate_chart(entry_id, body.text, now), now)
+
+    @app.delete("/api/ideas/{key}/charts/{entry_id}")
+    def remove_chart(key: str, entry_id: str):
+        return repository.modify_idea(key, lambda idea: idea.remove_chart(entry_id), clock())
+
+    def chart_snapshot(key, entry_id):
+        result = repository.get_idea(key)
+        entry = next((c for c in result.charts if c.id == entry_id), None)
+        if not entry:
+            raise FileNotFoundError()
+        return repository.get_snapshot(key, entry.snapshot_id)
+
+    @app.post("/api/ideas/{key}/charts/{entry_id}/latest")
+    def latest(key: str, entry_id: str):
+        saved = chart_snapshot(key, entry_id)
+        try:
+            return {"evaluation": research.evaluate(saved.evaluation.definition)}
+        except (ValueError, OSError) as error:
+            return {"unavailable": str(error)}
+
+    @app.get("/api/ideas/{key}/snapshots/{snapshot_id}/image")
+    def image(key: str, snapshot_id: str):
+        return Response(repository.snapshot_image(key, snapshot_id), media_type="image/png")
+
+    @app.post("/api/ideas/{key}/charts/{entry_id}/export")
+    def export(key: str, entry_id: str, body: CaptureRequest):
+        saved = chart_snapshot(key, entry_id)
+        evaluation = saved.evaluation if body.mode == "saved" else repository.get_evaluation(body.evaluation_id)
+        if body.mode == "saved" and body.evaluation_id != saved.evaluation.id:
+            raise ValueError("Export must match displayed saved evidence")
+        if (body.mode == "saved" and evaluation.id != saved.evaluation.id) or (body.mode == "latest" and evaluation.definition != saved.evaluation.definition) or body.mode == "investigation":
+            raise ValueError("Export must match displayed saved evidence or its preserved Latest definition")
+        if (body.display.years, body.display.view) != (saved.display.years, saved.display.view):
+            raise ValueError("Export must preserve displayed settings")
+        png = body.png()
+        with repository.transaction():
+            snapshot = repository.capture(key, evaluation, body.display, png, body.mode, clock())
+        return Response(png, media_type="image/png", headers={"X-Snapshot-ID": snapshot.id,
+            "Content-Disposition": 'attachment; filename="kairopsis-chart.png"'})
+
+    return app

kairopsis/catalogue.py

@@ -0,0 +1,93 @@
+"""Small active catalogue. Binding changes advance affected resolved definitions."""
+from .fixtures import analysis_fixture, series_fixture
+from .models import AnalysisDefinition, AnalysisSettings, ResolvedDefinition, SeriesBinding
+from .repository import Repository
+from .risk import adjusted_unit
+from .metapyle_catalogue import publish_catalogue
+from .repository import atomic_bytes
+
+
+class Catalogue:
+    def __init__(self, repository: Repository):
+        self.repository = repository
+        with repository.transaction():
+            if repository.read_json("catalogue") is None:
+                repository.write_json("catalogue", {
+                    "series": [s.model_dump(mode="json") for s in series_fixture()] if repository.mode == "mock" else [],
+                    "analyses": [a.model_dump(mode="json") for a in analysis_fixture()] if repository.mode == "mock" else []})
+            self._publish(self.records())
+
+    @property
+    def metapyle_path(self):
+        return self.repository.root / "metapyle.yaml"
+
+    def _publish(self, records: dict) -> None:
+        publish_catalogue(self.metapyle_path, tuple(SeriesBinding.model_validate(s) for s in records["series"]))
+
+    def _commit(self, records: dict) -> None:
+        # JSON publishes metadata/analyses together. YAML is a recoverable
+        # projection, restored on a failed commit and rebuilt at startup.
+        previous = self.metapyle_path.read_bytes()
+        self._publish(records)
+        try:
+            self.repository.write_json("catalogue", records)
+        except OSError:
+            atomic_bytes(self.metapyle_path, previous)
+            raise
+
+    def records(self) -> dict:
+        return self.repository.read_json("catalogue")
+
+    def resolve(self, key: str, settings: AnalysisSettings | None = None) -> ResolvedDefinition:
+        records = self.records()
+        analysis = next((AnalysisDefinition.model_validate(a) for a in records["analyses"] if a["id"] == key), None)
+        if not analysis:
+            raise FileNotFoundError("Analysis not found")
+        series = {s["id"]: SeriesBinding.model_validate(s) for s in records["series"]}
+        if settings is not None:
+            analysis = AnalysisDefinition.model_validate({**analysis.model_dump(), "settings": settings})
+        reference_ids = risk_references(analysis)
+        if any(i not in series for i in reference_ids):
+            raise ValueError("Choose an existing risk reference series")
+        return ResolvedDefinition(id=analysis.id, revision=analysis.revision, name=analysis.name,
+            calculation=analysis.calculation, settings=analysis.settings, inputs=tuple(series[i] for i in analysis.series_ids),
+            references=tuple(series[i] for i in sorted(reference_ids - set(analysis.series_ids))))
+
+    def save(self, kind: str, record: SeriesBinding | AnalysisDefinition) -> dict:
+        with self.repository.transaction():
+            records = self.records()
+            old = next((r for r in records[kind] if r["id"] == record.id), None)
+            value = record.model_dump(mode="json")
+            value["revision"] = old["revision"] + 1 if old else 1
+            if kind == "analyses":
+                definition = AnalysisDefinition.model_validate(value)
+                series = {s["id"]: s for s in records["series"]}
+                if any(i not in series for i in definition.series_ids):
+                    raise ValueError("Choose existing input series")
+                if any(i not in series for i in risk_references(definition)):
+                    raise ValueError("Choose an existing risk reference series")
+                units = [adjusted_unit(series[i]["unit"], series[r.reference_id or i]["unit"] if r.method != "none" else series[i]["unit"],
+                    r.method, definition.settings.measure) for i, r in zip(definition.series_ids, definition.settings.adjustments(len(definition.series_ids)))]
+                if definition.calculation == "difference" and len(set(units)) != 1:
+                    raise ValueError("Difference requires matching units")
+            elif old:
+                records["analyses"] = [{**a, "revision": a["revision"] + 1} if record.id in set(a["series_ids"]) | risk_references(AnalysisDefinition.model_validate(a)) else a for a in records["analyses"]]
+            records[kind] = [value if r["id"] == record.id else r for r in records[kind]] if old else [*records[kind], value]
+            self._commit(records)
+            return value
+
+    def delete(self, kind: str, key: str) -> None:
+        with self.repository.transaction():
+            records = self.records()
+            if not any(r["id"] == key for r in records[kind]):
+                raise FileNotFoundError("Catalogue entry not found")
+            dependencies = [a["name"] for a in records["analyses"] if key in set(a["series_ids"]) | risk_references(AnalysisDefinition.model_validate(a))] if kind == "series" else []
+            if dependencies:
+                raise ValueError("Used by: " + ", ".join(dependencies))
+            records[kind] = [r for r in records[kind] if r["id"] != key]
+            self._commit(records)
+
+
+def risk_references(analysis: AnalysisDefinition) -> set[str]:
+    return {r.reference_id for r in analysis.settings.adjustments(len(analysis.series_ids))
+            if r.method != "none" and r.reference_id is not None}

kairopsis/config.py

@@ -0,0 +1,74 @@
+"""User-writable paths and launch settings; never infer paths from cwd."""
+
+import argparse
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from platformdirs import user_cache_path, user_config_path, user_data_path, user_log_path
+
+
+@dataclass(frozen=True)
+class Settings:
+    workspace: Path = field(default_factory=lambda: user_data_path("Kairopsis", appauthor=False) / "mock")
+    config_dir: Path = field(default_factory=lambda: user_config_path("Kairopsis", appauthor=False))
+    cache_dir: Path = field(default_factory=lambda: user_cache_path("Kairopsis", appauthor=False))
+    log_dir: Path = field(default_factory=lambda: user_log_path("Kairopsis", appauthor=False))
+    mode: Literal["mock", "live"] = "mock"
+    host: str = "127.0.0.1"
+    port: int = 8765
+    timezone: str = "Europe/London"
+
+    def __post_init__(self) -> None:
+        package = Path(__file__).resolve().parent
+        for name in ("workspace", "config_dir", "cache_dir", "log_dir"):
+            path = Path(getattr(self, name)).expanduser()
+            if not path.is_absolute():
+                raise ValueError(f"{name} must be an absolute path, independent of the working directory")
+            path = path.resolve()
+            if path == package or package in path.parents:
+                raise ValueError(f"{name} must be outside the installed package")
+            object.__setattr__(self, name, path)
+        if self.mode not in ("mock", "live"):
+            raise ValueError("mode must be mock or live")
+        if not 1 <= self.port <= 65535:
+            raise ValueError("port must be between 1 and 65535")
+        try:
+            ZoneInfo(self.timezone)
+        except (ZoneInfoNotFoundError, ValueError):
+            raise ValueError("timezone must be an available IANA timezone, for example Europe/London") from None
+
+
+def load_settings(argv: list[str] | None = None) -> Settings:
+    parser = argparse.ArgumentParser(description="Local Kairopsis research dashboard")
+    parser.add_argument("--config", type=Path, help="Absolute path to an optional TOML configuration")
+    parser.add_argument("--mode", choices=("mock", "live"))
+    parser.add_argument("--host")
+    parser.add_argument("--port", type=int)
+    parser.add_argument("--timezone")
+    for name in ("workspace", "config-dir", "cache-dir", "log-dir"):
+        parser.add_argument(f"--{name}", type=Path)
+    args = vars(parser.parse_args(argv))
+    config = args.pop("config") or os.environ.get("KAIROPSIS_CONFIG")
+    values: dict = {}
+    if config:
+        config_path = Path(config).expanduser()
+        if not config_path.is_absolute():
+            parser.error("--config must be an absolute path")
+        with config_path.open("rb") as stream:
+            values = tomllib.load(stream).get("kairopsis", {})
+    for name in args:
+        environment = os.environ.get(f"KAIROPSIS_{name.upper()}")
+        if environment is not None:
+            values[name] = int(environment) if name == "port" else environment
+        if args[name] is not None:
+            values[name] = args[name]
+    if "workspace" not in values:
+        values["workspace"] = user_data_path("Kairopsis", appauthor=False) / values.get("mode", "mock")
+    try:
+        return Settings(**values)
+    except (TypeError, ValueError) as error:
+        parser.error(str(error))