Skip to main content

Crate kopitiam_ai

Crate kopitiam_ai 

Source
Expand description

Pluggable model adapters for KOPITIAM’s Semantic Runtime.

This crate defines the ModelAdapter trait — the sole boundary through which a model (local Qwen, Claude, GPT, Gemini, …) is invoked anywhere in the platform. Per the Semantic Runtime’s dependency rule, only kopitiam-workflow depends on this crate; everything else in the platform (kopitiam-knowledge, kopitiam-index, kopitiam-search, kopitiam-workspace, kopitiam-translation) stays model-agnostic.

What lives here is the shape of a request/response (CompletionRequest, CompletionResponse, Message), one deterministic stub adapter (EchoAdapter, always available) so kopitiam-workflow has something real to compile and test against with no weights and no network, and — behind the default-on local Cargo feature — LocalAdapter, a real, offline, on-CPU adapter backed by kopitiam-runtime’s Qwen inference stack. See [local]’s module docs for the full local-vs-cloud architecture and why depending on kopitiam-runtime from here does not violate the Semantic Runtime’s dependency rule.

Two other pieces round out the boundary for a live chat UI:

Structs§

Applied
The result of Glossary::apply: the rewritten output, plus the audit report of exactly what was substituted.
BilingualOptions
Options for render_bilingual.
BilingualSegment
One aligned source/target pair with a stable anchor.
Bucket
One severity bucket of diagnostics: a label and the distinct diagnostics that fell under it.
CloudStub
A scaffold CloudAdapter for one CloudVendor: does key-detection for real, and stands in for the not-yet-built network layer by returning a clear CloudUnavailable either way.
CompletionRequest
A request to a crate::ModelAdapter.
CompletionResponse
A crate::ModelAdapter’s reply to a CompletionRequest.
ConfidenceSignals
The composable evidence behind one segment’s confidence, recorded so every decision is auditable (never a silent accept).
DiagnosticBuckets
The result of classify_diagnostics: severity buckets over the deduplicated diagnostics.
DropReport
A record of what a preprocessing step removed, filtered, or could not judge.
EchoAdapter
A ModelAdapter that invokes no model at all: it echoes the last Role::User message back as the response.
Entry
One glossary rule: replace every (deterministically matched) occurrence of source with target.
Glossary
An ordered set of Entrys applied deterministically to text.
LocalAdapter
A crate::ModelAdapter that runs a GGUF Qwen model entirely on this machine’s CPU via kopitiam-runtime — no network, no cloud account, no API key. This is what makes CLAUDE.md’s Offline First pipeline (“existing knowledge, then native Rust, then local AI, then cloud AI as the final fallback”) a real, callable rung rather than a promise: before this type existed, “local AI” had nothing behind it but crate::EchoAdapter, which invokes no model at all.
Message
One turn in a CompletionRequest.
Preprocessed
A preprocessing result: the compact output, plus the DropReport of what producing it removed or set aside.
ReviewCoverage
The quantified review saving: of total segments, flagged need a look, so a reviewer reads review_fraction of the document (§13 measurement).
SegmentPlan
The plan for one segment: the local draft, the confidence, the routing decision, and the signals behind it.
Substitution
One reported substitution: source was replaced by target exactly count times. Only terms that actually fired appear in an Applied report.
TwoPassConfig
Configuration for draft_and_route: the routing threshold, the length comfort band, and the source/target language hints used only to frame the draft prompt.
TwoPassPlan
The result of draft_and_route: one SegmentPlan per input segment, plus any honesty caveats that apply to the whole plan.
TwoPassSummary
The measurable split produced by TwoPassPlan::summary.

Enums§

CloudUnavailable
Why a cloud rung couldn’t answer. Both variants are the honest miss signal the design’s dispatch ladder relies on (temp_ai_design.md §2): the provider reports it can’t cover the task instead of bluffing, and the dispatcher falls through.
CloudVendor
Which cloud vendor a CloudAdapter talks to. Each knows the environment variable its API key lives in, a human-facing name, and a sensible default model id — the minimum a dispatcher needs to probe the rung before any network layer exists.
Decision
What to do with one drafted segment.
Layout
How to lay the aligned pairs out.
Role
Who authored a Message in a CompletionRequest.
SourceKind
Which deterministic matching rule an Entry’s source uses, decided from the source text itself (rule 2 above).
StreamChunk
One piece of a streamed model reply, delivered in order over the Receiver that ModelAdapter::stream returns.

Constants§

DEFAULT_ACCEPT_THRESHOLD
The conservative default TwoPassConfig::accept_threshold.
DEFAULT_REVIEW_THRESHOLD
The default confidence below which a segment is treated as needing review.
ECHO_PASSTHROUGH_NOTE
Stamped into a DropReport whenever preprocessing ran against the echo stub instead of a real local model: the “output” is the input echoed back, not a filtered or compressed result, and must not be trusted as one.
REVIEW_MARKER
The visible marker stamped on a segment that needs review, so a human scanning the aligned output lands on it immediately. Kept as a stable literal substring so tooling (and review_targets consumers) can grep for it.
TWO_PASS_ECHO_PASSTHROUGH_NOTE
Stamped into a TwoPassPlan whenever drafting ran against the echo stub instead of a real local model: the “draft” is the source echoed back and the round-trip agreement is trivially perfect, so the round-trip signal carries no information and is folded in as neutral. Do not read a high local_fraction from an echo run as evidence the local model is good enough.

Traits§

CloudAdapter
The vendor-specific seam of a cloud model adapter.
ModelAdapter
A pluggable connection to one model backend.

Functions§

classify_diagnostics
Bucket raw compiler-diagnostic text by severity, after removing exact duplicates.
dice_similarity
Character-bigram Sørensen–Dice similarity in 0..=1 (1.0 = identical), the round-trip agreement metric. Deterministic, dependency-free, and character-based so it works on CJK source text.
draft_and_route
Draft every segment with the local adapter, apply the III-5 glossary deterministically, score confidence from composable signals, and route each segment to AcceptLocal or SendToCloud against cfg.accept_threshold.
draft_commit_message
Draft a commit-message subject line for diff by routing the whole diff through the local model (optional helper; card II-6).
from_two_pass
Bridge from III-6: build aligned segments from a slice of two-pass crate::SegmentPlans and a parallel slice of finished targets (the reviewed/final target text for each plan, in the same order).
glossary_score
Glossary sub-score in 0..=1. Neutral 0.5 when no glossary was supplied or nothing hit; rising with diminishing returns as more project-decided terms are pinned deterministically (0.5 + 0.5·(1 − 1/(1+hits))). Hits are positive evidence — never a penalty for a term-free segment.
length_score
Length sub-score in 0..=1: 1.0 within the comfortable band [min, max], falling off linearly to 0.0 at zero length and decaying toward a 0.3 floor for over-long segments.
render_bilingual
Render aligned source/target output with stable per-segment anchors.
review_coverage
Compute the ReviewCoverage for a set of segments using the default review threshold — the measurement backing the card: a reviewer reads flagged of total.
review_targets
The anchors of the segments a reviewer must actually check — the “read only these” list (§0.1). A segment is included when it is needs_review or its recorded confidence is below DEFAULT_REVIEW_THRESHOLD. Returned in ascending index order to match the rendered output.
summarize
Compress text to at most target_lines lines by routing it through the local model, then hard-capping the reply at target_lines.
triage
Filter candidates (e.g. grep-hit snippets) down to the subset plausibly relevant to query, by asking the local model which to keep.