Metadata-Version: 2.3
Name: k-flow
Version: 0.3.4
Summary: Contract-first voice kernel skeleton with transport wrappers
Author: KpihX
Author-email: KpihX <kapoivha@gmail.com>
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: websockets>=12.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown

## flow

Hardware-first voice kernel for local STT/TTS orchestration on Intel-focused workstations.

Current status:

- Contract-first workflow is enforced.
- `CONTRACT.md` is the non-negotiable source of truth for internal API and transport wrappers.
- A modular core and transport adapters are implemented.
- Runtime STT execution is implemented with backend orchestration.

## Scope

- Stable internal API surface (`dispatch` + operation set).
- Transport wrappers:
  - CLI (`flow`)
  - stdio JSONL (`flow-stdio`)
  - WebSocket frame processor + server entry (`flow-ws`)
  - MCP tool wrapper mapping (`flow.adapters.mcp`)
- Frozen conventions (types, error codes, event schema).
- Runtime policy:
  - default backend: `whispercpp_vulkan`
  - fallback backend: `ctranslate2_cpu_int8`
  - mandatory normalization: 16kHz mono PCM

## Layout

- `CONTRACT.md` — full protocol and API contract (authoritative).
- `src/flow/kernel.py` — stateful kernel implementation.
- `src/flow/core.py` — stable operation facade + dispatch table.
- `src/flow/protocol.py` — envelope validation and request processing.
- `src/flow/adapters/` — modular transport adapters (`cli`, `stdio`, `ws`, `mcp`).
- `.agents/AGENTS.md` — project operating rules for agents.

## Quickstart

- Contract gate:
  - `make contract-test`
- CLI:
  - `uv run flow --help`
  - `uv run flow session --help`
  - `uv run flow transcribe --help`
  - `uv run flow health --json`
  - `uv run flow status --json`
  - `uv run flow doctor --json`
  - `uv run flow doctor --verbose --json`
- stdio:
  - `uv run flow-stdio --help`
  - `uv run flow-stdio status`
  - `uv run flow-stdio serve`
  - `printf '{"schema_version":"flow.contract.v1","request_id":"req1","timestamp_ms":1,"payload":{"op":"health","args":{}}}\n' | uv run flow-stdio`
- websocket:
  - `uv run flow-ws --help`
  - `uv run flow-ws serve --port 9876`
  - `uv run flow-ws status`
- Enable real runtime STT execution:
  - `export FLOW_ENABLE_REAL_STT=1`

## Runtime server config

Defaults are externalized in `src/flow/config.yaml`:

- `servers.ws.host`, `servers.ws.port`, `servers.ws.path`
- `servers.stdio.name`
- `state.pid_directory` (PID files like `~/.mcps/flow-stdio.pid`, `~/.mcps/flow-ws.pid`)

## STT prerequisites

Before real STT execution (`FLOW_ENABLE_REAL_STT=1`), install and configure:

- `ffmpeg` (for mandatory normalization to 16kHz mono),
- `whisper.cpp` Vulkan binary (`whisper-cli`),
- whisper.cpp model file (`ggml`),
- `whisper-ctranslate2` CLI.

Use your environment/package manager standards for installation and version pinning.  
`flow` runtime does not execute install procedures automatically; it checks availability and reports missing components.

### Linux (current baseline)

For Ubuntu/Debian-class systems, a pragmatic baseline is:

```bash
sudo apt update
sudo apt install -y ffmpeg git cmake build-essential vulkan-tools libvulkan-dev
```

Install `whisper-ctranslate2` CLI with your Python tool manager:

```bash
uv tool install whisper-ctranslate2
```

Build `whisper.cpp` with Vulkan enabled and fetch at least one GGML model:

```bash
git clone https://github.com/ggerganov/whisper.cpp "$HOME/.cache/flow/whisper.cpp"
cmake -S "$HOME/.cache/flow/whisper.cpp" -B "$HOME/.cache/flow/whisper.cpp/build" -DGGML_VULKAN=ON
cmake --build "$HOME/.cache/flow/whisper.cpp/build" -j
bash "$HOME/.cache/flow/whisper.cpp/models/download-ggml-model.sh" base "$HOME/.cache/flow/models"
```

If your distro or driver stack differs, keep the same dependency intent (FFmpeg + Vulkan-capable whisper.cpp + GGML model + ctranslate2 CLI) and adapt commands accordingly.

Diagnostic check from Python:

- `uv run python -c "from flow.bootstrap import bootstrap_all; print(bootstrap_all())"`

## Release

- Distribution name: `k-flow` (module import remains `flow`).
- Build and publish:
  - `make release`
- The `push` pipeline bootstraps missing remotes (`github`, `gitlab`) automatically using `gh` + `glab`.
