feat: create Circuit-Forge/cf-voice repo with stub VoiceFrame API #39

New issue

Closed

opened 2026-04-06 15:38:07 -07:00 by pyr0ball · 1 comment

pyr0ball commented

2026-04-06 15:38:07 -07:00

Owner

Context

Linnet (Notation v0.1.x) and Osprey both need cf_voice. Architecture decision: standalone repo, not a cf-core module (see #35).

Approach: create the repo immediately with a stub VoiceFrame that returns synthetic tone events. Linnet builds against the real import path from day one using the stub, then cf-voice classifiers are filled in incrementally.

Deliverables for this ticket

Create Circuit-Forge/cf-voice repo (public, MIT for IO layer / BSL for inference layer)
Define VoiceFrame dataclass: label: str, confidence: float, speaker_id: str, shift_magnitude: float, timestamp: float
Stub cf_voice.io — returns synthetic VoiceFrame events on a timer (no real audio)
Stub cf_voice.context — wraps stub IO, passes through VoiceFrame
--mock-voice flag / env var CF_VOICE_MOCK=1 that activates stub mode
pyproject.toml with versioned package (cf-voice)
README with install instructions and VoiceFrame API docs

VoiceFrame API contract

@dataclass
class VoiceFrame:
    label: str           # e.g. "Warmly impatient"
    confidence: float    # 0.0–1.0
    speaker_id: str      # local ephemeral label, e.g. "speaker_a"
    shift_magnitude: float  # delta from previous frame, 0.0–1.0
    timestamp: float     # session-relative seconds

Install target

Linnet will install via: pip install -e ../cf-voice (editable, same pattern as cf-core)

Consumed by

Circuit-Forge/linnet (Notation v0.1.x) — first consumer
Circuit-Forge/osprey — second consumer (telephony path)

Blocking

Circuit-Forge/linnet#3, Circuit-Forge/linnet#4, Circuit-Forge/linnet#5

## Context Linnet (Notation v0.1.x) and Osprey both need `cf_voice`. Architecture decision: standalone repo, not a cf-core module (see #35). Approach: create the repo immediately with a **stub** `VoiceFrame` that returns synthetic tone events. Linnet builds against the real import path from day one using the stub, then cf-voice classifiers are filled in incrementally. ## Deliverables for this ticket - [ ] Create `Circuit-Forge/cf-voice` repo (public, MIT for IO layer / BSL for inference layer) - [ ] Define `VoiceFrame` dataclass: `label: str`, `confidence: float`, `speaker_id: str`, `shift_magnitude: float`, `timestamp: float` - [ ] Stub `cf_voice.io` — returns synthetic `VoiceFrame` events on a timer (no real audio) - [ ] Stub `cf_voice.context` — wraps stub IO, passes through `VoiceFrame` - [ ] `--mock-voice` flag / env var `CF_VOICE_MOCK=1` that activates stub mode - [ ] `pyproject.toml` with versioned package (`cf-voice`) - [ ] README with install instructions and `VoiceFrame` API docs ## VoiceFrame API contract ```python @dataclass class VoiceFrame: label: str # e.g. "Warmly impatient" confidence: float # 0.0–1.0 speaker_id: str # local ephemeral label, e.g. "speaker_a" shift_magnitude: float # delta from previous frame, 0.0–1.0 timestamp: float # session-relative seconds ``` ## Install target Linnet will install via: `pip install -e ../cf-voice` (editable, same pattern as cf-core) ## Consumed by - `Circuit-Forge/linnet` (Notation v0.1.x) — first consumer - `Circuit-Forge/osprey` — second consumer (telephony path) ## Blocking `Circuit-Forge/linnet#3`, `Circuit-Forge/linnet#4`, `Circuit-Forge/linnet#5`

pyr0ball added the

priority:high

module:voice

architecture

labels 2026-04-06 15:38:07 -07:00

pyr0ball referenced this issue from Circuit-Forge/linnet

2026-04-06 15:40:03 -07:00

feat: cf_voice dependency — Circuit-Forge/circuitforge-core#39 #3

pyr0ball commented

2026-04-06 16:03:20 -07:00

Author

Owner

Shipped in Circuit-Forge/cf-voice @ 35fc0a0.

VoiceFrame dataclass with is_reliable() and is_shift() helpers
MockVoiceIO — async generator of synthetic frames, activated by CF_VOICE_MOCK=1
ContextClassifier — passthrough stub; _enrich() hook ready for YAMNet/wav2vec2
make_io() factory with env-based mock detection
12 tests passing

Install: pip install -e ../cf-voice

Linnet#3, #4, #5 can now unblock.

Shipped in Circuit-Forge/cf-voice @ 35fc0a0. - `VoiceFrame` dataclass with `is_reliable()` and `is_shift()` helpers - `MockVoiceIO` — async generator of synthetic frames, activated by `CF_VOICE_MOCK=1` - `ContextClassifier` — passthrough stub; `_enrich()` hook ready for YAMNet/wav2vec2 - `make_io()` factory with env-based mock detection - 12 tests passing Install: `pip install -e ../cf-voice` Linnet#3, #4, #5 can now unblock.

pyr0ball closed this issue

2026-04-06 16:03:20 -07:00