Public surfaces contract

This document defines which TranscriptX surfaces are supported and which are explicitly not supported. It is the contract for how users and contributors are expected to interact with the system.

1. Supported public surfaces

1.1 GUI (Streamlit web app)

  • The Streamlit web interface (launched via transcriptx or python -m transcriptx.web) is the primary supported interface.

  • Supported operations include:

    • Importing transcripts into managed storage (managed import workflow).

    • Running analysis on individual transcripts and groups.

    • Viewing results via Transcript → Overview → Insights → Charts → Artifacts.

    • Correct mode on Transcript for word/span propose/apply (see runtime/corrections-viewer.md); Corrections Studio for batch/detector/LLM review.

    • Managing basic settings exposed in the UI.

  • Use Artifacts (Browse / Preview / Export). Overview / Artifacts ZIP export includes selected files plus generated index.html and, when ebooklib is available, index.epub (see runtime/export.md). Legacy Data / Explorer (File List) page keys are no longer supported (removed in 0.9.7).

  • Built-in layout profiles are immutable (default / Standard, executive, meeting_followup, speaker_focus, minimal, developer_debug, and generated all). Switch, preview, edit (custom), and clone via Settings → Dashboard Builder; custom layouts live under {config_dir}/profiles/ui_layouts/ (PROFILES_DIR/ui_layouts). Charts Overview strip selection is Settings → Configuration → Charts overview, not the Builder.

  • Optional rollback: Speaker Identification mounts the Streamlit Components v2 workspace by default when transcriptx-workspaces is installed. Roll back to the classic fragment UI with TX_SPEAKER_ID_WORKSPACE_COMPONENT=0; missing package falls through to classic automatically. See theme_c_workspaces_ccv2.md.

1.2 Python API

  • The Python API is a supported surface for scripting and automation.

  • Core entrypoints include:

    • run_managed_import_workflow (managed import) — canonical import path: from transcriptx.io.managed_import_workflow import run_managed_import_workflow.

    • run_analysis (single-transcript analysis).

    • Batch and group workflows as documented in docs/generated/cli.md and dev guides.

  • These APIs expect:

    • Canonical or managed transcripts as defined in the storage and terminology contracts.

    • Use of typed request models (e.g. AnalysisRequest, BatchAnalysisRequest).

1.3 Managed import workflow

  • The managed import workflow is the only supported way to admit transcripts into managed storage for library-valid analysis:

    • It performs canonical validation.

    • It writes sidecars and archival/original artifacts.

    • It enforces the storage and metadata mirroring invariants.

  • Importing raw JSON directly into the canonical library without going through a managed import path is not supported for library-valid analysis.

1.4 Docker (operational surface)

  • Docker Compose is a supported way to run the Streamlit web app without a local Python install.

  • Supported operations mirror the GUI: import, analysis, browsing results, and settings exposed in the UI.

  • Compose mounts and environment variables are operational configuration only; storage layout, output layout, and run-truth rules are defined in the contracts linked from §1.

  • See docs/runtime/docker.md for build commands, volume mounts, and container-specific pitfalls.

1.5 First-run experience (not extra entrypoints)

  • Prefer task documentation and a clear, complete GUI over reduced presentation modes or in-app tours.

  • Guided / Full controls, Getting started checklist, and bundled demo-project load/remove were trialled in 0.9.6 and removed (see pre_release_roadmap_1_0.md §16). They are not supported product surfaces.

