The Problem

Developers need quick, reproducible ways to experiment with Liquid AI Foundational Models (LFM) and the LEAP SDK—e.g., extracting data from invoices, transcribing audio, or fine‑tuning a model. The repo supplies ready‑to‑run examples but offers no guardrails (CI, licence) and contains several code‑quality pain points that increase maintenance effort.

What This Does

The repository is a collection of self‑contained example applications under examples/.

  • examples/invoice-parser/src/invoice_parser/main.py drives a CLI that watches a folder, downloads a LFM2‑Text model, and runs OCR → LLM extraction (InvoiceProcessor.process).
  • examples/audio-transcription-cli/src/audio_transcription_cli/transcribe.py implements a real‑time transcription loop (cli) that loads a LFM2‑Audio model (model_wrapper.ModelWrapper) and streams audio to transcribe_audio_file.
  • examples/voice-chat/src/voice_chat/server.py starts a WebSocket server (get_model_response) that forwards user utterances to a model and streams back responses.

All examples share a thin wrapper around the LEAP SDK (load_model, load_dataset) and rely on small utility modules (config.py, model_downloader.py) that locate model binaries and set up file‑system paths.

How It Is Wired

Invoice‑parser flow

  1. Entry – python -m examples.invoice_parser.main (line 46).
  2. main calls process_existing_files (line 18) → InvoiceProcessor.process.
  3. InvoiceProcessor.process invokes image2text which loads the model via _download_model (calls model_downloader.ModelDownloader).
  4. The model generates structured output (model.generate) and the result is written to CSV by InvoiceFileHandler.append_to_csv.

Key call‑graph points: print appears 40 × from main; load_model is invoked 4 × across the repo; the only outbound network call is the model download in ModelDownloader.

Audio‑transcription‑cli flow

  1. Entry – python -m examples.audio_transcription_cli.transcribe (line 73).
  2. cli creates ModelWrapper (imports model_wrapper.ModelWrapper).
  3. ModelWrapper.transcribe_audio_file spawns an external llama.cpp process (subprocess.run) and parses its stdout via _parse_output.
  4. The transcription text is streamed to the console and optionally saved by raw_transcript_logger.

Key call‑graph points: print 40 × from cli; transcribe_audio_file is the sole function reaching an external binary; load_model is called once here.

Voice‑chat flow

  1. Entry – uvicorn examples.voice_chat.server:app (implicit – server.py defines app).
  2. Incoming WebSocket messages trigger get_model_response (line 37).
  3. It loads the model (model_loader.load_model_and_processor) and calls model.generate.
  4. Responses are sent back over the socket; audio playback is handled by audio_player.AudioPlayer.start_playback.

Key call‑graph points: print 11 × from record; load_model 4 ×; the server is the only component that opens a network socket.

Hot‑spot modules

  • audio_transcription_cli/model_wrapper.py – highest instability (0.75) with deep nesting (8‑level indentation).
  • voice_chat/audio_recorder.py – deep nesting, file‑handle leak risk.
  • audio_transcription_cli/config.py – imported by 4 modules, but contains duplicated path logic across examples.

How To Use It

# Clone the repo (use the exact URL)
git clone https://github.com/moses-y/cookbook
cd cookbook

# Install uv (or use pip) – uv is referenced by existing lock files
python -m pip install uv

# Example: invoice parser
cd examples/invoice-parser
uv sync               # installs deps from pyproject.toml
python -m invoice_parser.main   # watches ./invoices and writes CSV

# Example: audio transcription
cd ../audio-transcription-cli
uv sync
python -m audio_transcription_cli.transcribe   # starts live transcription

# Example: voice chat server
cd ../voice-chat
uv sync
uvicorn voice_chat.server:app --host 0.0.0.0 --port 8000

Configuration: Each example ships a pyproject.toml that declares its dependencies; no additional environment variables are required. Model binaries are cached under paths defined in config.py (e.g., model_path, llama_binary_path).

Real‑World Use

A SaaS platform could embed the invoice‑parser as a microservice: a file‑upload endpoint drops PDFs into examples/invoice-parser/invoices/, the service runs main in a container, and the generated CSV is consumed by downstream billing logic. The same pattern applies to real‑time transcription for meeting‑note services or to the voice‑chat server for low‑latency conversational agents.

Code Health & Issues

  • HIGH (cognitive_load) – Deep nesting (max depth 8) in audio_recorder.py, model_wrapper.py, inference.py. Refactor with early returns or helper functions.
  • HIGH (clarity) – Repeated 6‑line blocks across examples.sh, config.py, model_downloader.py. Consolidate into shared utilities.
  • MEDIUM (resource_safety) – audio_recorder.py opens files without a context manager; may leak handles.
  • MEDIUM (resilience) – Broad except: clauses in model_wrapper.py and audio_playback.py; replace with specific exception handling.
  • SDLC – No CI/CD pipeline (.github/ absent). No LICENSE file, so redistribution rights are unclear. Dependency declarations lack lockfiles (e.g., audio-transcription-cli/pyproject.toml), leading to non‑reproducible builds.

The Bottom Line

The repo delivers functional, end‑to‑end demos of Liquid AI models with minimal setup, but the codebase suffers from maintainability issues (deep nesting, duplicated logic) and lacks basic project hygiene (CI, licence, lockfiles). It is suitable for rapid prototyping or learning, yet teams should allocate effort to refactor hot‑spot modules and introduce proper CI before using it in production.