store.FeedbackStore

Persistent store for collected feedback over a FileStateStore.

Usage

Source

store.FeedbackStore()

Layers the feedback_events table (extended with the origin_path display-hint column) onto cc-transcript’s file-mtime ledger and adds the triage verdict table (the judge package’s verdict mechanism pinned to cc-steer’s column names), the refinement table, and the accepted_steering and refined_pairs views. Verdicts and refinements key on the content-derived dedup key, so they survive a database rebuild; the enrich stage’s code evidence lives in cc-transcript’s shared corrections ledger, keyed by the steering anchor.

Example

async with await FeedbackStore.open(FeedbackStore.default_path()) as store: … await store.record_file_scan(str(path), mtime, candidates)

Attributes

Name Description
ACCEPTED_COLUMN str(object=’’) -> str
SUMMARY_COLUMN str(object=’’) -> str
VERDICT_TABLE str(object=’’) -> str

ACCEPTED_COLUMN

str(object=’’) -> str

ACCEPTED_COLUMN="is_steering"

str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

SUMMARY_COLUMN

str(object=’’) -> str

SUMMARY_COLUMN="what_claude_did"

str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

VERDICT_TABLE

str(object=’’) -> str

VERDICT_TABLE="triage"

str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

Methods

Name Description
candidates() Returns one row per event with its latest judge verdict and refine summary.
default_path() Returns the default database path, ~/.cc-steer/feedback.db.
embeddings() Returns every stored exemplar embedding for model, oldest first.
gate_sample_stats() Returns gate sample counts keyed by kind.
gate_samples() Returns gate samples, oldest first, optionally restricted to one kind.
lineage() Returns one event with all its triage verdicts and latest refined pairs.
negative_sessions() Returns the sessions that already carry random-negative samples.
open() Opens (creating if needed) the feedback database at path.
pairs() Returns every row of the refined_pairs view, the pipeline’s deliverable.
record_embeddings() Upserts exemplar embeddings as (dedup_key, model, text_digest, dim, vector) rows.
record_file_scan() Records a scanned file and its candidates in one transaction.
record_gate_samples() Records gate training samples idempotently, keyed by sample_key.
record_refinement() Records one event’s atomic refined pairs in a single transaction.
triage_stats() Returns triage coverage and acceptance at prompt_version.
unenriched() Returns refined pairs whose steering anchor carries no shared-ledger correction.
unrefined() Returns accepted steering events lacking a refinement at (prompt_version, model).

candidates()

Returns one row per event with its latest judge verdict and refine summary.

Usage

Source

candidates()

Powers the dashboard’s candidate view across every pipeline status — refined, accepted-but-unrefined, judge-rejected noise, and unjudged. The verdict and refine columns are NULL for events that have not reached that stage.

Returns
list[dict[str, object]]

One dict per event: the event columns plus the latest judge verdict

(category, is_steering, confidence, judge_version,

judge_model, what_claude_did), the latest auditor side

(auditor_is_steering), the judge flipped flag, and the refine

summary (pair_count, refine_version, refine_model).

default_path()

Returns the default database path, ~/.cc-steer/feedback.db.

Usage

Source

default_path()

embeddings()

Returns every stored exemplar embedding for model, oldest first.

Usage

Source

embeddings(*, model)

gate_sample_stats()

Returns gate sample counts keyed by kind.

Usage

Source

gate_sample_stats()

gate_samples()

Returns gate samples, oldest first, optionally restricted to one kind.

Usage

Source

gate_samples(*, kind=None)

lineage()

Returns one event with all its triage verdicts and latest refined pairs.

Usage

Source

lineage(dedup_key)

Reads feedback_events, triage, and latest_refinement directly — the deliverable views drop the auditor, the older judge versions, and the payload the lineage needs.

Parameters
dedup_key: str
The event’s content-derived key.
Returns
dict[str, object]

The event columns plus verdicts (every judge and auditor row, oldest

first) and pairs (the latest refinement generation, by pair_index),

or {} when no event carries the key.

negative_sessions()

Returns the sessions that already carry random-negative samples.

Usage

Source

negative_sessions()

open()

Opens (creating if needed) the feedback database at path.

Usage

Source

open(path)

pairs()

Returns every row of the refined_pairs view, the pipeline’s deliverable.

Usage

Source

pairs()

record_embeddings()

Upserts exemplar embeddings as (dedup_key, model, text_digest, dim, vector) rows.

Usage

Source

record_embeddings(rows)

record_file_scan()

Records a scanned file and its candidates in one transaction.

Usage

Source

record_file_scan(path, mtime, candidates)

The platform store’s ingestion, plus the scanned path lands in each row’s origin_path — a display hint only (the dashboard’s project labels); transcript resolution always goes through discovery by session UUID.

Parameters
path: str

The scanned file’s path.

mtime: float

The file’s modification time at scan.

candidates: Sequence[FeedbackCandidate]
The candidates extracted from the file.
Returns
int
The number of newly inserted feedback events.

record_gate_samples()

Records gate training samples idempotently, keyed by sample_key.

Usage

Source

record_gate_samples(samples)
Parameters
samples: Sequence[GateSample]
The samples to persist; re-inserting an existing key is a no-op.
Returns
int
The number of newly inserted samples.

record_refinement()

Records one event’s atomic refined pairs in a single transaction.

Usage

Source

record_refinement(key, refinement, *, prompt_version, model)

Keyed by (dedup_key, prompt_version, model, pair_index) so re-running over a fully refined corpus is a no-op and every pair of one event commits together.

Parameters
key: DedupKey

The refined event’s dedup key.

refinement: Refinement

The atomic pairs to persist.

prompt_version: int

The refine prompt version that produced them.

model: str
The resolved model name that produced them.

triage_stats()

Returns triage coverage and acceptance at prompt_version.

Usage

Source

triage_stats(*, prompt_version)

unenriched()

Returns refined pairs whose steering anchor carries no shared-ledger correction.

Usage

Source

unenriched(log, *, limit=None)

A pair settles once its (session_id, event_uuid) anchor has a row in the shared corrections ledger — the single source of truth for “done”. Since the extractor is idempotent per anchor, every pair sharing one anchor settles together the moment any of them writes its row. Pairs come from the latest refine generation only, so a refine re-run resurfaces its new pairs here automatically. Anchors that legitimately yield no correction (expired, editless, or no faulted edit) never settle, but resolving them costs no LLM call.

Parameters
log: CorrectionLog

The shared correction ledger to check each anchor against.

limit: int | None = None
When set, the maximum number of rows to return.
Returns
list[dict[str, object]]

One dict per unenriched pair with the columns the extractor and anchor

resolution need, oldest event first.

unrefined()

Returns accepted steering events lacking a refinement at (prompt_version, model).

Usage

Source

unrefined(*, prompt_version, model, limit=None)

Surfaces the columns the refine prompt needs — dedup_key, source_kind, text, context_json, payload_json, and the judge’s what_claude_did hint — oldest first.

Parameters
prompt_version: int

The refine prompt version the refinement must carry.

model: str

The resolved model name the refinement must carry.

limit: int | None = None
When set, the maximum number of rows to return.
Returns
list[dict[str, object]]
One dict per accepted, unrefined event.