Metadata-Version: 2.4
Name: cjm-capability-primitives
Version: 0.0.5
Summary: The dep-light primitives library for the cjm capability ecosystem — defines the shared cross-task result DTOs (data nouns) that tool capabilities emit and task adapters, workflow cores, and the composition layer all consume, so a pure-compute tool capability depends only on its task's data noun, never on the adapter machinery.
Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
License: Apache-2.0
Project-URL: Repository, https://github.com/cj-mills/cjm-capability-primitives
Project-URL: Documentation, https://cj-mills.github.io/cjm-capability-primitives/
Keywords: nbdev
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cjm_plugin_system>=0.0.46
Dynamic: license-file

# cjm-capability-primitives


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Install

``` bash
pip install cjm_capability_primitives
```

## Project Structure

    nbs/
    ├── forced_alignment.ipynb # Standardized word-level forced-alignment DTOs — the data noun forced-alignment tool capabilities emit and task adapters / workflow cores consume, wire-registered so results cross the worker boundary typed.
    ├── transcription.ipynb    # Standardized result DTO for the transcription task — the data noun tool capabilities emit and task adapters / workflow cores consume, wire-registered so results cross the worker boundary typed.
    └── vad.ipynb              # Standardized result DTO for the voice-activity-detection task — the data noun VAD tool capabilities emit and task adapters / workflow cores consume, wire-registered so results cross the worker boundary typed.

Total: 3 notebooks

## Module Dependencies

``` mermaid
graph LR
    forced_alignment["forced_alignment<br/>Forced Alignment Result"]
    transcription["transcription<br/>Transcription Result"]
    vad["vad<br/>VAD Result"]
```

No cross-module dependencies detected.

## CLI Reference

No CLI commands found in this project.

## Module Overview

Detailed documentation for each module in the project:

### Forced Alignment Result (`forced_alignment.ipynb`)

> Standardized word-level forced-alignment DTOs — the data noun
> forced-alignment tool capabilities emit and task adapters / workflow
> cores consume, wire-registered so results cross the worker boundary
> typed.

#### Import

``` python
from cjm_capability_primitives.forced_alignment import (
    ForcedAlignItem,
    ForcedAlignResult
)
```

#### Classes

``` python
@dataclass
class ForcedAlignItem:
    "A single word-level alignment result."
    
    text: str  # The aligned word (punctuation typically stripped by model)
    start_time: float  # Start time in seconds
    end_time: float  # End time in seconds
```

``` python
@dataclass
class ForcedAlignResult:
    "Standardized output for all forced alignment capabilities."
    
    items: List[ForcedAlignItem]  # Word-level alignments
    metadata: Dict[str, Any] = field(...)  # Capability-specific metadata
    
    def from_dict(
        "Reconstruct from a wire payload, re-typing nested items.

`items` holds typed `ForcedAlignItem` objects, so the substrate's typed
wire envelope (stage 2) reconstructs them host-side here rather than
leaving bare dicts (which would break attribute access like `it.text`)."
```

### Transcription Result (`transcription.ipynb`)

> Standardized result DTO for the transcription task — the data noun
> tool capabilities emit and task adapters / workflow cores consume,
> wire-registered so results cross the worker boundary typed.

#### Import

``` python
from cjm_capability_primitives.transcription import (
    TranscriptionResult
)
```

#### Classes

``` python
@dataclass
class TranscriptionResult:
    "Standardized output for all transcription plugins."
    
    text: str  # The transcribed text
    confidence: Optional[float]  # Overall confidence (0.0 to 1.0)
    segments: Optional[List[Dict[str, Any]]]  # Timestamped segments
    metadata: Dict[str, Any] = field(...)  # Additional metadata
```

### VAD Result (`vad.ipynb`)

> Standardized result DTO for the voice-activity-detection task — the
> data noun VAD tool capabilities emit and task adapters / workflow
> cores consume, wire-registered so results cross the worker boundary
> typed.

#### Import

``` python
from cjm_capability_primitives.vad import (
    TimeRange,
    VADResult
)
```

#### Classes

``` python
@dataclass
class TimeRange:
    "A temporal segment within an audio source (the VAD speech/silence span)."
    
    start: float  # Start time in seconds
    end: float  # End time in seconds
    label: str = 'speech'  # Segment type (e.g. 'speech')
    confidence: Optional[float]  # Detection confidence (0.0 to 1.0)
    payload: Dict[str, Any] = field(...)  # Extra data (reserved)
    
    def to_dict(self) -> Dict[str, Any]:  # Serialized representation
        "Convert to dictionary for JSON serialization."
```

``` python
@dataclass
class VADResult:
    "Standardized output for voice-activity-detection capabilities."
    
    ranges: List[TimeRange]  # Detected speech segments, sorted by start
    metadata: Dict[str, Any] = field(...)  # Global VAD stats (duration, sample_rate, total_speech, ...)
    
    def from_dict(
        "Reconstruct from a wire payload, re-typing nested TimeRanges.

`ranges` holds typed `TimeRange` objects, so the substrate's typed wire
envelope (stage 2) reconstructs them host-side here rather than leaving
bare dicts (which would break attribute access like `r.start`)."
```
