Agentic POS monitoring (liquor store demo)

When to use this skill

Use this skill when:

• Editing workflow/agents.py (specialist agents, Hypothesis, incident kinds).
• Changing workflow/run_workflow.py (orchestration, merge logic, CLI).
• Updating workflow/policy.py or ensuring Streamlit sidebar keys stay in sync with PolicyConfig.
• Modifying data/shift_segments.json or data/pos_events.csv (segments, video_path, audio_path, mock_cv / mock_asr).
• Working on ui/app.py (tabs, workflow run, Copilot chat, Slack/Discord).
• Fixing HTTPS / SSL for webhooks (workflow/ssl_util.py, certifi).
• Adding docs (docs/ARCHITECTURE.md, SVG diagrams) or deployment (Dockerfile, Streamlit Cloud, requirements.txt).

Repository map

Path	Role
workflow/agents.py	UnderRing, CustomerService, CheckoutSequence, POSPresence, POSAnomaly agents
workflow/run_workflow.py	LiquorStoreAgentWorkflow, _merge_hypotheses, WorkflowState
workflow/policy.py	PolicyConfig — single source of policy defaults
workflow/loaders.py	load_pos_csv, load_segments_json (paths relative to project root)
workflow/types.py	AVSegment, Hypothesis, IncidentReport, POSEvent
data/shift_segments.json	Segments + mock_cv / mock_asr + media paths
ui/app.py	Streamlit UI; ROOT = parent of ui/
docs/ARCHITECTURE.md	Mermaid + modality → agent diagrams

Patterns

Adding or changing an agent

1. Implement propose(...) returning list[Hypothesis] with stable agent class attribute (name = "...").
2. Wire it in LiquorStoreAgentWorkflow.__init__ and run() (per-segment vs global POS pass like POSAnomalyAgent).
3. Extend _merge_hypotheses in run_workflow.py if new incident_kind values need recommended_actions heuristics.
4. Update docs/ARCHITECTURE.md and modality diagram if inputs change.

Policy and UI parity

• PolicyConfig fields must match Streamlit st.session_state keys built in _init_policy_session / policy_from_session in ui/app.py.
• Adding a policy field: dataclass default → session defaults → sidebar widget → policy_from_session().

Media paths

• video_path and audio_path in JSON are relative to project root (e.g. media/scenarios/foo.mp4), not necessarily under data/.
• The UI resolves with ROOT / video_path. Files only in data/*.mp4 appear in the “MP4 files in data/” section; scripted expanders still need JSON entries.

Webhooks and secrets

• Prefer env or .streamlit/secrets.toml; never commit webhook URLs or API keys.
• Slack Block Kit posts need a top-level text alongside blocks for reliable client behavior.
• Use workflow/ssl_util.urlopen_webhook for outbound HTTPS consistent with certifi.

Copilot chat (optional)

• workflow/copilot_chat.py: Whisper STT, chat completions, TTS; OPENAI_API_KEY from env or secrets.
• st.audio_input requires Streamlit ≥ 1.33 and a secure context (localhost / HTTPS).

Common mistakes

• Importing workflow modules from ui/app.py without putting project root on sys.path (already done via ROOT).
• Forgetting audio_path when changing video_path — loaders require both; extract WAV with ffmpeg or use silent WAV pattern from scripts/fetch_live_demo_media.py.
• Git push HTTP 400 on large packs: git config http.postBuffer 524288000 and git config http.version HTTP/1.1, or use SSH remote.
• Committing .venv, secrets, or SSH private keys — keep them gitignored.

Testing locally

cd liquor_store_agentic_monitor
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements-demo.txt
python3 -m streamlit run ui/app.py

CLI workflow (no UI):

python3 -m workflow.run_workflow --root .

Publishing this skill (Shipables)

From skills/retail_store_agentic_monitor/ (must match Shipables slug memanj/retail_store_agentic_monitor):

shipables login    # first time
shipables publish --dry-run
shipables publish

Copy into Cursor for local testing:

cp -r skills/retail_store_agentic_monitor ~/.cursor/skills/retail_store_agentic_monitor

See references/shipables-notes.md and Creating a Skill | Shipables.