AIOps

Imported from neuron42/AIOps (AGENTS.md). Install upstream with npx skills add neuron42/AIOps. Copyright stays with the author.

AIOps Agent Guide

This file is for AI coding agents working on the AIOps project. It assumes no prior knowledge of the codebase.

Project overview

AIOps is an AI-powered operations and maintenance platform. The goal is to let operators ask natural-language diagnostic questions ("What incidents are open in Jira for the production cluster?") and get streamed, auditable answers pulled from dashboards and ticketing systems.

Key ideas:

• Pluggable scrapers retrieve ops data. Each scraper exposes self-describing metadata and a Pydantic parameter schema.
• Playwright is used only for initial SSO login/session bootstrap. After login, all data retrieval is pure HTTP API calls.
• Operator session delegation: operators upload session cookies/tokens once. The centralized runner stores them and calls APIs on the operator's behalf.
• Agent reasoning is streamed to the operator as a visible chain of PLAN → ACT → OBSERVE → REFLECT loops.
• Raw data is preserved alongside the reasoning chain for auditability.

Technology stack

• Language: Python 3.13 (requires Python >=3.11)
• Package manager / build: uv with pyproject.toml; build backend is hatchling
• Web framework: FastAPI + Uvicorn
• HTTP client: httpx
• Browser automation: playwright
• LLM gateway: litellm
• Settings/config: pydantic-settings
• Data validation / schemas: Pydantic v2
• Embeddings / vector search: chromadb
• CLI / rich output: rich
• Parsing: beautifulsoup4, lxml
• Token counting: tiktoken

Development tools:

• pytest + pytest-asyncio + pytest-cov
• ruff (linting, import sorting, formatting)
• mypy (strict mode)
• pre-commit

Project structure

C:/Users/neuro/Documents/AIOps
├── src/aiops/                 # Main package
│   ├── agent/                 # Agent lifecycle (planner, executor, reasoning trace)
│   ├── api/                   # FastAPI layer
│   │   ├── auth/              # API key provisioning / validation
│   │   ├── queries/           # Streaming query endpoints (SSE)
│   │   ├── scrapers/          # Scraper registration / listing
│   │   └── sessions/          # Session token management
│   ├── auth/                  # Session manager, refresh worker, base auth module
│   ├── cli/                   # Admin CLI (operator API key management)
│   ├── core/                  # AgentRuntime, state machine, events
│   ├── scrapers/              # Pluggable scrapers
│   │   └── jira/              # Jira scraper + auth + params
│   ├── telemetry/             # Raw telemetry store + query engine (grep/jq)
│   └── tools/                 # Tool schema + tool registry for the agent
├── tests/                     # Unit tests mirroring src/ structure
├── docs/adr/                  # Architecture Decision Records
├── docs/agents/               # Agent-specific conventions (issue tracker, triage)
├── CONTEXT.md                 # Domain glossary and agent lifecycle
├── pyproject.toml             # Project metadata, dependencies, tool config
└── uv.lock                    # Locked dependency tree

Main modules

src/aiops/agent/

The reasoning loop.

• state_machine_agent.py: main entry point. Drives the agent through PLANNING → ACTING → OBSERVING → REFLECTING → DONE.
• planner.py / llm_planner.py: plan generation (currently a placeholder in Planner, with LLMPlanner wired via litellm).
• executor.py: executes planned steps against the tool registry.
• reasoning_trace.py: single module holding plan, ReAct steps, critiques, and artifact references for a query. The planner reads it; the executor/appender writes to it.
• planner_config.py: Pydantic settings for the planner.

src/aiops/api/

HTTP interface. main.py exposes create_app() and the Uvicorn entry point.

• auth/: API key provisioning (POST /keys/{operator_id}), validation via X-API-Key header.
• queries/: submit streaming diagnostic queries via Server-Sent Events, list/query metadata, fetch artifacts.
• scrapers/: list scrapers and register new ones dynamically.
• sessions/: upload/refresh/revoke session tokens for data sources.
• models.py: shared Pydantic request/response models.

src/aiops/auth/

• base.py: BaseAuthModule / AuthConfig — credentials are injected, never hardcoded.
• session_manager.py: in-memory token store keyed by {operator_id}:{source_name}.
• refresh_worker.py: background worker that refreshes tokens.

src/aiops/core/

• agent_runtime.py: central coordination of agent, scrapers, telemetry, and tools.
• state_machine.py: explicit agent state machine.
• events.py: event types streamed during agent execution.

src/aiops/scrapers/

