rootcoz 4.4.2__tar.gz → 4.4.4__tar.gz

{rootcoz-4.4.2 → rootcoz-4.4.4}/.pre-commit-config.yaml

@@ -42,9 +42,10 @@ repos:
         exclude: ^docs/
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.22
+    rev: v0.16.0
     hooks:
       - id: ruff
+        args: [--fix]
       - id: ruff-format
 
   - repo: https://github.com/gitleaks/gitleaks
@@ -61,7 +62,7 @@ repos:
           [types-requests, types-PyYAML, types-colorama, types-aiofiles, pydantic, pi-sidecar-client]
 
   - repo: https://github.com/pre-commit/mirrors-eslint
-    rev: v10.7.0
+    rev: v10.8.0
     hooks:
       - id: eslint
         files: \.js$

{rootcoz-4.4.2 → rootcoz-4.4.4}/AGENTS.md

@@ -82,7 +82,8 @@ uvx --with tox-uv tox -e chart      # Helm chart only
 ```text
 src/rootcoz/
   engine/                   # CI-agnostic analysis core
-    core.py                 # Failure grouping, AI CLI orchestration, prompt building,
+    core.py                 # Failure grouping, AI orchestration (per-group with agent
+                            # system_prompt + cross-failure detection), prompt building,
                             # JSON response parsing, deduplication. Has ZERO knowledge
                             # of any specific CI system.
     chat.py                 # Chat engine: workspace, AI session, prompt builder
@@ -99,9 +100,13 @@ src/rootcoz/
   prow_validation.py        # Canonical Prow validators (+ URL helper re-exports for compatibility)
   url_utils.py              # Cross-cutting HTTP(S) URL sanitization (strip userinfo, href)
   main.py                   # FastAPI app, unified POST /analyze endpoint, background tasks
-  models.py                 # Pydantic request/response models
+  xml_enrichment.py          # JUnit XML parsing: extract_all_tests_from_xml (pass/skip/fail),
+                            # extract_failures_from_xml/extract_test_failures wrappers,
+                            # apply_analysis_to_xml, build_enriched_xml
+  models.py                 # Pydantic request/response models (BaseTestEntry, FailedTest, etc.)
   config.py                 # Settings (env vars)
-  storage.py                # SQLite persistence
+  storage.py                # SQLite persistence (includes test_entries table)
+  agents/                    # Built-in pi agents (e.g. test-analyzer) copied to workspace .pi/agents/
   ai_client.py              # AI provider constants and usage recording setup
   sidecar-helper/            # Pi SDK sidecar service (Node.js/TypeScript)
     src/server.ts           # Thin wrapper calling @myk-org/pi-sidecar startSidecar()
@@ -169,7 +174,7 @@ Analyzed repositories can provide project-specific customization files under a `
 
 - **`settings.json`**: Optional non-sensitive analysis settings for the test repo. Validated against the JSON Schema in `src/rootcoz/schemas/rootcoz-settings.schema.json` (Pydantic model `RootcozRepoSettings`). Allowed keys only: `ai_provider`, `ai_model`, `ai_call_timeout`, `max_concurrent_ai_calls`, `peer_ai_configs`, `peer_analysis_max_rounds`, `additional_repos`. No secrets (tokens rejected). Priority for all allowed keys: request → `settings.json` → server. Loaded after the test repo is cloned (`rootcoz_repo_settings.py`).
 - **Prompt files**: `build_resources_section()` and `build_prompt_sections()` in `engine/core.py` scan `<repo>/.rootcoz/` for `ROOTCOZ_PROMPT.md` and `ROOTCOZ_HISTORY_PROMPT.md`. The issue prompt (`ROOTCOZ_ISSUE_PROMPT.md`) is fetched via the GitHub Contents API from `.rootcoz/` in `main.py`.
