noteflow/.rag/03-domain-ports.md

NoteFlow Domain Ports (Protocols)

Location

src/noteflow/domain/ports/

Repository Protocols (repositories/)

Core Repositories (transcript.py)

Protocol	Key Methods
MeetingRepository	add(), get(), list(), update(), delete(), count_by_state(), find_older_than()
SegmentRepository	add(), add_batch(), get(), list_by_meeting(), update(), delete()
SummaryRepository	add(), get(), list_by_meeting(), mark_verified()
AnnotationRepository	add(), get(), list_by_meeting(), update(), delete()

Asset Repository (asset.py)

Protocol	Purpose
AssetRepository	Store/retrieve meeting audio files

Background Jobs (background.py)

Protocol	Purpose
DiarizationJobRepository	Track background diarization jobs

External Repositories (external/)

Protocol	Location	Purpose
EntityRepository	_entity.py	Persist NER entities
IntegrationRepository	_integration.py	Store OAuth integrations
WebhookRepository	_webhook.py	Webhook configs and delivery logs
UsageEventRepository	_usage.py	Track usage metrics

Identity Repositories (identity/)

Protocol	Purpose
UserRepository	User identity and authentication
WorkspaceRepository	Workspace tenancy
ProjectRepository	Project CRUD and member access
ProjectMembershipRepository	Project role-based access
SummarizationTemplateRepository	Template CRUD and versioning
VoiceProfileRepository	Speaker voice profile storage

Engine/Provider Protocols

DiarizationEngine (diarization.py)

Speaker identification (streaming: diart, offline: pyannote)

• assign_speakers(audio: ndarray, segments: list[Segment]) -> list[SpeakerAssignment]
• is_ready() -> bool

NerPort (ner.py)

Named entity recognition with spaCy

• extract(text: str) -> list[NamedEntity]
• extract_from_segments(segments: list[Segment]) -> list[NamedEntity]
• is_ready() -> bool

GpuPort (gpu.py)

GPU detection and capabilities

• detect_gpu() -> GpuInfo
• is_cuda_available() -> bool
• is_rocm_available() -> bool
• get_vram_bytes() -> int | None

OAuthPort (calendar.py)

OAuth PKCE flow

• initiate_auth(provider: str) -> AuthUrl
• complete_auth(code: str, state: str) -> TokenResponse

CalendarProvider (calendar.py)

Calendar event fetching

• list_events(start: datetime, end: datetime) -> list[CalendarEventInfo]

SummarizerProvider (summarization/ports.py)

LLM summarization

• request(context: SummarizationRequest) -> SummarizationResult

Unit of Work Pattern (unit_of_work.py)

Hierarchical Protocol Structure

UnitOfWorkCapabilities
    supports_annotations: bool
    supports_diarization_jobs: bool
    supports_preferences: bool
    supports_entities: bool
    supports_integrations: bool
    supports_webhooks: bool
    supports_usage_events: bool
    supports_users: bool
    supports_workspaces: bool
    supports_projects: bool
    supports_tasks: bool
    supports_voice_profiles: bool

UnitOfWorkCoreRepositories
    meetings: MeetingRepository
    segments: SegmentRepository
    summaries: SummaryRepository
    assets: AssetRepository

UnitOfWorkOptionalRepositories
    annotations: AnnotationRepository | None
    diarization_jobs: DiarizationJobRepository | None
    preferences: PreferencesRepository | None
    entities: EntityRepository | None
    integrations: IntegrationRepository | None
    webhooks: WebhookRepository | None
    usage_events: UsageEventRepository | None
    tasks: TaskRepository | None
    voice_profiles: VoiceProfileRepository | None

UnitOfWorkLifecycle
    __aenter__() / __aexit__()
    commit() async
    rollback() async

Async Context (async_context.py)

Utilities for managing async context in protocols.

Key Data Classes

SummarizationRequest

@dataclass
class SummarizationRequest:
    meeting_id: MeetingId
    segments: list[Segment]
    template: SummarizationTemplate | None
    context: dict[str, str]

SummarizationResult

@dataclass
class SummarizationResult:
    summary: str
    key_points: list[KeyPoint]
    action_items: list[ActionItem]
    model_name: str
    provider_name: str
    tokens_used: int

CalendarEventInfo

@dataclass
class CalendarEventInfo:
    id: str
    title: str
    start_time: datetime
    end_time: datetime
    attendees: list[str]
    location: str | None
    description: str | None

GpuInfo

@dataclass
class GpuInfo:
    available: bool
    backend: str | None  # "cuda", "rocm", None
    device_name: str | None
    vram_bytes: int | None