refactor: modularize agent toolsets and improve documentation

.env.example

@@ -0,0 +1,63 @@
+# Ares SOC Investigation Agent - Environment Variables
+# Copy this file to .env and fill in your values
+
+# ============================================================================
+# Grafana Configuration
+# ============================================================================
+
+# Grafana service account token for API access
+# Note: GRAFANA_API_KEY is deprecated, use GRAFANA_SERVICE_ACCOUNT_TOKEN instead
+GRAFANA_SERVICE_ACCOUNT_TOKEN=your-grafana-token-here  # pragma: allowlist secret
+
+# Grafana URL (can also be set via --grafana-url)
+GRAFANA_URL=https://grafana.dev.plundr.ai
+
+# ============================================================================
+# LLM Provider API Keys
+# ============================================================================
+
+# Anthropic API key for Claude models (recommended)
+ANTHROPIC_API_KEY=your-anthropic-api-key-here  # pragma: allowlist secret
+
+# OpenAI API key (alternative to Anthropic)
+# OPENAI_API_KEY=your-openai-api-key-here  # pragma: allowlist secret
+
+# ============================================================================
+# Dreadnode Platform Configuration
+# ============================================================================
+
+# Dreadnode Platform API token for observability and tracing
+DREADNODE_API_KEY=your-dreadnode-api-key-here  # pragma: allowlist secret
+
+# Dreadnode Platform URL (default: https://platform.dev.plundr.ai/)
+# DREADNODE_SERVER=https://platform.dev.plundr.ai/
+
+# Dreadnode organization name (default: ares)
+# DREADNODE_ORGANIZATION=ares
+
+# Dreadnode workspace name (default: ares-protocol)
+# DREADNODE_WORKSPACE=ares-protocol
+
+# Dreadnode project name (default: ares-soc)
+# DREADNODE_PROJECT=ares-soc
+
+# ============================================================================
+# Note: Loki and Prometheus queries are handled via Grafana MCP
+# No separate URLs needed - queries go through the Grafana MCP server
+# ============================================================================
+
+# ============================================================================
+# Investigation Configuration
+# ============================================================================
+
+# LLM model to use (default: claude-sonnet-4-20250514)
+# MODEL=claude-sonnet-4-20250514
+
+# Maximum agent steps per investigation (default: 150)
+# MAX_STEPS=150
+
+# Seconds between alert polling cycles (default: 30)
+# POLL_INTERVAL=30
+
+# Directory for markdown investigation reports (default: reports)
+# REPORT_DIR=./reports

.github/workflows/tests.yaml

@@ -30,7 +30,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - name: Set up git repository
@@ -45,7 +45,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install pytest pytest-cov ruff
+          pip install pytest pytest-cov pytest-asyncio ruff
           pip install -e .
 
       - name: Lint with ruff

.gitignore

@@ -1,5 +1,11 @@
 # Testing code
 notebooks/
+test-alerts/
+
+# Project-specific ignores
+TODO
+.tool-versions
+reports/
 
 # Custom parquet storage
 *.parquet

.hooks/check_pinned_hash_dependencies.py

@@ -2,11 +2,10 @@
 import re
 import sys
 from pathlib import Path
-from typing import List, Tuple
 
 
 class GitHubActionChecker:
-    def __init__(self):
+    def __init__(self) -> None:
         # Pattern for actions with SHA-1 hashes (pinned)
         self.pinned_pattern = re.compile(r"uses:\s+([^@\s]+)@([a-f0-9]{40})")
 
@@ -30,9 +29,9 @@ def format_terminal_link(self, file_path: str, line_number: int) -> str:
         """
         return f"{file_path}:{line_number}"
 
-    def get_line_numbers(self, content: str, pattern: re.Pattern) -> List[Tuple[str, int]]:
+    def get_line_numbers(self, content: str, pattern: re.Pattern[str]) -> list[tuple[str, int]]:
         """Find matches with their line numbers."""
-        matches: List[Tuple[str, int]] = []
+        matches: list[tuple[str, int]] = []
         matches.extend(
             (match.group(0), i)
             for i, line in enumerate(content.splitlines(), 1)
@@ -107,7 +106,7 @@ def check_file(self, file_path: str) -> bool:
         return not has_errors
 
 
-def main():
+def main() -> None:
     checker = GitHubActionChecker()
     files_to_check = sys.argv[1:]
 

.hooks/generate_pr_description.py

@@ -19,7 +19,7 @@
 )
 
 
-@rg.prompt
+@rg.prompt  # type: ignore[untyped-decorator]
 def generate_pr_description(diff: str) -> t.Annotated[str, rg.Ctx("markdown")]:  # type: ignore[empty-body]
     """
     Analyze the provided git diff and create a PR description in markdown format.