MatchOps Commander

AI incident command for live-event operations.

MatchOps Commander detects operational drift during high-pressure live events, executes response work through GitLab, and preserves a visible audit trail — all deterministic, auditable, no LLM in the critical path.

Built for the Google Cloud Rapid Agent Hackathon (GitLab track).

What It Does

Live event operations depend on WhatsApp threads, spreadsheets, and verbal escalation. Risks emerge before incidents are declared, but the people responsible often see them too late.

MatchOps Commander watches live operational signals, detects when things drift off baseline, decides what to do, and maps actions to GitLab execution plans — with idempotency keys and a full audit trail.

Architecture

Feed (OpsEvent[]) → Drift (DriftState) → Decision (ActionIntent[]) → Execution (ExecutionPlan[])

Phase	Module	What It Does
Feed	src/events/	Simulated operational event stream with configurable overrides
Drift	src/drift/	Threshold-based drift detection with 4 rules + critical escalation
Decision	src/policy/	Maps drift state to action intents with confidence scoring
Execution	src/execution/	Maps action intents to GitLab execution plans with idempotency keys
Demo	src/demo/	Interactive terminal-style UI with scenario presets and live pipeline

Core principles:

• All pure functions — deterministic, no hidden state
• Same inputs always produce same outputs
• LLM explains decisions but does not own authoritative scoring or triggers
• Every step produces a human-readable audit entry

Tech Stack

• Runtime: TypeScript on Node.js
• AI Layer: Gemini (explanation only — not in control path)
• Execution: GitLab MCP (issues, pipelines)
• Hosting: Google Cloud (Agent Builder / Cloud Run)
• Testing: Node.js built-in test runner

Quick Start

npm install
npm test          # 46 tests
npm run check     # typecheck
npm run demo      # interactive demo on http://localhost:3001
npx adk web       # interactive AI agent chat UI

Demo

The interactive demo lets you:

1. Select scenario presets — Nominal, Warning, or Critical
2. Adjust operational sliders — transport delays, gate pressure, staffing gaps, vendor readiness
3. Watch the pipeline — see drift detection, action decisions, and execution plans update in real time
4. Review the audit trail — every decision is explained and traceable

Project Structure

src/
├── agent/          # ADK agent + tools (MCPToolset, FunctionTool)
├── demo/           # Interactive UI + HTTP server
├── drift/          # Drift detection rules and state machine
├── events/         # Event schema and simulated feed emitter
├── execution/      # Action intent → GitLab execution plan mapping
├── gemini/         # Gemini explanation layer (AI Studio API)
├── gitlab/         # GitLab REST API adapter (issues, pipelines)
└── policy/         # Drift state → action intent decision policy

tests/              # 46 tests across all modules

How It Works

1. Feed: Emits a stream of operational events (transport, gates, staffing, vendors) with configurable values
2. Drift: Compares each event against threshold rules and classifies state as none, warning, or critical
3. Decision: Maps drift state to action intents (MONITOR, CREATE_INCIDENT, ESCALATE) with confidence scores
4. Execution: Converts action intents into GitLab execution plans with deterministic idempotency keys

Hackathon Integrations

Gemini Integration

MatchOps Commander uses Gemini (gemini-2.0-flash) via the AI Studio API to provide natural language explanations of operational drift. The LLM is not in the critical path — it only explains deterministic pipeline results:

• Drift Analysis: Why the system entered a warning/critical state
• Action Rationale: Why specific execution plans were chosen
• Risk Assessment: Potential operational failures
• Recommended Next Steps: Clear actions for operators

GitLab MCP Adapter

Execution plans generated by the policy engine are mapped to real GitLab REST API calls:

• CREATE_INCIDENT → Creates an issue in the target project
• ESCALATE → Triggers a pipeline execution
• MONITOR → Creates an issue for ongoing monitoring (all 3 actions execute real GitLab API calls)

Agent Builder Architecture

The project is built using the official @google/adk. The MatchOpsAgent (in src/agent/) exposes the pipeline functions as tools (runPipelineTool) and integrates directly with the GitLab MCP server via MCPToolset. This gives judges a live interactive agent (npx adk web) and full hackathon compliance.

Deployment

A Dockerfile and railway.json are included for zero-config deployment to Railway or any standard Docker hosting environment. A .gitlab-ci.yml is also provided for automated deployment to Railway via GitLab CI/CD.

Environment Variables

To run the full pipeline including Gemini and GitLab MCP tools, set the following variables in a .env file or in your hosting provider's dashboard:

• GEMINI_API_KEY or GOOGLE_API_KEY (for Gemini API)
• GITLAB_TOKEN (for real issue/pipeline creation)
• GITLAB_PROJECT_ID (the numeric ID of your target GitLab project)
• GITLAB_PERSONAL_ACCESS_TOKEN (used by the MCP server, mapped to the same token)

How to Deploy (Railway)

1. Connect your GitLab repository to Railway (New Project → Deploy from GitLab).
2. Set the environment variables listed above in the Railway dashboard.
3. Configure the RAILWAY_SERVICE_ID variable in your GitLab project settings (Settings → CI/CD → Variables).
4. Run the CI/CD pipeline on the main branch to trigger a deploy.

License

MIT