openkind_core/lib.rs
1//! `openkind-core`: Zero-dependency, Jev-compatible wire protocol types and validation.
2//!
3//! # Overview
4//! `openkind-core` is the foundational crate in the `openkind` workspace. It acts as the
5//! canonical, single source of truth for the wire schema spoken by both HTTP/REST
6//! (`/v1/systemone` and `/v1/system_one`) and gRPC (`openkind.SystemOne/Evaluate`) transports.
7//!
8//! Pinned to the TypeSafe Jev API contract documented at <https://docs.typesafe.ai/api> and
9//! the Python SDK specification at <https://docs.typesafe.ai/sdk/python/api>.
10//!
11//! # Architectural Invariants
12//! - **Strict Dependency Layering**: `openkind-core` depends on no other workspace crates (`openkind-engine`,
13//! `openkind-api`, etc.). All higher layers depend on `openkind-core`.
14//! - **64-bit IEEE 754 Precision**: All floating-point fields (`probabilities`, `score`, `noul`, `confidence`)
15//! use `f64` to prevent wire representation regressions (such as `0.92f32` round-tripping to `0.9200000166893005`).
16//! - **Zero Confidence on Noul**: Per the Jev specification, boolean probability (`Noul`) answers contain only
17//! `noul` and never include a `confidence` field.
18//! - **Polymorphic State & Instructions**: `state` and question `instructions` allow plain text strings, JSON
19//! objects, or JSON arrays.
20//!
21//! See `docs/ARCHITECTURE.md` and `crates/openkind-core/schemas/` for generated JSON Schema definitions.
22
23#![warn(missing_docs)]
24
25/// Wire answer types for Noul, Choice, and Score evaluations.
26pub mod answer;
27/// Request and response schema validation errors and checks.
28pub mod error;
29/// Model metadata structures for `/v1/models` discovery.
30pub mod models;
31/// Question descriptors and rubric criteria representations.
32pub mod question;
33/// System evaluation request envelope and versioning constants.
34pub mod request;
35/// System evaluation response payload and usage metrics.
36pub mod response;
37/// Flexible evaluation state input (text, structured object, or array).
38pub mod state;
39
40pub use answer::{Answer, ChoiceAnswer, NoulAnswer, ScoreAnswer};
41pub use error::{
42 validate_request, validate_response, validate_response_for_request, ResponseContract,
43 ValidationError, ValidationResult, MAX_CRITERIA_OPTIONS, MAX_QUESTIONS_PER_REQUEST,
44};
45pub use models::{ModelInfo, ModelsResponse};
46pub use question::{ChoiceQuestion, NoulCriteria, NoulQuestion, Question, ScoreQuestion};
47pub use request::{SystemRequest, WireHashState, API_VERSION};
48pub use response::{SystemResponse, Usage};
49pub use state::State;
50
51/// Current API version constant. Bumped when the wire schema breaks compat.
52pub const fn api_version() -> &'static str {
53 API_VERSION
54}
55
56#[cfg(test)]
57mod tests {
58 use super::*;
59
60 #[test]
61 fn api_version_constant_is_stable() {
62 // Pin the wire version. Changing this is a breaking change.
63 assert_eq!(api_version(), "jev-compatible-0.1");
64 }
65}