rootsight 0.1.0__py3-none-any.whl

rootsight/__init__.py

@@ -0,0 +1,40 @@
+"""rootsight: a Gymnasium RL environment for incident investigation.
+
+Each episode: an alert fires on a service with one hidden root cause. The agent
+calls diagnostic tools (metrics, deploy history, commit diff, runbook) and then
+submits one of 4 causes or escalates. Reward: +1 correct, -1 wrong, -0.25
+escalate, small cost per tool call, max 8 actions.
+
+How the files connect (top to bottom = dependency order):
+
+  scenarios.py    seeded incident generator; hidden cause + precomputed tool responses
+  tools.py        action registry, ToolAdapter interface, SimulatedTools, Transcript
+  observation.py  Transcript -> 35 features in [0, 1] (never sees the hidden cause)
+  env.py          IncidentEnv(gym.Env): step/reset, rewards, termination vs truncation
+  policies.py     baselines (random, fixed-order, heuristic, supervised, cascade) + DQN wrapper
+  evaluate.py     runs any policy on frozen test fixtures -> JSON/CSV/Markdown
+  train.py        trains DQN (stable-baselines3), picks checkpoint on validation
+  supervised.py   trains classifier baselines to check whether RL is actually needed
+  explain.py      template + local-LLM explanations behind a grounding guardrail; LLM eval
+  agent.py        investigate(alert, tools, policy): the production-style entry point
+  demo.py         replays one incident with every policy, reveals the answer after
+  live.py         LiveTools: same ToolAdapter backed by real Prometheus + git
+  live_scenarios.py  injects real faults into the Docker stack, runs every policy on the alert
+  dashboard.py    local web dashboard (+ dashboard.html): results, training, agent at work,
+                  errors, live incidents, approvals/resources, human feedback
+
+Run from the repo root (Python 3.10+):
+
+  pip install -e ".[rl,dev]"
+  pytest                                                   # 31 checks, ~10s
+  python -m rootsight.train --seed 7                     # ~25s on CPU
+  python -m rootsight.demo --checkpoint artifacts/rl/seed7/best_model.zip --episode-seed 42
+  python -m rootsight.evaluate --split test --checkpoints artifacts/rl/seed7/best_model.zip
+
+Minimal use as a plain Gymnasium env:
+
+  from rootsight.env import IncidentEnv
+  env = IncidentEnv(split="train")
+  obs, info = env.reset(seed=0)
+  obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
+"""