-- **Pi resources**: After cloning repos (analysis, re-analysis, and chat paths), `.rootcoz/{agents,skills,extensions}/` are copied into `<workspace>/.pi/` via `copy_rootcoz_pi_resources()` so pi's `DefaultResourceLoader` discovers them.
+- **Pi resources**: After cloning repos (analysis, re-analysis, and chat paths), `.rootcoz/{agents,skills,extensions}/` are copied into `<workspace>/.pi/` via `copy_rootcoz_pi_resources()` so pi's `DefaultResourceLoader` discovers them. Built-in agents from `src/rootcoz/agents/` are then copied via `copy_builtin_agents_to_workspace()` — existing user agent files with the same name are NOT overwritten (user agents take precedence). Analysis sessions use tools `["read", "ls", "find", "grep"]` only (no `subagent`); the `test-analyzer` agent file is loaded as `system_prompt`. Chat sessions still include `subagent`.
 - This is a **breaking change** — the previous legacy prompt filenames in the repo root are no longer supported. Only `.rootcoz/` is recognized.
 
 ### AI Tool Access (MANDATORY)
@@ -212,7 +217,7 @@ AI chat sessions MUST use restricted tool sets — **never give bash access**.
 - **Data access**: Use HTTP-backed custom tools via pi-sidecar (pi-sidecar ≥4.2.0)
 - **Never**: `bash`, `exec`, `write`, `edit` — the AI must not execute arbitrary commands or modify files
 - Custom tools define exactly which API endpoints the AI can call — nothing else is reachable
-- Per-job chat tools: `get_job_result`, `get_job_comments`, `search_jira`, `get_jira_issue`, `search_github_issues`, `get_github_issue` (conditional on user credentials)
+- Per-job chat tools: `get_job_result`, `get_job_comments`, `get_job_tests`, `search_jira`, `get_jira_issue`, `search_github_issues`, `get_github_issue` (conditional on user credentials)
 - Admin chat tools: `db_schema`, `db_query` (read-only SQL against the database), `get_report_totals`, `get_classification_overrides`, `get_issues_created` (pre-built analytics reports), `save_report` (generate downloadable HTML report)
 
 ### CLI Parity
@@ -244,11 +249,19 @@ When not configured, error messages are role-aware: admins are pointed to Server
 
 `rootcoz-ai` is the reserved system identity for all AI-originated actions (auto-review, classification). The identity string is defined as `AI_SYSTEM_USERNAME` in `storage.py` — all code must use this constant instead of hardcoding the string. It is blocked from user registration. The `POST /history/classify` endpoint uses `source="ai"` in the request body to identify AI callers, and stores `created_by = "rootcoz-ai"` for attribution. A backend guard prevents AI from overriding user classifications.
 
+### Test Entries & Zero-Failure Fast Path
+
+All test outcomes (passed, skipped, failed) are stored in the `test_entries` table with `child_job_name`/`child_build_number` scoping. Counts are cached in `result_json` for dashboard display. The `BaseTestEntry` model (base class of `FailedTest`) provides the shared `test_name`/`duration`/`status` fields.
+
+- **Paginated API**: `GET /api/results/{job_id}/tests?status=passed&status=skipped&offset=0&limit=50` (viewer+ auth, CLI: `rootcoz results tests`)
+- **Zero-failure fast path**: When `CISourceResult.skip_analysis=True` (e.g. Jenkins SUCCESS, file with no failures), the pipeline skips AI analysis, repo cloning, and workspace setup. Test entries are still saved and counts cached. Metadata assignment, SSE notifications, and auth enforcement still apply.
+- **Jenkins FAILURE/UNSTABLE/ABORTED with empty test report**: NOT fast path — console-only analysis runs (preserves existing behavior).
+
 ### Failure Deduplication
 
 When multiple tests fail with the same error:
 1. Failures are grouped by error signature (SHA-256 hash of normalized error + stack trace)
-2. Only one AI CLI call per unique error type
+2. One `call_ai_once` per unique error with `test-analyzer` agent as system_prompt (cross-failure patterns detected in a final pass)
 3. Analysis is applied to all failures with matching signature
 4. Signatures are normalized before hashing (timestamps, UUIDs, pod name suffixes, build numbers stripped)
 

