kairopsis 0.1.0__tar.gz

kairopsis-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

kairopsis-0.1.0/AGENTS.md

@@ -0,0 +1,16 @@
+## Agent skills
+
+### Issue tracker
+
+Issues live as local Markdown under `.scratch/`. Before creating,
+reading, or updating tickets, read `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Use the five default triage roles. Before triaging issues, read
+`docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Use a single-context layout: root `CONTEXT.md` and `docs/adr/`.
+Before exploring the codebase, read `docs/agents/domain.md`.

kairopsis-0.1.0/CONTEXT.md

@@ -0,0 +1,78 @@
+# Kairopsis
+
+Kairopsis supports relative-value investigation and the development of investment views for team discussion.
+
+## Language
+
+**Relative Value Relationship**:
+An economically meaningful comparison between sectors, segments, or exposures whose pricing is examined for relative attractiveness, including credit exposures relative to rates and FX.
+
+**Relationship Family**:
+A set of Relative Value Relationships that share an explicit economic rationale for comparison.
+Comparisons between credit exposures in different currencies remain credit-credit relationships.
+
+**Cross-Market Inconsistency**:
+A difference in the economic implications of pricing across markets under a stated interpretation, even when no clear trade expression has been identified.
+
+**Comparison Basis**:
+The currency and reference-curve conventions underlying a metric, including any rebasing applied to make it comparable across markets.
+
+**Flag**:
+An observed condition or change in a single asset or a Relative Value Relationship that merits investigation, with an identifiable reason for drawing attention to it. Flags include extreme historical percentiles and significant changes in asset measures or pairwise ratios, differences, and regression residuals.
+_Avoid_: Investment recommendation
+
+**Economic Materiality**:
+The significance of an observed level or change to an investment argument, judged using measures appropriate to its Relationship Family.
+
+**Catch-up**:
+A retrospective examination of the most significant market and relationship changes over a user-selected period.
+_Avoid_: Unread alert backlog
+
+**Relative Value View**:
+An investment judgment about the attractiveness of one sector, segment, or exposure relative to another, supported by evidence and an economic argument.
+_Avoid_: Signal when an investment judgment is meant
+
+**Possible Expression**:
+A proposed way to express a Relative Value View through market exposures, without account-specific sizing or suitability analysis.
+_Avoid_: Account Expression
+
+**Idea**:
+A saved investigation that develops and revisits a Relative Value View, collecting supporting and challenging evidence, arguments, and possible expressions.
+_Avoid_: Individual flag or chart when referring to the whole investigation
+
+**Research Asset**:
+A chart, snapshot, note, argument, or narrative retained as part of an Idea.
+
+**Snapshot**:
+A frozen record of chart evidence at a particular time, including the underlying observations, analytical choices, and Comparison Basis.
+_Avoid_: Live chart
+
+**Research Pack**:
+A selection of an Idea's evidence and arguments assembled to support narrative drafting outside Kairopsis.
+_Avoid_: Standardized report for team distribution
+
+**Discussion Shortlist**:
+The Ideas selected for upcoming team conversations or meetings, independently of their investigation state.
+
+**Revisit Condition**:
+A stated condition whose fulfillment warrants renewed attention to an Idea.
+
+
+**Data Series**:
+A time-ordered set of observations for a particular asset measure, with an identified source, units and Comparison Basis.
+
+**Analysis**:
+A defined investigation of one or two Data Series, including its calculation and analytical settings. Its type is Standalone or Pair.
+
+**Risk Adjustment**:
+An adjustment of spread changes or returns using an estimated risk measure or sensitivity to support comparison between exposures.
+
+**Frequency**:
+The daily, weekly or monthly interval over which an Analysis measures changes or returns. Risk Adjustment estimates use the same interval.
+_Avoid_: Measurement horizon
+
+**Standalone**:
+An Analysis of one Data Series, examining its level or changes relative to its history.
+
+**Pair**:
+An Analysis relating two specified Data Series through a ratio, difference or regression.

