README.md

Example catalog

The examples are small, runnable programs built against Watch Skill's public interfaces. They are numbered by learning path, not release order.

Before you run them

From the repository root:

uv sync --extra all
uv run watch-skill doctor

Commands below assume uv run --no-sync. If Watch Skill is already installed in your active environment, invoke python and watch-skill directly instead.

Recommended path

#	Example	Main requirement	What you should learn
01	Watch and ask	Network for the sample URL	Index one video and answer from cited evidence.
02	Focused moment	Example 01 or another indexed video	Resample a narrow time window at higher density.
03	Cross-video search	Two or more indexed videos	Find relevant moments across the library.
04	UI loop	Playwright and a vision provider	Capture, critique, fix, and verify a local page.
05	Multilingual Arabic	OCR extras	Preserve the source language through OCR, search, and answers.
06	Agent integration	MCP or REST extra	Expose the same engine to an external agent.
07	Lessons and stats	An indexed video	Store a correction and inspect its cost/token effect.
08	Loop types	Vision provider; capture support varies	Apply the loop to generated video, games, and monitors.
09	Framework adapters	The selected framework extra	Hand native tools to LangChain, CrewAI, or Agents SDK.
10	Structured extraction	An indexed clip	Produce chapters, a bug report, and hook analysis.
11	Batch mode	Pillow and ffmpeg	Index a folder and query it as one collection.
12	Library memory	Pillow and ffmpeg	Synthesize an answer whose evidence spans multiple clips.
13	Self-improvement	Local lessons enabled	Evaluate lessons and retire guidance the pipeline outgrew.
14	Browser verification	Playwright and a vision provider	Catch a transient flow bug that a final screenshot cannot show.
15	Private offline workflow	OCR extra and ffmpeg	Run acquisition, OCR, indexing, and answers with cloud use disabled.
16	Shareable viewer	Any indexed video	Export one self-contained HTML report.
17	Freshness and offline	ffmpeg	An overwritten video becomes a new revision; offline stays offline with keys set; an empty critique is inconclusive.
18	Live watch	ffmpeg, Pillow	A state change reported while the source is still playing, then finalised into ordinary indexed memory.
19	Live browser	Playwright chromium	Page pixels and console/network/DOM evidence, both before the page closes, against a broken local fixture.
20	Observer Loop	Playwright chromium	A postcondition frozen first, a correction that waits for a named human, and a verdict from a separate process.
20	Observer Loop	Playwright chromium	Success declared first, a correction that waits for a human, and a verdict from a separate verifier process.

Useful commands

watch-skill list
watch-skill clean --dry-run
watch-skill stats --cost

Most examples write only to the configured Watch Skill data directory. Examples that make temporary clips identify their workspace in the output and remove it when the process exits. The shareable-viewer example writes the requested HTML file intentionally.

Contributing an example

Keep each example focused on one outcome. Include a README.md, a runnable entry point, the exact command, prerequisites, and representative output. Network-backed examples should provide a local or generated alternative when that is practical.