• base.py: BaseScraper abstract class + ScraperMetadata.
• registry.py: ScraperRegistry — discover scrapers, export tool definitions.
• jira/: reference implementation using the Jira REST API v3.

src/aiops/telemetry/

• store.py: TelemetryStore, QueryStore, ScrapedDataset, RawRecord. Stores raw data verbatim for auditability. Currently in-memory.
• query_engine.py: QueryEngine runs grep/regex and jq-like filters over raw telemetry.

src/aiops/tools/

• schema.py: ToolSchema (Pydantic base) and Tool wrapper with automatic JSON Schema export for LLM function calling.
• registry.py: ToolRouter for registering callable tools.

Build and run commands

Install dependencies (uses uv):

uv sync

Run the FastAPI server:

uv run python -m aiops.api.main

Or with explicit env:

LOG_LEVEL=info PLANNER_PROVIDER=anthropic PLANNER_MODEL=... PLANNER_API_KEY=... uv run python -m aiops.api.main

The server binds to 0.0.0.0:8000 by default. OpenAPI docs are at /docs.

Admin CLI (operator API keys):

uv run python -m aiops.cli.admin provision alice@company.com
uv run python -m aiops.cli.admin list
uv run python -m aiops.cli.admin revoke alice@company.com

Test commands

Run the full test suite:

uv run pytest

Run with coverage:

uv run pytest --cov=src/aiops --cov-report=term-missing

Run a single test file:

uv run pytest tests/unit/scrapers/jira/test_scraper.py

Linting and type checking

uv run ruff check .
uv run ruff format .
uv run mypy src

ruff is configured in pyproject.toml:

• line length: 100
• target Python: 3.11
• enabled rules: E, F, I, N, W, B, C4, UP
• tests/** ignores E402 because tests bootstrap sys.path before importing.

mypy runs in strict mode targeting Python 3.13.

Code style guidelines

• Use from __future__ import annotations in new modules.
• Prefer modern type hints (list[str], str | None).
• Use Pydantic v2 models for all external interfaces and schemas.
• Keep scrapers raw: do not pre-process or summarize data inside a scraper. Return exact API responses so the agent can grep/jq over them.
• Credentials are injected via auth config; never hardcode secrets.
• Use datetime.utcnow() for timestamps (current convention; note that this is deprecated in newer Pythons — do not change existing code unless asked).
• Module-level docstrings should explain the file's purpose and any env vars.
• Keep API routers focused: one router per resource group under src/aiops/api/.

Testing conventions

• Tests live in tests/unit/ and mirror the src/aiops/ package structure.
• Test files are named test_<module>.py.
• Tests bootstrap sys.path to include src/ before imports (hence the E402 ignore).
• pytest-asyncio is enabled with asyncio_mode = "auto".
• Unit tests should not require real credentials or network access; mock HTTP and Playwright calls.

Security considerations

• API keys: provisioned via admin CLI or POST /keys/{operator_id}. The plaintext key is shown exactly once; only its SHA-256 hash is stored.
• Session tokens: stored in SessionManager (currently in-memory). A production deployment must replace this with encrypted-at-rest storage (PostgreSQL + KMS/SOPS).
• No hardcoded secrets: auth modules receive credentials through config objects or uploaded session payloads.
• CORS: create_app() allows all origins (["*"]) with credentials. Tighten this for production deployments.
• Scraper registration: POST /scrapers/register dynamically imports a module path. This is powerful; restrict it to admin callers in production.
• Subprocess: QueryEngine.run_jq shells out to jq with a timeout. Validate or sandbox agent-generated queries if exposing to untrusted inputs.

Deployment notes

• The app is a standard ASGI app: aiops.api.main:create_app.
• Default Uvicorn command (with reload in debug mode) is in src/aiops/api/main.py.
• A background token refresh worker starts automatically unless WORKER_ENABLED=false is set.
• Module-level singleton registries in queries/routes.py mean each worker process has its own registry in multi-worker deployments. Use a single worker or a shared store (Redis) for production horizontal scaling.
• No container config is present yet; deploy with Uvicorn/Gunicorn as usual.

Domain documentation

Read before making domain changes:

• CONTEXT.md: domain glossary and agent lifecycle state machine.
• docs/adr/: architecture decision records, especially when touching core orchestration, auth, scrapers, planner, or the API layer.

Agent skills

Issue tracker

Issues live as local markdown files under .scratch/. See docs/agents/issue-tracker.md.

Triage labels

Uses the default five-role triage vocabulary. See docs/agents/triage-labels.md.

Domain docs

Single-context: one CONTEXT.md + docs/adr/ at the repo root. See docs/agents/domain.md.