{rootcoz-4.4.2 → rootcoz-4.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rootcoz
-Version: 4.4.2
+Version: 4.4.4
 Summary: AI-powered root cause analysis for CI/CD test failures
 License: Apache-2.0
 License-File: LICENSE

{rootcoz-4.4.2 → rootcoz-4.4.4}/README.md

@@ -67,10 +67,129 @@ Jobs can omit `gcs_prefix`; RootCoz auto-resolves it via prowjob.json or the Pro
 
 - **AI-Powered Failure Analysis** — Classifies test failures as code issues or product bugs
 - **Multi-CI Support** — Analyzes builds from Jenkins, Prow (GCS artifacts), or raw JUnit XML input with a unified pipeline
+- **Full Test Visibility** — Stores and displays all test outcomes (passed, skipped, failed) from CI sources. Zero-failure jobs are handled as a fast path with no AI overhead.
 - **AI Token Usage Tracking** — Track token consumption, costs, and duration for all AI CLI calls. Admin dashboard shows usage by provider/model/time period with CSV export.
 - **Public OpenAPI** — `/openapi.json`, `/docs`, and `/redoc` are available without authentication
 - **Sparse result fields** — `GET /results/{job_id}?fields=status,result.summary,...` returns only allowlisted paths (full values). Discover paths via `GET /api/results/fields` or `rootcoz results fields`
 - **Reports access flag** — Non-admins need `can_view_reports` (admin grant / `rootcoz admin users set-can-view-reports`) to call `/api/reports/*` and `rootcoz reports`
+- **Analyze-time labels** — Pass `--label` / `-l` on `rootcoz analyze` (or `labels` in the API / config.toml) to merge job metadata labels at submit time
+
+## Custom Analysis Agents
+
+rootcoz supports user-provided analysis agents that extend or customize the AI failure analysis pipeline. Agents are defined as Markdown files and are automatically discovered and executed during analysis.
+
+### How It Works
+
+1. Place agent `.md` files in `.rootcoz/agents/` in your analyzed repository
+2. When rootcoz clones the repo for analysis, it copies `.rootcoz/agents/` to the workspace `.pi/agents/`
+3. The AI orchestrator loads the built-in `test-analyzer` agent body as the `system_prompt` for per-group AI calls (read via the `read` tool, not dispatched as a subagent)
+4. Other project agents (non-`test-analyzer`) are read via the STEP 0 hard gate before analysis begins — the AI reads each agent file using the `read` tool to incorporate their guidance
+5. To override the built-in analyzer, name your agent `test-analyzer` — user agents take precedence
+
+### Creating an Agent
+
+Create a Markdown file in `.rootcoz/agents/` with YAML frontmatter:
+
+```markdown
+---
+name: my-analyzer
+description: Brief description of what this agent does.
+tools:
+  - read
+  - ls
+  - find
+  - grep
+---
+
+# My Custom Analyzer
+
+Your agent instructions here...
+```
+
+### Requirements
+
+- **Name**: Must match `^[A-Za-z0-9._-]{1,64}$` — prefer frontmatter `name:`; filename stem is used as fallback when it matches the same regex
+- **Format**: Markdown file with YAML frontmatter. `name:` is preferred (filename stem is the fallback when it matches the safe regex). `description:` and `tools:` are recommended — see below
+- **Tools**: Strongly recommended — list `tools: [read, ls, find, grep]` in frontmatter to restrict available tools. Without this, pi may grant default builtins including `bash`
+- **Discovery**: Names that don't match the regex are silently skipped (not sanitized/rewritten)
+- **Response** (test-analyzer or overrides): Return a valid JSON object matching the `AnalysisDetail` schema. Other STEP 0 agents return free-form text that gets incorporated into the analysis details:
+
+```json
+{
+  "classification": "PRODUCT BUG | CODE ISSUE | INFRASTRUCTURE",
+  "pattern": "NEW | REGRESSION | FLAKY | INTERMITTENT | KNOWN_BUG | PERSISTENT",
+  "affected_tests": ["test_name_1"],
+  "details": "Detailed analysis text",
+  "artifacts_evidence": "Evidence from build artifacts"
+}
+```
+
+For `CODE ISSUE`, include a `code_fix` object. For `PRODUCT BUG`, include a `product_bug_report` object.
+
+### Example Agent
+
+```markdown
+---
+name: k8s-analyzer
+description: Analyzes Kubernetes-related test failures including pod scheduling, networking, storage, and RBAC issues.
+tools:
+  - read
+  - ls
+  - find
+  - grep
+---
+
+# Kubernetes Failure Analyzer
+
+You specialize in analyzing Kubernetes-related test failures.
+
+## Instructions
+
+1. Read the failure details file provided by the orchestrator
+2. Look for Kubernetes-specific errors (pod scheduling, resource limits, network policies)
+3. Check build artifacts for kubectl logs, pod descriptions, and event dumps
+4. Return your findings as free-form text (STEP 0 advisory agents are not per-group classifiers)
+
+## Focus Areas
+
+- Pod scheduling failures (Insufficient CPU/memory, node affinity)
+- Network connectivity issues (DNS resolution, service endpoints)
+- Storage provisioning failures (PVC binding, StorageClass issues)
+- RBAC and security context problems
+```
+
+### Agent Discovery
+
+- Agents are discovered from `.rootcoz/agents/*.md` files
+- The `name` field in frontmatter is preferred; filename stem is used as fallback
+- User agents take precedence over built-in agents with the same name
+- Agent names are validated against `^[A-Za-z0-9._-]{1,64}$` — non-matching names/stems are silently skipped
+
+### Built-in Agents
+
+rootcoz ships a built-in `test-analyzer` agent that handles the core failure analysis. It is automatically copied to the workspace and used by the orchestrator. User agents with the same name override it.
+
+### Cross-Failure Patterns
+
+When using orchestrated analysis (default, non-peer mode), the orchestrator AI sees ALL failure groups and can detect cross-failure patterns — correlations impossible with per-group isolation.
+
+Patterns appear in the API response as `cross_failure_patterns` on the job result:
+
+```json
+{
+  "cross_failure_patterns": [
+    {
+      "pattern": "15 failures share the same NFS mount timeout",
+      "affected_tests": ["test_a", "test_b"],
+      "suggested_root_cause": "NFS server infrastructure issue"
+    }
+  ]
+}
+```
+
+On `GET /results/{job_id}`, the field lives at `result.cross_failure_patterns`. The frontend displays these patterns on the job report page between the summary and individual failure cards.
+
+**Note:** Cross-failure patterns are only detected in orchestrated mode. When `peer_ai_configs` is set, the legacy per-group analysis path is used and no cross-failure patterns are generated.
 
 ## CLI
 
@@ -80,6 +199,7 @@ export ROOTCOZ_SERVER=http://localhost:8000
 
 rootcoz health
 rootcoz analyze --job-name my-job --build-number 42
+rootcoz analyze --job-name my-job --build-number 42 --label Nightly -l CNV
 rootcoz analyze --source prow \
   --job-name periodic-ci-e2e-aws \
   --build-number 1234567890 \
@@ -87,6 +207,7 @@ rootcoz analyze --source prow \
   --gcs-bucket test-platform-results \
   --gcs-prefix logs/periodic-ci-e2e-aws/1234567890
 rootcoz results list
+rootcoz results tests <job_id>         # List test entries (passed/skipped/failed)
 rootcoz admin token-usage              # Summary dashboard
 rootcoz admin token-usage --group-by model  # Grouped breakdown
 rootcoz admin token-usage --job-id <uuid>   # Per-job usage

{rootcoz-4.4.2 → rootcoz-4.4.4}/config.example.toml

@@ -41,6 +41,9 @@ enable_jira = true
 # GitHub
 github_token = "ghp_your-github-token"
 
+# Job metadata labels (comma-separated); merged into job_metadata.labels on analyze
+# labels = "Nightly,CNV"
+
 [servers.dev]
 url = "http://localhost:8000"
 username = "your-username"

rootcoz-4.4.2/docs/deployment-recipes.html → rootcoz-4.4.4/docs/api-reference.html

@@ -3,8 +3,8 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Deployment Recipes - rootcoz</title>
-    <meta name="description" content="Automatically diagnose CI/CD test failures with AI and get actionable root cause analysis in seconds">
+    <title>API Endpoint Reference - rootcoz</title>
+    <meta name="description" content="Understand failing CI runs, collaborate on fixes, and create follow-up issues faster.">
     <link rel="stylesheet" href="assets/style.css">
     <script>try{var t=localStorage.getItem('theme');if(t==='dark')document.documentElement.setAttribute('data-theme','dark')}catch(e){}</script>
     <link rel="alternate" type="text/plain" title="LLM Documentation Index" href="llms.txt">
@@ -14,7 +14,7 @@
     <aside class="sidebar" id="sidebar">
         <div class="sidebar-header">
             <a href="index.html" class="sidebar-logo">rootcoz</a>
-            <p class="sidebar-tagline">Automatically diagnose CI/CD test failures with AI and get actionable root cause analysis in seconds</p>
+            <p class="sidebar-tagline">Understand failing CI runs, collaborate on fixes, and create follow-up issues faster.</p>
         </div>
 
         <div class="sidebar-search">
@@ -35,13 +35,6 @@
                         </a>
                     </li>
                     
-                    <li>
-                        <a href="cli-setup.html"
-                           class="nav-link">
-                            Setting Up the CLI
-                        </a>
-                    </li>
-                    
                 </ul>
             </div>
             
@@ -50,65 +43,72 @@
                 <ul class="nav-group-pages">
                     
                     <li>
-                        <a href="analyzing-failures.html"
+                        <a href="submit-analyses.html"
+                           class="nav-link">
+                            Submitting Analyses
+                        </a>
+                    </li>
+                    
+                    <li>
+                        <a href="configure-analysis-context.html"
                            class="nav-link">
-                            Analyzing Test Failures
+                            Configuring Analysis Context
                         </a>
                     </li>
                     
                     <li>
-                        <a href="reviewing-results.html"
+                        <a href="track-analysis-progress.html"
                            class="nav-link">
-                            Reviewing Analysis Results
+                            Tracking Analysis Progress
                         </a>
                     </li>
                     
                     <li>
-                        <a href="chatting-with-ai.html"
+                        <a href="review-and-classify-failures.html"
                            class="nav-link">
-                            Chatting with AI About Failures
+                            Reviewing and Classifying Failures
                         </a>
                     </li>
                     
                     <li>
-                        <a href="creating-issues.html"
+                        <a href="collaborate-on-results.html"
                            class="nav-link">
-                            Creating Bug Reports from Analysis
+                            Collaborating on Results
                         </a>
                     </li>
                     
                     <li>
-                        <a href="configuring-integrations.html"
+                        <a href="manage-account-and-notifications.html"
                            class="nav-link">
-                            Configuring Integrations
+                            Managing Your Account and Notifications
                         </a>
                     </li>
                     
                     <li>
-                        <a href="peer-analysis.html"
+                        <a href="create-follow-up-issues-and-push-results.html"
                            class="nav-link">
-                            Using Multi-AI Peer Analysis
+                            Creating Follow-Up Issues and Pushing Results
                         </a>
                     </li>
                     
                     <li>
-                        <a href="managing-users.html"
+                        <a href="explore-history-and-reports.html"
                            class="nav-link">
-                            Managing Users and Roles
+                            Exploring History and Reports
                         </a>
                     </li>
                     
                     <li>
-                        <a href="tracking-history.html"
+                        <a href="manage-users-and-server-settings.html"
                            class="nav-link">
-                            Tracking Failure History and Reports
+                            Managing Users and Server Settings
                         </a>
                     </li>
                     
                     <li>
-                        <a href="pytest-integration.html"
+                        <a href="use-server-chat-for-cross-job-analysis.html"
                            class="nav-link">
-                            Integrating with pytest
+                            Use Server Chat for Cross-Job Analysis
                         </a>
                     </li>
                     
@@ -120,16 +120,16 @@
                 <ul class="nav-group-pages">
                     
                     <li>
-                        <a href="deployment-recipes.html"
-                           class="nav-link active" aria-current="page">
-                            Deployment Recipes
+                        <a href="automate-common-tasks-with-the-cli.html"
+                           class="nav-link">
+                            Automating Common Tasks with the CLI
                         </a>
                     </li>
                     
                     <li>
-                        <a href="cli-recipes.html"
+                        <a href="deploy-rootcoz.html"
                            class="nav-link">
-                            CLI Recipes
+                            Deploying RootCoz
                         </a>
                     </li>
                     
@@ -142,8 +142,8 @@
                     
                     <li>
                         <a href="api-reference.html"
-                           class="nav-link">
-                            REST API Reference
+                           class="nav-link active" aria-current="page">
+                            API Endpoint Reference
                         </a>
                     </li>
                     
@@ -155,9 +155,9 @@
                     </li>
                     
                     <li>
-                        <a href="environment-variables.html"
+                        <a href="configuration-reference.html"
                            class="nav-link">
-                            Environment Variables and Configuration
+                            Configuration Reference
                         </a>
                     </li>
                     
@@ -210,28 +210,21 @@
                          converted to HTML server-side by the markdown library, not
                          user-supplied input. XSS risk is minimal and accepted since
                          the AI generates the content, not end users. -->
-                    <p>Let me explore the repository structure and key files to write accurate documentation.Now let me explore the key deployment-related files:</p>
-<h2 id="related-pages">Related Pages</h2>
-<ul>
-<li><a href="quickstart.html">Quickstart</a></li>
-<li><a href="environment-variables.html">Environment Variables and Configuration</a></li>
-<li><a href="configuring-integrations.html">Configuring Integrations</a></li>
-<li><a href="managing-users.html">Managing Users and Roles</a></li>
-<li><a href="cli-setup.html">Setting Up the CLI</a></li>
-</ul>
+                    <h1 id="api-endpoint-reference">API Endpoint Reference</h1>
+<p><em>Documentation generation failed. Please re-run.</em></p>
                 </div>
             </article>
             <nav class="page-nav">
                 
-                <a href="pytest-integration.html" class="page-nav-link page-nav-prev">
+                <a href="deploy-rootcoz.html" class="page-nav-link page-nav-prev">
                     <span class="page-nav-label">Previous</span>
-                    <span class="page-nav-title">Integrating with pytest</span>
+                    <span class="page-nav-title">Deploying RootCoz</span>
                 </a>
                 
                 
-                <a href="cli-recipes.html" class="page-nav-link page-nav-next">
+                <a href="cli-reference.html" class="page-nav-link page-nav-next">
                     <span class="page-nav-label">Next</span>
-                    <span class="page-nav-title">CLI Recipes</span>
+                    <span class="page-nav-title">CLI Command Reference</span>
                 </a>
                 
             </nav>
@@ -240,9 +233,7 @@
                 <div class="toc-container">
                     <h3>On this page</h3>
                     <div class="toc">
-<ul>
-<li><a href="#related-pages">Related Pages</a></li>
-</ul>
+<ul></ul>
 </div>
 
                 </div>
@@ -253,7 +244,7 @@
 
         <footer class="page-footer">
             
-            <span class="footer-version">Generated from version 4.2.0</span>
+            <span class="footer-version">Generated from version 4.4.2</span>
             <span class="footer-sep">&middot;</span>
             
             Generated with <a href="https://github.com/myk-org/docsfy" target="_blank" rel="noopener">docs<span class="brand-accent">fy</span></a>

rootcoz-4.4.4/docs/api-reference.md

@@ -0,0 +1,3 @@
+# API Endpoint Reference
+
+*Documentation generation failed. Please re-run.*