diff --git a/README.md b/README.md index c5552f8..c5228ec 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,9 @@ mint dev --no-open --port 3333 The live site deploys from this repository. -Keep the site concise. Generated reference, SDK, Webhook and MCP pages follow reviewed versioned contracts. +Keep the site concise. Generated reference, SDK, Webhook and MCP pages follow reviewed versioned definitions and compatibility policies. -`openapi/heyrafiki.openapi.yaml` is the published API contract. Narrative pages explain it and never redefine it. +`openapi/heyrafiki.openapi.yaml` is the published API definition. Narrative pages explain it and never redefine it. ## License diff --git a/changelog.mdx b/changelog.mdx index 2b0289d..59da072 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -7,14 +7,23 @@ rss: true Released API changes appear here. Product and website changes are on the [Heyrafiki changelog](https://heyrafiki.space/changelog). + +**Published** the JavaScript, Python, Go and Rust SDK public betas through their +standard registries, joining the existing .NET beta. See [SDKs](/sdks) for +version-pinned install commands and source repositories. + +**Added** the [Affective Dynamics guide](/research/affective-dynamics) and the +public [Heyrafiki Lab](https://heyrafiki.space/resources/lab). + + -**Documented** the complete [API overview](/resources) as eight resource areas and 31 released operations. The generated endpoint reference and public contract remain the operation-level authorities. +**Documented** the complete [API overview](/resources) as eight resource areas and 31 released operations. The generated endpoint reference and public API definition remain the operation-level authorities. -**Added** a [research and evidence guide](/research/evidence) connecting public statements to the OpenAPI contract, Assurance Graph, synthetic fixtures, deterministic runners and stated limitations. +**Added** a [research and evidence guide](/research/evidence) connecting public statements to the OpenAPI definition, Assurance Graph, synthetic fixtures, deterministic runners and stated limitations. -**Added** the Stage 1 Assurance Graph protocol manuscript, prior-art search record and independent reviewer packet. The candidate is evaluated against five progressively stronger baselines before results are published. +**Added** the Assurance Graph comparative protocol, manuscript, prior-art search record and independent reviewer packet. **Documented** First Light v2 as reproducible synthetic conformance evidence. It does not establish clinical validity or population effectiveness. diff --git a/concepts/capabilities.mdx b/concepts/capabilities.mdx index bc7551d..d592818 100644 --- a/concepts/capabilities.mdx +++ b/concepts/capabilities.mdx @@ -1,14 +1,14 @@ --- title: "Platform capabilities" -description: "The resource families and contracts that make up the Heyrafiki Platform." +description: "The resource families and interfaces that make up the Heyrafiki Platform." keywords: ["platform capabilities", "typed capabilities", "healthcare API architecture"] --- -The public contract grows by capability. Generated endpoint pages remain the authority for callable operations. +The public API grows by capability. Generated endpoint pages remain the authority for callable operations. ## Sandbox resources -| Capability | Contract | +| Capability | Interface | | --- | --- | | API discovery | Environment and available resource families | | Practitioner discovery | List and retrieve synthetic Practitioner profiles | @@ -19,11 +19,12 @@ The public contract grows by capability. Generated endpoint pages remain the aut ## Developer surfaces -| Capability | Contract | +| Capability | Interface | | --- | --- | | JavaScript SDK | Typed client and shared conformance fixtures | | Webhooks | Versioned events, signing, replay protection and bounded retries | | MCP | Thirteen read-only, scope-checked sandbox tools | +| Public Lab | Browser-based tools using example data and published research boundaries | ## Resource families @@ -35,4 +36,4 @@ The public contract grows by capability. Generated endpoint pages remain the aut - Organizations, Insurers and network operations - Standards-based healthcare and reporting adapters -Endpoint, event, package and tool behavior is governed by its versioned contract. +Endpoint, event, package and tool behavior follows its versioned definition and compatibility policy. diff --git a/docs.json b/docs.json index 59e0ba5..f785bd3 100644 --- a/docs.json +++ b/docs.json @@ -146,7 +146,7 @@ }, { "group": "Research and evidence", - "pages": ["research/evidence"] + "pages": ["research/evidence", "research/affective-dynamics"] } ] }, diff --git a/index.mdx b/index.mdx index 63a4a9f..fb2a622 100644 --- a/index.mdx +++ b/index.mdx @@ -5,7 +5,7 @@ description: "Build Care, Cover and Claims workflows through the Heyrafiki API." keywords: ["Mental Healthcare API", "health insurance API", "Heyrafiki API"] --- -The Heyrafiki API connects Practitioner discovery, Bookings, Benefits, Sessions, Claims, remittance and Webhooks through versioned REST contracts. +The Heyrafiki API connects Practitioner discovery, Bookings, Benefits, Sessions, Claims, remittance and Webhooks through one versioned REST interface. Use the Sandbox to build complete integrations. @@ -40,7 +40,7 @@ https://api.heyrafiki.space/v1 -## Start with the contract +## Start with the API diff --git a/research/affective-dynamics.mdx b/research/affective-dynamics.mdx new file mode 100644 index 0000000..8ce369b --- /dev/null +++ b/research/affective-dynamics.mdx @@ -0,0 +1,107 @@ +--- +title: "Affective Dynamics" +description: "Understand Heyrafiki's consent-governed approach to longitudinal affective context, example data and Practitioner review." +keywords: ["Affective Dynamics", "longitudinal mental health data", "experience sampling", "Practitioner review"] +--- + +Affective Dynamics describes how repeated affective observations change over +time. Heyrafiki uses it to organise longitudinal context for a Person and their +Practitioner. It does not make a Diagnosis or decide what a pattern means. + +## Start with the public tools + +- [Use the browser Lab](https://heyrafiki.space/resources/lab#affective-dynamics) + to move example check-ins and see the descriptive summary change. +- [Read the research note](https://heyrafiki.space/resources/articles/affective-dynamics-what-change-can-and-cannot-tell-us) + for the scientific basis and limitations. +- [Run the public protocol](https://github.com/heyrafiki/proving-ground/tree/main/research/affective-dynamics) + for synthetic edge cases, expected boundaries and the reviewer checklist. + +## What the view describes + +| Description | Question it answers | Important limit | +| --- | --- | --- | +| Average | Where are the observations centred in this window? | The Instrument, window and missing observations affect the value. | +| Variation | How spread out are the observations? | Variation does not preserve temporal order. | +| Direction | Does the available sequence move up or down over elapsed time? | A short cluster is not treated as a trajectory. | +| Successive change | How much do adjacent observations differ after accounting for elapsed time? | The summary does not identify a cause. | +| Inertia | How strongly does one observation predict the next? | The value is withheld when intervals are irregular or variance is zero. | +| Return | Does the sequence return toward its declared reference range? | If the return is not observed, the duration remains unresolved. | + +## Evidence carried with each observation + +Each observation keeps the fields needed to decide whether it is comparable +and eligible for the requested purpose: + +- dimension identifier and version; +- value and declared scale; +- observed time and recorded time; +- Consent reference and version; +- source and source version; +- quality state and weight; and +- optional context references that do not contain Session content. + +The original observations, computed description and Practitioner +interpretation remain separate records. + +## When a measure is withheld + +The view returns a clear empty or not-interpretable state when: + +- too few eligible check-ins are available; +- the available period is too short; +- timing is too irregular for lag-one autocorrelation; +- the series has no variance; +- no return is observed inside the available window; +- Consent does not permit the read; or +- the request crosses an Organization boundary. + +No missing observation is silently filled in. + +## Time and reconstruction + +`observed_at` records when an observation applied. `recorded_at` records when +the system learned it. A read at a knowledge cutoff includes only observations +whose `recorded_at` value is at or before that cutoff. This allows a reviewer to +reconstruct what the system could have shown at that time. + +## Access and review + +| Audience | Access boundary | +| --- | --- | +| Person | May read their own consented view. | +| Practitioner | May read a shared Client view inside an active Care relationship and record a separate review. | +| Researcher | May use only an approved protocol, research scope and eligible de-identified data. | +| System | May run committed synthetic fixtures for conformance testing. | + +The public Lab uses example data. The authenticated Platform preview remains +feature-gated, and Affective Dynamics is not currently a public REST resource. +Use the Proving Ground protocol for integration-independent evaluation. + +## Reproduce the public boundary + +```bash +git clone https://github.com/heyrafiki/proving-ground.git +cd proving-ground +npm ci +npm run test:affective-dynamics +``` + +The check validates nine synthetic case families, the declared comparators and +the protocol's failure boundaries. Population, language and Instrument-specific +clinical studies require their own approved protocol. + +## Published sources + +- [Jahng, Wood and Trull (2008)](https://doi.org/10.1037/a0014173) on + variability, temporal dependency and successive differences. +- [Kuppens, Allen and Sheeber (2010)](https://doi.org/10.1177/0956797610372634) + on emotional inertia. +- [Houben, Van Den Noortgate and Kuppens (2015)](https://doi.org/10.1037/a0038822) + on short-term emotion dynamics and well-being. +- [Dejonckheere and colleagues (2019)](https://doi.org/10.1038/s41562-019-0555-0) + on incremental value beyond mean and variance. +- [McNeish and colleagues (2021)](https://doi.org/10.1080/10705511.2021.1915788) + on measurement in intensive longitudinal data. +- [Schneider and colleagues (2023)](https://doi.org/10.3758/s13428-022-01995-1) + on reliability and sampling error in within-person dynamics. diff --git a/research/evidence.mdx b/research/evidence.mdx index a2a4321..da0c77e 100644 --- a/research/evidence.mdx +++ b/research/evidence.mdx @@ -1,15 +1,15 @@ --- title: "Research and evidence" -description: "Follow Heyrafiki statements to public contracts, executable evidence and explicit research limitations." +description: "Follow Heyrafiki statements to public API definitions, executable evidence and explicit research limitations." keywords: ["mental health research evidence", "reproducible conformance", "First Light", "Assurance Graph"] --- -Heyrafiki publishes the evidence that another team can inspect and run. The public path starts with a defined statement and ends with a versioned contract, synthetic fixture, expected result, deterministic runner and visible limitation. +Heyrafiki publishes evidence that another team can inspect and run. The public path starts with a defined statement and ends with a versioned definition, synthetic fixture, expected result, deterministic runner and visible limitation. ```mermaid flowchart LR - Statement["Defined statement"] --> Contract["Versioned contract"] - Contract --> Fixture["Synthetic fixture"] + Statement["Defined statement"] --> Definition["Versioned definition"] + Definition --> Fixture["Synthetic fixture"] Fixture --> Expected["Expected result"] Expected --> Runner["Deterministic runner"] Runner --> Limitation["Stated limitation"] @@ -19,12 +19,12 @@ flowchart LR | Authority | What it owns | Inspect it | | --- | --- | --- | -| Contract | The public REST surface and machine-readable Assurance Graph | [heyrafiki/contract](https://github.com/heyrafiki/contract) | +| API definition | The public REST interface and machine-readable Assurance Graph | [heyrafiki/contract](https://github.com/heyrafiki/contract) | | Proving Ground | Deterministic conformance suites, fixtures and expected results | [heyrafiki/proving-ground](https://github.com/heyrafiki/proving-ground) | | Docs | Integration guidance and the meaning of released public behavior | [heyrafiki/docs](https://github.com/heyrafiki/docs) | -| SDK repositories | Language-specific source maintained against the public contract | [SDK guide](/sdks) | +| SDK repositories | Language-specific source maintained against the public API definition | [SDK guide](/sdks) | -The Platform implementation remains the authority for runtime behavior. Public repositories make contracts and selected evidence independently inspectable without becoming a second runtime authority. +The Platform implementation remains the authority for runtime behavior. Public repositories make API definitions and selected evidence independently inspectable without becoming a second runtime authority. ## First Light v2 @@ -56,7 +56,7 @@ npm test ## What the current evidence supports -The public suites support claims about contract coverage, deterministic scoring, bitemporal replay, Consent-aware access boundaries, audit completeness and rejection of declared adversarial mutations. +The public suites support claims about API coverage, deterministic scoring, bitemporal replay, Consent-aware access boundaries, audit completeness and rejection of declared adversarial mutations. Separate clinical and population studies are required for: @@ -64,7 +64,7 @@ Separate clinical and population studies are required for: - effectiveness for a Kenyan or other real population; - actuarial savings or health outcomes; - safety under every production condition; -- scientific priority or patentability. +- claims beyond the declared protocol and evidence. Those conclusions require a separate protocol, appropriate approvals, licensed instruments, representative data, baseline methods, uncertainty estimates and expert review. @@ -72,18 +72,18 @@ Those conclusions require a separate protocol, appropriate approvals, licensed i A research candidate is ready for formal evaluation only when its problem, assumptions, prior art, baseline, protocol, measures, data rights, failure implications and review owner are written down before outcome claims are made. -The [Assurance Graph](/institutions/assurance-graph) provides the traceability layer. It connects public operations and controls to executable evidence. Scientific priority is evaluated separately through the comparative protocol and independent review. +The [Assurance Graph](/institutions/assurance-graph) provides the traceability layer. It connects public operations and controls to executable evidence. Comparative research follows its declared protocol and independent review. -### Candidate under comparative review +### Comparative evaluation -The current candidate tests a two-cutoff, Consent-conditional assurance-path query with fail-closed completeness. The protocol is in Stage 1 independent review. Results follow protocol freeze, comparative evaluation and independent reproduction. +The public protocol tests a two-cutoff, Consent-conditional assurance-path query with fail-closed completeness. It declares the comparators, measures, stopping rules and independent review path before evaluation. Review the formal query, five baselines, fixed measures and stopping rules. - - Inspect the article structure before any result is collected. + + Inspect the article structure and declared evidence boundary. See the closest standards, papers and patent families found by the author search. @@ -95,4 +95,4 @@ The current candidate tests a two-cutoff, Consent-conditional assurance-path que ## Reporting a mismatch -If a public statement, contract, fixture or result disagrees with another authority, open an issue in the repository that owns the mismatched artifact. Security and privacy findings should follow the private process in the [Security overview](/security/overview). +If a public statement, API definition, fixture or result disagrees with another authority, open an issue in the repository that owns the mismatched artifact. Security and privacy findings should follow the private process in the [Security overview](/security/overview). diff --git a/sdks.mdx b/sdks.mdx index b3dd0d1..bcf3891 100644 --- a/sdks.mdx +++ b/sdks.mdx @@ -4,13 +4,13 @@ description: "Typed JavaScript, Python, Go, .NET and Rust clients for the Heyraf keywords: ["Heyrafiki SDK", "healthcare API clients", "insurance API", "Heyrafiki CLI"] --- -Every SDK follows the same OpenAPI contract, authentication rules, idempotency +Every SDK follows the same OpenAPI definition, authentication rules, idempotency requirements, error envelope and request identifiers. - Install the current SDKs and CLI from the reviewed source repositories using - the build commands below. Registry releases will be linked here after each - clean consumer installation passes. + JavaScript, Python, Go, .NET and Rust public betas are available from their + standard package registries. The source repositories remain available for + review and reproducible builds. ## Choose a client @@ -23,7 +23,7 @@ requirements, error envelope and request identifiers. | [`rafiki-net`](https://github.com/heyrafiki/rafiki-net) | .NET Standard 2.0, .NET 8 and .NET 10 | Insurer, health-system and government integrations | | [`rafiki-rs`](https://github.com/heyrafiki/rafiki-rs) | Rust 1.85+ | Correctness-sensitive and high-throughput services | | [`hey`](https://github.com/heyrafiki/hey) | Node.js 22+ | Local diagnostics, CI and governed API reads | -| [`contract`](https://github.com/heyrafiki/contract) | OpenAPI 3.1 | Code generation and contract validation | +| [`contract`](https://github.com/heyrafiki/contract) | OpenAPI 3.1 | Code generation and API compatibility checks | Each client is available from its public repository for Sandbox integration. The repository owns its source-install path, compatibility policy, release @@ -82,14 +82,53 @@ cargo test --all-features -## Install the .NET SDK +## Install a published beta -The [`heyrafiki` NuGet package](https://www.nuget.org/packages/heyrafiki/0.1.0-beta.1) is available as `0.1.0-beta.1`. + + + +```bash +npm install @heyrafiki/rafiki-js@0.1.0-beta.1 +``` + + + + +```bash +python -m pip install --pre heyrafiki==0.1.0b1 +``` + + + + +```bash +go get github.com/heyrafiki/rafiki-go@v0.1.0-beta.1 +``` + + + ```bash dotnet add package heyrafiki --version 0.1.0-beta.1 ``` + + + +```bash +cargo add heyrafiki@0.1.0-beta.1 +``` + + + + +The published packages are available on +[npm](https://www.npmjs.com/package/@heyrafiki/rafiki-js), +[PyPI](https://pypi.org/project/heyrafiki/0.1.0b1/), +[pkg.go.dev](https://pkg.go.dev/github.com/heyrafiki/rafiki-go), +[NuGet](https://www.nuget.org/packages/heyrafiki/0.1.0-beta.1) and +[crates.io](https://crates.io/crates/heyrafiki/0.1.0-beta.1). + ## Make the first request @@ -152,7 +191,7 @@ stores and retain the request identifier when tracing a failed call. ## Write safely -All clients preserve the REST contract's write controls: +All clients preserve the REST API's write controls: - caller-owned idempotency keys for replay-safe writes; - bounded retries only where the operation and key make retry safe; @@ -176,13 +215,13 @@ npm run check node dist/index.js doctor ``` -## Verify the contract +## Verify API compatibility - + Inspect the versioned OpenAPI schemas, scopes, errors and Assurance Graph. - Run contract, financial-identity, bitemporal and adversarial conformance suites. + Run API, financial-identity, bitemporal and adversarial conformance suites. diff --git a/testing.mdx b/testing.mdx index ce2aaeb..43c8e69 100644 --- a/testing.mdx +++ b/testing.mdx @@ -4,7 +4,7 @@ description: "Build integrations against deterministic sandbox data." keywords: ["API testing", "Sandbox fixtures", "integration conformance"] --- -Use sandbox keys for development, CI and acceptance tests. Sandbox responses contain synthetic data and use the same identifiers, scopes, errors and rate-limit headers as the API contract. +Use sandbox keys for development, CI and acceptance tests. Sandbox responses contain synthetic data and use the same identifiers, scopes, errors and rate-limit headers as the API definition. ## Test safely @@ -14,8 +14,14 @@ Use sandbox keys for development, CI and acceptance tests. Sandbox responses con - Exercise `400`, `401`, `403`, `404`, `429` and `503` handling. - Retry only when the response permits it. -## Contract changes +## API compatibility Additive fields may appear without a new API version. Ignore fields your integration does not use and keep a default branch for enum values. -The [Changelog](/changelog) records contract changes. The [Versioning guide](/versioning) defines compatibility. +The [Changelog](/changelog) records API changes. The [Versioning guide](/versioning) defines compatibility. + +## Public research tools + +Use the [Heyrafiki Lab](https://heyrafiki.space/resources/lab) for browser-based +examples. The [Affective Dynamics guide](/research/affective-dynamics) connects +the interactive example to its public protocol and synthetic failure cases.