Feature similarity and hosted analysis

Perseval separates deterministic failure identity from optional similarity and hosted assistance.

Detector ID, version, structured subject, operation, error kind, and evidence determine an exact failure signature. Those groups drive recurrence, review, and eval candidates.

Enabling feature similarity or a hosted provider cannot merge exact groups, change representative evidence, rewrite candidate IDs, or alter review decisions.

When enabled, Perseval projects safe finding features into a bounded vector and runs seeded K-means locally. Cohorts help discover groups with related execution shape that do not share an exact signature.

Defaults:

• disabled;
• at least 3 findings before fitting;
• at most 20,000 cases per model;
• at most 8 clusters;
• project, analysis-definition, and scope isolated;
• model history and feature cache bounded.

The local projection is not semantic understanding and the distance is not a probability of failure. Treat a cohort as a navigation aid.

Hosted capabilities are independently disabled until the master provider opt-in is enabled:

• embeddings for the safe finding projection;
• human-readable labels after a local K-means fit;
• a semantic behavior judge over structured-only behavior facts.

OPENAI_API_KEY is read from the launch environment and is never saved in TOML, SQLite, DuckDB, or blob storage. Merely setting the key does not enable a call.

Embeddings and labels receive a versioned safe finding projection and bounded representative safe cases. The semantic judge receives a StructuredOnly behavior projection.

Raw payload blobs, prompts, messages, reasoning, source code, tool payloads, full inputs, and full outputs are excluded. Externalization is not consent: check Settings and the provider description before enabling anything.

Missing keys, provider errors, or rate limits leave deterministic groups usable. Provider health is sanitized, retry backoff is bounded, and deterministic results commit even when an augmentation is incomplete.

Provider jobs are not yet a durable retry ledger. Restart can require an augmentation to be scheduled again.

Automated tests prove configuration dependencies, project/scope isolation, cache invalidation, deterministic invariance, cancellation, bounded queues, and safe serialization. They do not prove that hosted embeddings, labels, or judgments improve finding quality on production traffic.

No held-out quality/cost study has been published. Do not interpret optional hosted output as ground truth.

Use Settings → Analysis to enable local similarity first. Enable hosted analysis only after reviewing the data boundary and launching Perseval with OPENAI_API_KEY. Settings reports provider readiness and degraded state without storing the secret.