1.6 Transcription command generation (GUI capability)

  • Generating shell/CLI commands for external transcription tools (whispermlx, whispermlx-missing, WhisperX Docker, Whisper-WebUI Gradio deploy) is a shipped GUI capability (0.9.4+): copyable only; Streamlit does not execute transcription. Whisper-WebUI is an optional interoperability recipe only — ownership disclaimer and smoke-test limits: recipes/whisper-webui/README.md.

  • Supported product path remains: external transcript → managed import → analysis.

  • Corpus helpers such as scripts/whispermlx-missing.py and scripts/inbox-watch.py are documented user-facing scripts when referenced from runtime docs. They are not a replacement for managed import: they write raw engine output under originals/. Optional inbox-watch --admit subprocesses python -m transcriptx.admit_originals, which calls admit_and_register (same admission path as Import Transcript). Optional --auto-name / --auto-link (and python -m transcriptx.identify_speakers) run speaker auto-identify after admit — auto-identify.md. Those modules are not transcriptx <subcommand>s. Streamlit does not execute these host scripts.

  • Audio preprocess / merge are available in the GUI under System → Tools (Preprocessing and Merge tabs), with CLI helpers scripts/audio_preprocess.py / scripts/audio_merge.py for automation. Documented in transcription docs; 1.x theme G1 still decides invest in transcript-part stitching vs remove helpers (ROADMAP.md).

  • Workspace backup / restore is available in the GUI under Settings → Storage, with helper script scripts/workspace_backup.py and Python API transcriptx.services.workspace_backup for large corpora. Normative rules: contracts/workspace-backup.md. This is not a transcriptx <subcommand> CLI.

2. Not supported surfaces / patterns

The following patterns are explicitly not supported and should be avoided in user flows, docs, and contributions:

2.1 Direct CLI analysis commands

  • There is no supported transcriptx <subcommand> analysis CLI.

  • The transcriptx console script:

    • Only launches the web interface.

    • Accepts --host and --port flags.

  • Any usage of transcriptx analyze ..., transcriptx transcript ..., or similar subcommands is considered deprecated and unsupported.

2.2 Legacy Streamlit entry (web/streamlit_app.py)

  • The former src/transcriptx/web/streamlit_app.py stub has been removed.

  • Canonical GUI module: transcriptx.web.app.

  • Supported launch commands:

    • transcriptx

    • python -m transcriptx.web

    • streamlit run src/transcriptx/web/app.py

2.3 Ad hoc JSON ingestion

  • Directly pointing analysis at arbitrary JSON files that:

    • Have not gone through canonical validation, and

    • Are not part of the managed transcript set

  • is not supported as a stable surface.

  • Codepaths that “guess” based on filenames or directory placement (e.g. “any .json under transcripts_dir”) violate the storage and admission contracts.

2.4 Direct filesystem operations on managed storage

  • Direct filesystem writes, renames, or deletions under:

    • transcripts_dir and its metadata subtrees,

    • managed outputs and state defined in the storage and output contracts,

  • are not supported and may corrupt invariants.

  • Supported behavior:

    • Use the storage rename service (rename_managed_transcript / web RenameService) for managed transcript moves; repair incomplete ops via repair_managed_rename.

    • Use public APIs to modify or regenerate artifacts.

3. Contributor guidance

  • When adding new features or entrypoints:

    • Prefer the GUI and Python API as integration points.

    • Keep new surfaces aligned with this contract; if you introduce a new public surface, document it here.

  • When removing or deprecating surfaces:

    • Update this document to reflect what remains supported.

    • Make deprecated patterns clearly visible in docs to avoid reintroduction.

4. Contract violations

This section describes public surface contract violations, how they are detected, and the expected behavior.

  • Invalid states (examples):

    • Docs or examples that present unsupported CLI subcommands (for example, transcriptx analyze ...) as if they were supported.

    • Features or codepaths that rely on direct filesystem manipulation of managed storage instead of using documented public APIs.

    • Workflows that bypass the managed import workflow while still claiming library-valid analysis guarantees.

  • Detection:

    • Documentation reviews that compare guides and README against this contract.

    • Tests or linters that scan for references to deprecated or unsupported surfaces.

    • Code review checklists that flag direct filesystem operations on managed storage paths.

  • Expected behavior:

    • Treat such cases as fail-fast documentation or API violations: update docs and/or code to align with this contract before shipping.

    • Where users depend on an unsupported surface, clearly mark it as unsupported and provide a migration path to a supported surface where feasible.

This contract is the reference point for “what is supported” in README, installation docs, and CONTRIBUTING.