LarkGuard

• 

• 

• 

• 

• 

Inspiration

I kept seeing the same pattern on GitHub: bug reports that sound urgent but lack clear repro steps, environment details, or proof of what actually failed. Maintainers burn time triaging noise before they can even try to reproduce.

I built LarkGuard because I wanted a verifier that starts with evidence, not guesses - and that still delivers a useful result when AI or agent infrastructure is down. The hackathon’s Lark and TrueFoundry tracks pushed me to design around real workflow execution and resilient parsing, not a brittle “all-or-nothing” demo agent.

What it does

LarkGuard takes a GitHub issue (and comments), normalizes it into an evidence packet, and runs a replayable verification pipeline:

Issue → evidence packet → verification brief → verification plan → verification result

It can return statuses like reproduced, simulated, blocked, or not reproduced, store every run locally for replay, and post one managed comment on the issue (create on first run, update on re-runs) with proof, timings, and next steps.

Honest semantics: When the status is Reproduced, that means live getlark workflow execution proof (e.g. captured wflw_exec_…) - not a claim that I fully reproduced the target application bug end-to-end_

Sponsor integrations:

getlark.ai - live REST workflow listing + optional invoke, optional live CLI listing; MCP/CLI scaffolds for the full execution path I’m building toward. TrueFoundry AI Gateway - optional structured parser with deterministic fallback when the gateway is unavailable. When parser or adapter infrastructure fails, LarkGuard degrades gracefully and surfaces explicit health states (healthy, degraded-parser, degraded-adapter, degraded-both) instead of silently failing the maintainer workflow.

How I built it

I built LarkGuard as a Python + FastAPI service with Pydantic models and httpx for GitHub and sponsor APIs. I added a Rich CLI so I could demo and debug without always running the server.

Core pipeline

Fetch issue + comments via GitHub REST (skipping my own managed bot comments on re-runs). Parse into a structured verification_brief - deterministic by default for reproducible demos and tests. Build a verification_plan (workflow goal, steps, assumptions, blockers). Execute through a pluggable Lark adapter layer and persist JSON under .larkguard_runs/ for replay. Parser layer (TrueFoundry track)

Default: rule-based deterministic parser. Optional: one OpenAI-compatible POST /chat/completions through TrueFoundry AI Gateway, validated into verification_brief, with fallback to deterministic unless strict mode is on. Execution layer (Lark track)

fake — reliable simulated path for offline demos. getlark_mcp / getlark_cli - scaffolds that describe intended MCP/CLI workflow execution. getlark_live_check - real REST GET /workflows + optional POST /workflows/{id}/invoke. getlark_cli_live - real getlark workflows list subprocess evidence. I wired env-driven modes (PRIMARY_ADAPTER_MODE, PARSER_MODE, FAULT_INJECTION_MODE) so I could show healthy vs degraded runs in the CLI and on GitHub without code changes.

Maintainer UX

Idempotent managed comment with <!-- larkguard:managed -->. CLI summaries with Health=…, workflow selection, invoke status, and issue-driven run artifacts tying proof back to the issue number.

Challenges I ran into

Scope vs. time. I wanted full MCP invoke --wait and per-issue workflow creation, but for a solo hackathon build I had to ship a thin, honest live integration first (list + optional invoke + CLI list) and scaffolds for what’s next.

Naming “Reproduced” honestly. Early versions could imply I reproduced the app bug. I tightened copy and logic so Reproduced means live workflow execution proof, with that qualifier in CLI output and GitHub comments.

Resilience without hiding failures. I needed demos that never die on stage when keys are missing, but judges still need to see degradation. I added explicit health modes, fallback notes, and fault injection so failures are visible, not swallowed.

Sponsor API + demo stability. Live invoke depends on workflow IDs, network, and credentials. I added GETLARK_WORKFLOW_ID, invoke toggles, and tests that don’t require live keys by default.

Solo velocity. Every layer (API, CLI, parser, adapters, comments, tests, README, Devpost assets) was me - so I prioritized a replayable evidence trail over feature breadth.

Accomplishments that I'm proud of

End-to-end evidence-first pipeline from GitHub issue to stored, replayable verification result. Live getlark proof with workflow selection, optional invoke, and wflw_exec_* execution IDs when invoke succeeds. TrueFoundry gateway parser integrated only at the parser layer, with deterministic fallback. Resilience story I can demo on command: parser fallback, adapter fallback, and degraded-both. Idempotent managed GitHub comments - one living verification comment per issue, updated each run. 12 passing tests and a README/demo path judges can follow without guessing what’s live vs scaffolded. As a solo developer, I’m proud I shipped something that is demoable, honest, and extensible — not just a slide-deck agent.

What I learned

Deterministic first made debugging and judging far easier than jumping straight to LLM variability. Separate concerns: parsing (TrueFoundry) vs execution (getlark) vs presentation (GitHub comments) kept failures isolated and fallbacks simple. Honest status labels build more trust than overstating “reproduced.” Adapters + env flags are a practical way to demo sponsor integrations without maintaining multiple codebases. Building for maintainers means optimizing for clarity: evidence artifacts, replay, and one updated comment - not spam.

What's next for LarkGuard

Per-issue dynamic getlark workflows via full MCP tool calls and getlark workflows invoke --wait. Target-app reproduction beyond workflow smoke proof (real repro steps against the app under test). Webhooks to auto-verify on new or updated issues. Hosted deployment so judges and teams can try it without local setup. Deeper auth, database, and multi-repo support for production triage workflows.

Built With

• fastapi
• getlark.ai-(rest-+-cli)
• github-rest-api
• httpx
• pydantic
• pytest
• python
• python-dotenv
• rich-cli
• tenacity
• truefoundry-ai-gateway
• uvicorn