kairopsis-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.3
+Name: kairopsis
+Version: 0.1.0
+Summary: Relative-value idea generation dashboard powered by metapyle
+Author: Stabile Frisur
+Author-email: Stabile Frisur <26568863+stabilefrisur@users.noreply.github.com>
+Requires-Dist: fastapi==0.135.2
+Requires-Dist: jinja2==3.1.6
+Requires-Dist: metapyle>=0.1.6
+Requires-Dist: pandas==3.0.6
+Requires-Dist: platformdirs==4.5.1
+Requires-Dist: pydantic==2.13.5
+Requires-Dist: tzdata==2026.4
+Requires-Dist: uvicorn==0.42.0
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/stabilefrisur/kairopsis
+Project-URL: Documentation, https://github.com/stabilefrisur/kairopsis/blob/main/src/kairopsis/docs/human-guide.md
+Project-URL: Issues, https://github.com/stabilefrisur/kairopsis/issues
+Description-Content-Type: text/markdown
+
+# Kairopsis
+
+A local workspace for relative-value research.
+
+Explore market series, compare exposures, and develop investment Ideas with
+charts and notes you can revisit. Kairopsis brings investigation and saved
+evidence together in a browser-based dashboard.
+
+- **Investigate:** levels, differences, ratios and regression residuals, with
+  historical context and optional risk adjustment.
+- **Retain evidence:** save charts, observations and notes alongside each Idea.
+- **Revisit and share:** compare saved evidence with the latest data and export
+  charts or spreadsheet-ready values.
+
+A built-in demo lets you explore without market-data credentials. Your research
+stays in a local workspace. Live data access uses Metapyle.
+
+## Guides
+
+- [Human guide](https://github.com/stabilefrisur/kairopsis/blob/main/src/kairopsis/docs/human-guide.md)
+  — everyday investigation, Ideas and exports.
+- [Agent setup guide](https://github.com/stabilefrisur/kairopsis/blob/main/src/kairopsis/docs/agent-setup.md)
+  — installation, data connections, verification and handoff.
+
+Both guides are included in the installed Python package and the source archive.
+Requires Python 3.12 or later. Frontend assets are bundled; no Node.js setup is
+needed.

kairopsis-0.1.0/README.md

@@ -0,0 +1,27 @@
+# Kairopsis
+
+A local workspace for relative-value research.
+
+Explore market series, compare exposures, and develop investment Ideas with
+charts and notes you can revisit. Kairopsis brings investigation and saved
+evidence together in a browser-based dashboard.
+
+- **Investigate:** levels, differences, ratios and regression residuals, with
+  historical context and optional risk adjustment.
+- **Retain evidence:** save charts, observations and notes alongside each Idea.
+- **Revisit and share:** compare saved evidence with the latest data and export
+  charts or spreadsheet-ready values.
+
+A built-in demo lets you explore without market-data credentials. Your research
+stays in a local workspace. Live data access uses Metapyle.
+
+## Guides
+
+- [Human guide](https://github.com/stabilefrisur/kairopsis/blob/main/src/kairopsis/docs/human-guide.md)
+  — everyday investigation, Ideas and exports.
+- [Agent setup guide](https://github.com/stabilefrisur/kairopsis/blob/main/src/kairopsis/docs/agent-setup.md)
+  — installation, data connections, verification and handoff.
+
+Both guides are included in the installed Python package and the source archive.
+Requires Python 3.12 or later. Frontend assets are bundled; no Node.js setup is
+needed.

kairopsis-0.1.0/docs/adr/0001-public-wheel-distribution.md

@@ -0,0 +1,10 @@
+# Distribute a complete application as a Python wheel
+
+Installations may use restricted package indexes and lack Node.js or frontend
+build tools. Ship the application and prepared browser assets together in a
+Python wheel, with the human and agent guides available as package resources.
+
+Configuration, credentials and user research belong outside the installed
+package. Runtime dependencies are supplied by the approved package index or a
+prepared wheelhouse. The source archive includes the material needed to build
+and verify a release without cloning its GitHub repository.

kairopsis-0.1.0/docs/adr/0002-local-user-deployment.md

@@ -0,0 +1,8 @@
+# Support one local user before shared network deployment
+
+The initial deployment runs under one user's account and serves localhost.
+This keeps research and provider access tied to that user's environment.
+
+Network binding remains configurable. Shared deployment requires explicit
+decisions about authentication, credential use, reachability and availability,
+because those requirements change the deployment model.

kairopsis-0.1.0/docs/adr/0003-metapyle-data-access.md

@@ -0,0 +1,10 @@
+# Use Metapyle as the sole data-access API
+
+Kairopsis accesses market data through Metapyle. Keeping provider integrations
+behind that boundary lets the dashboard focus on investigation and retained
+evidence rather than provider-specific connection logic.
+
+An installation may select a compatible Metapyle distribution through its
+approved package route. Provider configuration, authentication and private
+implementation changes remain outside the public Kairopsis package. Adapter
+capabilities and observation semantics must be verified in the target environment.

kairopsis-0.1.0/docs/adr/0004-portable-idea-evidence.md

@@ -0,0 +1,11 @@
+# Preserve idea evidence in portable folders
+
+Each Idea has an application-managed folder containing readable notes, chart
+images, underlying observations and saved analytical settings. Preserve dated
+Snapshots alongside refreshing charts so an investment argument can be reviewed
+independently of later data or analytical changes.
+
+This uses more storage than retaining live chart definitions alone, but keeps
+evidence that may be impossible to reconstruct. Versioned Ideas use atomic
+commit pointers; Snapshots retain JSON, PNG and CSV records. Formats, backup
+and recovery are documented in the [runtime guide](../runtime.md).

kairopsis-0.1.0/docs/agents/domain.md

@@ -0,0 +1,27 @@
+# Domain docs
+
+## Layout and reading rules
+
+This repo uses a single-context layout:
+
+- `CONTEXT.md` at the repo root holds domain terminology.
+- `docs/adr/` holds architectural decision records.
+
+Before exploring the codebase, read `CONTEXT.md` and the ADRs
+relevant to the area being explored.
+
+If these files do not exist, proceed silently. The domain-modeling
+skill creates them when terms or decisions are resolved.
+
+## Vocabulary
+
+Use the terms defined in `CONTEXT.md` when naming domain concepts
+in issues, proposals, hypotheses, and tests.
+
+If a needed concept is absent, reconsider whether it belongs in
+the domain or note the gap for domain-modeling.
+
+## Decision conflicts
+
+If a proposal contradicts an existing ADR, name that ADR and
+explain why the decision should be reconsidered.

kairopsis-0.1.0/docs/agents/issue-tracker.md

@@ -0,0 +1,40 @@
+# Issue tracker: Local Markdown
+
+Issues and specs live as Markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`.
+- Specs live at `.scratch/<feature-slug>/spec.md`.
+- Each implementation ticket has its own file:
+  `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`.
+- Record triage state as a `Status:` line near the top of each issue.
+  Use the role strings in `triage-labels.md`.
+- Append comments and conversation history under `## Comments`.
+
+## Publishing and fetching
+
+When a skill says "publish to the issue tracker", create the
+appropriate file under `.scratch/<feature-slug>/`, creating
+directories as needed.
+
+When a skill says "fetch the relevant ticket", read the referenced
+file. Resolve issue numbers within the relevant feature directory.
+
+## Wayfinding operations
+
+- Map: `.scratch/<effort>/map.md`, with Notes, Decisions-so-far,
+  and Fog sections.
+- Child ticket: `.scratch/<effort>/issues/NN-<slug>.md`, numbered
+  from `01`, with the question in the body.
+- Type: record `research`, `prototype`, `grilling`, or `task`
+  in a `Type:` line.
+- Status: use `open`, `claimed`, or `resolved` for wayfinding tickets.
+- Blocking: record dependencies as `Blocked by: NN, NN`.
+  A ticket is unblocked when all listed tickets are resolved.
+- Frontier: select the lowest-numbered open, unblocked,
+  unclaimed ticket.
+- Claim: save `Status: claimed` before starting work.
+- Resolve: append the answer under `## Answer`, set
+  `Status: resolved`, and add a gist and link to the map's
+  Decisions-so-far section.

kairopsis-0.1.0/docs/agents/triage-labels.md

@@ -0,0 +1,14 @@
+# Triage labels
+
+Use these strings in issue files' `Status:` lines when triaging.
+
+| Role | Status string | Meaning |
+| --- | --- | --- |
+| needs-triage | needs-triage | Maintainer evaluation needed |
+| needs-info | needs-info | Waiting for more information |
+| ready-for-agent | ready-for-agent | Fully specified; ready for an autonomous agent |
+| ready-for-human | ready-for-human | Requires human implementation |
+| wontfix | wontfix | Will not be actioned |
+
+When a skill mentions a triage role, use its mapped status string.
+Wayfinding ticket lifecycle states are defined in `issue-tracker.md`.

kairopsis-0.1.0/docs/risk-adjustment.md

@@ -0,0 +1,45 @@
+# Risk adjustment
+
+Investigation uses the Risk adjustment side panel. Changes there are exploratory; **Edit defaults in Library → Use exploratory settings → Save defaults** explicitly adopts them for that Analysis. Opening and monitoring use saved defaults. Idea Snapshots preserve the resolved references, settings, raw observations, transformed inputs and historical scales. Latest uses the captured definition even after catalogue edits/deletion.
+
+## Controls and evidence
+
+Reference series can be each input itself, a common named series or an external catalogue series. Customize per series exposes independent references/methods/calibration. Each estimator has a lookback; volatility adds equal/exponential weights and half-life, while VaR/CVaR add confidence and downside direction. Frequency belongs to the Analysis and is daily, weekly or monthly. Self-beta is allowed, so both inputs can be adjusted to the first input.
+
+Legend click toggles a trace; double-click isolates it. Axes stay fixed and hidden labels remain dimmed. Visibility changes presentation only. Save to Idea and image exports preserve the selected visibility and scales; older Snapshots remain readable. Shared source metadata and adjustment summaries appear once in the footnote, with full calibration and estimates under Source and chart details.
+
+## Calculation contract
+
+Adjustment applies to each measured input before the Standalone or Pair calculation. The Measured / adjusted series chart compares the individual inputs; Analysis shows the selected difference, ratio or regression residual. Underlying series shows original levels. Display range never changes estimation.
+
+Frequency uses the existing calendar convention: daily = previous weekday; weekly = seven calendar days; monthly = previous calendar month with day clamped. Weekly/monthly baselines are backward-only within three calendar days. Both endpoints require actual observations on their row dates; no fill. Weekly/monthly moves are overlapping observations sampled at daily endpoints. No square-root-of-time conversion or annualization is applied.
+
+Change is `current − baseline`, in supplied units. Percentage change is `100 × (current / baseline − 1)` and requires a positive baseline. This is a percentage change in the supplied measure, not a total investment return inferred from spread levels. To examine supplied cumulative return series, choose their configured Data Series.
+
+For each date, the risk sample ends at the measured interval's start and begins the selected number of calendar years earlier. The current measured interval is excluded. At least 60 valid prior moves are required by default. Estimation history older than seven calendar days at that cutoff is unavailable. Beta uses paired moves with identical start/end dates. Source freshness qualifications still apply to findings.
+
+| Method | Divisor / convention |
+| --- | --- |
+| None | 1; preserves measured changes. Existing Analyses retain unadjusted levels by default. |
+| Volatility | Demeaned sample standard deviation. Equal weights use `N−1`. Exponential weights use `w = 2^(−age/half-life)`, with age/half-life in weekday sessions; normalized weighted variance uses denominator `Σw − Σw²/Σw`. |
+| Beta to reference | Intercept OLS slope `Σ(x−x̄)(y−ȳ) / Σ(x−x̄)²`; y is the target and x the reference. Self-beta equals 1 when reference moves vary. Signed negative beta is retained; absolute beta below `1e−12` is unavailable. |
+| Value at Risk | Historical loss quantile: sorted loss at `ceil(confidence × N)`. Confidence is converted from percent. Increasing or decreasing values explicitly defines downside. |
+| Expected Shortfall (CVaR) | Mean of the worst `(1−confidence) × N` losses, including proportional weight for a fractional boundary observation. Uses the same downside direction as VaR. |
+
+The input is divided by its estimated scale without subtracting a drift or intercept. Volatility/VaR/ES yield dimensionless **risk units** and require matching target/reference units, or percentage changes. Beta yields the reference's units. Pair differences require identical resulting units; ratios preserve the units of the quotient. Zero variance, missing estimates, near-zero beta and nonpositive downside scales produce unavailable values. Per-series customization can therefore produce incompatible differences; the UI retains the last accepted evaluation and explains the incompatibility.
+
+VaR/ES describe downside moves of the selected Data Series, not portfolio P&L or capital requirements. High confidence with few observations has little tail evidence; disclosed sample counts and periods are essential. These historical estimates are comparisons, not calibrated trading or investment recommendations.
+
+## Defaults, thresholds and continuity
+
+None preserves existing level behavior and older stored evidence remains readable. Selecting an adjustment from a level Analysis switches Measure to Change. Changing risk configuration or Measure clears exploratory move/materiality thresholds, preventing old measurement-unit rules from being reused silently. Library exposes explicit thresholds in the resulting Analysis units; production threshold calibration remains separate.
+
+References are resolved and fetched through Metapyle alongside the inputs. Reference edits advance dependent Analysis revisions; deletion is prevented while an active Analysis uses that reference. Captured definitions retain the binding needed for Latest evaluation independently of active catalogue entries. Snapshots contain raw reference data in JSON; CSV/clipboard exports additionally include measured inputs, scales and period starts.
+
+## Sources and scope
+
+Definitions follow [BIS market-risk terminology](https://www.bis.org/committees/bcbs/basel-framework/standard/mar?allChapters=true&q=PPP0QQQ&sort=PPP1QQQ&year=PPP2QQQ) for VaR/ES, [NIST least squares](https://www.itl.nist.gov/div898/handbook/pmd/section4/pmd431.htm) for intercept regression, and [NIST exponential smoothing](https://www.itl.nist.gov/div898/handbook/pmc/section4/pmc43.htm) for decaying weights. The finite-sample correction, empirical quantile, fractional-tail and calendar conventions above are explicit implementation choices; no regulatory methodology is claimed.
+
+Mock tests establish numerical and persistence behavior. Provider calendars, actual source semantics, estimator suitability and risk-adjusted monitoring thresholds require validation in the target environment.
+
+The [verification guide](verification.md) describes source and installed-package checks. A source test result does not establish acceptance for a different operating system or data provider.

kairopsis-0.1.0/docs/runtime.md

@@ -0,0 +1,72 @@
+# Run and preserve research
+
+Python 3.12+, FastAPI/Uvicorn, Jinja2 and plain JavaScript. All browser assets are packaged locally. Install the wheel and dependencies before launch; startup never resolves dependencies. Three destinations: Analyses, Ideas, Library.
+
+```powershell
+kairopsis --mode mock --host 127.0.0.1 --port 8765 --workspace C:\Users\Me\Kairopsis\rebuild-mock
+```
+
+Use the environment's absolute `Scripts\kairopsis.exe` in Windows Task Scheduler. Working directory does not matter. Paths (`--workspace`, `--config-dir`, `--cache-dir`, `--log-dir`) must be absolute, writable and outside the installed package. `--timezone Europe/London` sets daily refresh boundaries. CLI overrides `KAIROPSIS_<KEY>` environment variables, optional `--config C:\absolute\kairopsis.toml` (`[kairopsis]` keys with underscores), then platform defaults.
+
+Mock fixtures are deterministic, explicitly fabricated native-market observations through **30 September 2026**. No credentials/provider connection. New Library bindings require a matching fixture; unavailable bindings produce explicit failures. Monitoring is independent of saving to an Idea. First daily opening starts refresh in the background; manual Refresh completes a dated attempt. Failed analyses retain their prior result and lose fresh finding eligibility.
+
+## Evidence and recovery
+
+The rebuild uses workspace schema 2. Older/unmarked nonempty workspaces are refused without modification. Choose a new empty directory; no migration or deletion is performed. Retain older user directories independently.
+
+`workspace/ideas/<id>/current.json` selects a committed version under `versions/<version>/idea.json` and `notes.md`. `snapshots/<id>/` contains `snapshot.json`, `image.png` and `data.csv`. Snapshot JSON embeds resolved inputs/risk references, analytical settings, raw/aligned observations, measured inputs/scales/interval starts and retrieval/capture times. Display settings include hidden trace indices and axis ranges; the PNG has a verified content hash. Catalogue and dated evaluation/refresh records live outside the package. No database index is the only copy of evidence.
+
+Files for a version are written before its atomic commit pointer. Interrupted saves leave the previous version readable; unpublished directories are ignored. Snapshot metadata is committed last. Disk/read errors stop capture/export with an actionable message. Removing a chart/note preserves prior versions and Snapshots internally. No History destination is required.
+
+Saved charts render their frozen observations and settings with the current presentation; Saved/Latest share chart geometry. Original PNGs remain unchanged and can be downloaded under Source and chart details. A chart note sits directly below its plot, with Edit/Delete beside it and source disclosure last.
+
+Legend click shows/hides a series; double-click isolates it. Hidden labels stay dimmed and axes remain fixed while toggling. Image exports and Save to Idea capture `hidden_traces` and `axis_ranges` in DisplaySettings. Older records default to all traces visible and automatic initial scales. Latest keeps the captured selection and recalculates scales from all current traces; changing chart view resets selection. Underlying values and analytical metrics remain unchanged by visibility.
+
+Idea chart actions are Copy data, Copy chart, Download chart, Remove chart. Image actions use the selected view. Copy data uses its full displayed period and supplies spreadsheet-ready TSV with calculated/input values, units, ISO chart/source dates, measured/adjusted inputs, risk scales and interval starts, full numeric precision and blank missing cells. Legend visibility does not remove input columns. Clipboard denial downloads the corresponding PNG or TSV. Copy/export first captures another Snapshot; a capture failure stops completion and preserves the clipboard. Original saved evidence is never overwritten.
+
+Footnotes deduplicate shared source, currency/reference curve and observation dates, with a compact method/reference/Frequency summary for adjusted views. Demo status and applicable fit period remain explicit. Full per-series bindings, calibration, retrieval and quality details stay folded and in portable records. Date axes have no title; numeric scatter axes retain series/unit titles. Idea detail omits the saved-chart count. Owned UI asset URLs include content hashes, so refresh loads changed scripts/styles.
+
+Stop the application before copying the entire workspace for backup. Restore to a separate empty directory and point `--workspace` there. An Idea folder can also be copied under another compatible workspace's `ideas/`; its current pointer and embedded evidence suffice to reopen it. Never copy only images or an index. Preserve corrupt content for recovery; restore a known-good backup rather than resetting a directory.
+
+## Live data and verification
+
+Start `--mode live` in a separate workspace. Library **Add data series** creates a Metapyle catalogue entry; Edit/Delete update it. No separate translation configuration is needed for new entries.
+
+The form uses actual provider identifiers:
+
+| Source | Required query fields |
+| --- | --- |
+| Bloomberg | Symbol/ticker and field |
+| Macrobond | Series symbol; no field or path |
+| Local file | Case-sensitive column name and absolute CSV/Parquet path; no field |
+| Other registered source | Registered adapter name and its supported symbol/field/path/parameters |
+
+Name is the display label. Catalogue name (`my_name`) defaults to the name with underscores and can be edited under additional details. Units are required. Currency describes the data; Description is optional. Reference curve, comparison currency and adjustment/rebasing have been removed from the form. New series do not generate a comparison-basis record; existing metadata remains readable in earlier definitions and saved evidence. Provider credentials remain in the provider's runtime configuration, outside catalogue query parameters.
+
+`workspace/metapyle.yaml` is a real YAML catalogue readable by Metapyle. Library owns this file: edit entries through Library. `catalogue.json` commits series metadata and analysis dependencies together; YAML is a validated projection rebuilt at startup. A failed metadata commit restores the preceding YAML. Both files belong in workspace backups. Concurrent external edits/import of independent catalogues are not supported in this version.
+
+Metapyle validates source-specific attributes and registered sources before publication. Structural validation does not prove that a symbol exists or that it represents the intended asset. Library save does not fetch observations. Source failures and missing expected columns remain explicit.
+
+Retrieval uses `Client(catalog=..., cache_enabled=False)` → `get([my_name], ..., use_cache=False)` → `close()`. A new client loads each request's catalogue. Active definitions use the managed YAML; frozen definitions use a temporary catalogue containing their captured entries when current entries differ or have been removed. No frequency alignment is requested from Metapyle; analytical Frequency remains in Kairopsis.
+
+Public adapter responses remain freshness **unverified** and native observation dates unknown. They support inspectable charts and saved evidence but cannot establish eligible findings. Observation cache bypass remains deliberate; catalogue files are definitions, not an observation cache. Installed adapter capabilities, upstream freshness, calendars and dependency routing require verification in the target environment.
+
+Existing demo fixtures and old snapshots without `catalog_name` keep their previous binding contract. Old live bindings alone may use private `config-dir/metapyle.json` mappings and `get_raw()` for compatibility, including explicitly configured observation-date columns. Edit an old live series, select its real provider and supply its actual symbol/field/path to move future evaluations to the catalogue API. Prior snapshots keep their captured definitions. No automatic translation or guessed migration is performed.
+
+Public Metapyle 0.1.6 has no add/update/remove API or CLI. Kairopsis uses `Catalog` export/load and public `Client` validation behind one module. A generic upstream request tracks those additions: [Metapyle issue #3](https://github.com/stabilefrisur/metapyle/issues/3).
+
+## Analytical conventions
+
+| Item | Applied rule |
+| --- | --- |
+| Standing | Current-excluded eligible history; `100 × (below + 0.5 × equal) / N`; default reference 3 calendar years; at least 60 prior points. Shorter available history is qualified by sample count. |
+| Alignment | Exact supplied row dates, no fill/interpolation. Findings require finite inputs and known native dates equal to the row; weekdays only. Union rows remain inspectable with missing arithmetic. Provider holiday calendars are not verified. |
+| Day move | Exact previous weekday session; never skip a missing baseline. |
+| Week/month move | Seven calendar days / previous calendar month (day clamped); backward-only baseline within three calendar days. Missing baseline yields unavailable, never zero. |
+| Pair | Ordered first minus second, first divided by second (zero denominator unavailable), or first dependent on second explanatory. Difference requires same units; different bases remain explicitly labelled. |
+| OLS | Intercept fit over selected full trailing calendar window excluding current. At least 20 eligible pairs; seven-day endpoint tolerance; constant x unavailable. Residual history uses current fit retrospectively. Fit and display/reference windows are independent. |
+| Sensitivity | Compare 1y/5y fits where full history permits; indicate a residual direction reversal. Unavailable checks are explicit; no invented stability score. |
+| Finding | Configured symmetric level tails and optional native-unit move thresholds. `demo-native-v1` explicitly illustrative. Compatible new native observations establish threshold entry or material movement; same evidence stays quiet. Corrections/definition/method changes suppress market novelty. Regression material movement holds the earlier fit fixed. |
+| Ordering | New, materially changed, first-observed condition; then case-folded name and stable ID. One row per analysis, no composite score/quota. |
+
+Risk adjustment is available in the Investigation side panel and as saved Analysis defaults in Library. Supported methods: volatility, beta, historical VaR and Expected Shortfall (CVaR), with common or per-input references/settings. [Calculation conventions](risk-adjustment.md) specify Frequency, prior-only estimation, half-life, downside, units and unavailable cases. Snapshots preserve raw/reference data and adjustment choices; Latest uses the captured definition. Estimator suitability and risk-adjusted monitoring thresholds require target-environment validation.

kairopsis-0.1.0/docs/verification.md

@@ -0,0 +1,52 @@
+# Verify a distribution
+
+Verify the built artifacts as well as the source checkout. Source tests establish
+application behavior; installed-package checks establish that the distribution
+contains the code, browser assets and guides needed outside the checkout.
+
+## Source and packaging checks
+
+```sh
+uv sync --locked
+uv run pytest -q
+uv run mypy src/kairopsis
+uv build
+uv run python scripts/acceptance/inspect_wheel.py dist/kairopsis-0.1.0-py3-none-any.whl --require-assets --source-directory . --output /absolute/output/wheel-inventory.json
+uvx --from twine twine check --strict dist/*
+```
+
+The inventory requires both installed guides, checks source completeness and
+vendor checksums, and rejects accidental private runtime material. Source archives
+include docs, tests, scripts, the lockfile and domain context. Keep scratch records
+and credentials outside published artifacts.
+
+## Installed application
+
+Install the wheel into a separate environment with approved dependencies. Launch
+from outside the checkout using fresh writable directories. Verify all three
+navigation destinations, local assets, an Analysis, saved Idea evidence, notes,
+exports and restart persistence. Locate the two installed guides through
+`importlib.resources` as described in the [agent setup guide](../src/kairopsis/docs/agent-setup.md).
+
+For an automated journey against an isolated running demo instance:
+
+```sh
+uv run python scripts/browser_acceptance.py --url http://127.0.0.1:8765 --output /absolute/output/browser
+```
+
+The script creates verification records. Supply a separate workspace rather than
+an existing research workspace. Prepare Playwright Chromium before network-limited
+checks. `scripts/acceptance/run_windows.py` also provides an installed Windows
+harness; its output directory must not exist.
+
+## Recorded scope
+
+The current implementation passes 63 source tests. Typechecking, packaged source
+and browser-asset inventory, installed guide discovery and strict Twine checks
+have passed. Tests also run from an extracted source archive without a checkout.
+
+An installed Linux demo has loaded all navigation pages and local assets and
+produced a mock Analysis preview from a separate environment. Full installed
+Windows and live-provider acceptance must be verified for the target release.
+Provider credentials, data semantics, calendars, freshness and monitoring
+threshold suitability are separate from package completeness.

kairopsis-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "kairopsis"
+version = "0.1.0"
+description = "Relative-value idea generation dashboard powered by metapyle"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi==0.135.2",
+    "jinja2==3.1.6",
+    "metapyle>=0.1.6",
+    "pandas==3.0.6",
+    "platformdirs==4.5.1",
+    "pydantic==2.13.5",
+    "tzdata==2026.4",
+    "uvicorn==0.42.0",
+]
+
+[[project.authors]]
+name = "Stabile Frisur"
+email = "26568863+stabilefrisur@users.noreply.github.com"
+
+[project.scripts]
+kairopsis = "kairopsis:main"
+
+[project.urls]
+Repository = "https://github.com/stabilefrisur/kairopsis"
+Documentation = "https://github.com/stabilefrisur/kairopsis/blob/main/src/kairopsis/docs/human-guide.md"
+Issues = "https://github.com/stabilefrisur/kairopsis/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx==0.28.1",
+    "mypy==1.18.2",
+    "playwright==1.55.0",
+    "pytest==8.4.2",
+]
+
+[tool.uv.build-backend]
+source-include = [
+    "docs/**",
+    "tests/**",
+    "scripts/**",
+    "uv.lock",
+    "CONTEXT.md",
+    "AGENTS.md",
+    ".python-version",
+]

kairopsis-0.1.0/pyproject.toml.orig

@@ -0,0 +1,42 @@
+[project]
+name = "kairopsis"
+version = "0.1.0"
+description = "Relative-value idea generation dashboard powered by metapyle"
+readme = "README.md"
+authors = [
+    { name = "Stabile Frisur", email = "26568863+stabilefrisur@users.noreply.github.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi==0.135.2",
+    "jinja2==3.1.6",
+    "metapyle>=0.1.6",
+    "pandas==3.0.6",
+    "platformdirs==4.5.1",
+    "pydantic==2.13.5",
+    "tzdata==2026.4",
+    "uvicorn==0.42.0",
+]
+
+[project.scripts]
+kairopsis = "kairopsis:main"
+
+[project.urls]
+Repository = "https://github.com/stabilefrisur/kairopsis"
+Documentation = "https://github.com/stabilefrisur/kairopsis/blob/main/src/kairopsis/docs/human-guide.md"
+Issues = "https://github.com/stabilefrisur/kairopsis/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx==0.28.1",
+    "mypy==1.18.2",
+    "playwright==1.55.0",
+    "pytest==8.4.2",
+]
+
+[tool.uv.build-backend]
+source-include = ["docs/**", "tests/**", "scripts/**", "uv.lock", "CONTEXT.md", "AGENTS.md", ".python-version"]