ci-log-intelligence 0.1.0__py3-none-any.whl

ci_log_intelligence/__init__.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .ci_analysis import analyze_ci_url
+from .ingestion import ingest_log
+from .models import ReductionResult
+from .parsing import parse_log
+from .reducer import reduce_parsed_lines
+from .storage import StorageBackend, create_storage_backend
+from .summarizer import summarize_reduction_result
+from .utils.logging import get_structured_logger
+from .utils.metrics import MetricsCollector, measure_stage
+
+__all__ = [
+    "analyze_log",
+    "analyze_ci_url",
+    "ReductionResult",
+]
+
+
+def analyze_log(
+    log: str,
+    storage_backend: Optional[StorageBackend] = None,
+    spill_threshold_bytes: int = 5_000_000,
+    metrics: Optional[MetricsCollector] = None,
+) -> ReductionResult:
+    logger = get_structured_logger("ci_log_intelligence")
+    collector = metrics or MetricsCollector()
+    backend = storage_backend or create_storage_backend(
+        byte_size=len(log.encode("utf-8")),
+        spill_threshold_bytes=spill_threshold_bytes,
+    )
+
+    stored_log = ingest_log(log, backend)
+    try:
+        with measure_stage("parse", collector, logger):
+            parsed_lines = parse_log(stored_log, backend)
+
+        result = reduce_parsed_lines(parsed_lines, metrics=collector, logger=logger)
+
+        with measure_stage("summarize", collector, logger):
+            result.summary = summarize_reduction_result(result)
+
+        selected_lines = sum(len(scored.block.lines) for scored in result.blocks)
+        collector.record_metric("reduction_ratio", selected_lines / max(len(parsed_lines), 1))
+        collector.record_metric("number_of_blocks", float(len(result.blocks)))
+        return result
+    finally:
+        backend.delete(stored_log.reference)

ci_log_intelligence/api/__init__.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+from pydantic import BaseModel, Field
+
+from .. import analyze_log
+
+
+class AnalyzeRequest(BaseModel):
+    log: str = Field(..., min_length=1)
+
+
+class AnalyzeBlockResponse(BaseModel):
+    start_line: int
+    end_line: int
+    score: float
+    classification: str
+
+
+class AnalyzeResponse(BaseModel):
+    blocks: list[AnalyzeBlockResponse]
+    summary: str
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="CI Log Intelligence")
+
+    @app.post("/analyze", response_model=AnalyzeResponse)
+    def analyze(request: AnalyzeRequest) -> AnalyzeResponse:
+        result = analyze_log(request.log)
+        blocks = [
+            AnalyzeBlockResponse(
+                start_line=scored.block.start_line,
+                end_line=scored.block.end_line,
+                score=scored.score,
+                classification=scored.classification,
+            )
+            for scored in result.blocks
+        ]
+        return AnalyzeResponse(blocks=blocks, summary=result.summary or "")
+
+    return app
+
+
+app = create_app()
+
+__all__ = ["AnalyzeRequest", "AnalyzeResponse", "app", "create_app"]

ci_log_intelligence/ci_analysis.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+from typing import Optional, Sequence, TYPE_CHECKING
+
+from .ci_report_builder import (
+    _summarize_root_cause,
+    build_report,
+    resolve_failure_type,
+)
+from .ci_report_builder import build_report as _build_report
+from .ci_report_builder import resolve_failure_type as _resolve_failure_type
+from .ingestion import ingest_log
+from .ingestion.github.fetcher import GitHubLogFetcher, _sort_logs, normalize_job_name
+from .ingestion.github.models import (
+    CIAnalysisReport,
+    FailedLogAnalysis,
+    NormalizedLog,
+)
+from .ingestion.github.resolver import resolve_github_url
+from .mcp.cache import CachedJob, CacheKey
+from .parsing import parse_log
+from .reducer import reduce_parsed_lines
+from .reducer.comparison import analyze_cross_run, extract_passed_context
+from .reducer.detectors import JobContext
+from .storage import InMemoryStorage
+from .summarizer import summarize_reduction_result
+from .utils.logging import get_structured_logger, log_stage_event
+from .utils.metrics import MetricsCollector, measure_stage
+
+if TYPE_CHECKING:  # pragma: no cover - typing-only import to avoid circulars
+    from .mcp.cache import JobCache
+
+
+def analyze_ci_url(
+    ci_url: str,
+    *,
+    include_passed: bool = True,
+    max_passed_runs: int = 3,
+    max_runs: int = 5,
+    fetcher: Optional[GitHubLogFetcher] = None,
+    metrics: Optional[MetricsCollector] = None,
+    cache: Optional["JobCache"] = None,
+    top_k: Optional[int] = None,
+    failure_types: Optional[Sequence[str]] = None,
+) -> CIAnalysisReport:
+    """Run the end-to-end CI analysis pipeline for a GitHub URL.
+
+    When ``cache`` is provided, per-job (parse + reduce) results are looked up on
+    ``(repo, run_id, job_id)`` and stored after computation. Cache hits skip the
+    parse + reduce work. The fetch (GitHub API call for the log content) still
+    happens unless the caller arranges to suppress it; today the cache short-
+    circuits only the CPU-bound stages, which is the dominant cost for cached
+    runs because the GitHub API returns 304 (or is otherwise cheap for an
+    already-completed immutable job log).
+    """
+    logger = get_structured_logger("ci_log_intelligence.ci")
+    collector = metrics or MetricsCollector()
+
+    with measure_stage("resolve_ci_url", collector, logger):
+        target = resolve_github_url(ci_url)
+
+    github_fetcher = fetcher or GitHubLogFetcher(logger=logger)
+    fetch_run_limit = max(max_runs, max_passed_runs + 2 if include_passed else max_runs)
+    with measure_stage("fetch_github_logs", collector, logger):
+        fetched = fetch_with_cache_awareness(
+            github_fetcher,
+            target,
+            include_passed=include_passed,
+            max_runs=fetch_run_limit,
+            max_passed_runs=max_passed_runs,
+            cache=cache,
+        )
+
+    failed_logs = [log for log in fetched.logs if log.status == "failed"]
+    passed_logs = [log for log in fetched.logs if log.status == "passed"]
+    collector.record_metric("failed_jobs", float(len(failed_logs)))
+    collector.record_metric("passed_jobs", float(len(passed_logs)))
+    log_stage_event(
+        logger,
+        "analyze_ci_url",
+        runs=len(fetched.runs),
+        failed_jobs=len(failed_logs),
+        passed_jobs=len(passed_logs),
+    )
+
+    failed_analyses: list[FailedLogAnalysis] = []
+    total_anchors = 0.0
+    total_blocks = 0.0
+    for failed_log in failed_logs:
+        failed_metrics = MetricsCollector()
+        job_context = JobContext(
+            job_name=failed_log.job_name,
+            run_id=failed_log.run_id,
+            repo=target.repo,
+        )
+
+        cached = _lookup_cache(cache, target.repo, failed_log)
+        if cached is not None:
+            reduction_result = cached.reduction_result
+            cache_hit_anchors = float(_count_anchors(reduction_result))
+            cache_hit_blocks = float(len(reduction_result.blocks))
+            failed_metrics.record_metric("number_of_anchors", cache_hit_anchors)
+            failed_metrics.record_metric("number_of_blocks", cache_hit_blocks)
+            log_stage_event(logger, "job_cache_hit", run_id=failed_log.run_id, job_id=failed_log.job_id)
+        else:
+            with measure_stage("reduce_failed_log", collector, logger):
+                reduction_result, parsed_lines = _analyze_single_log(
+                    failed_log.content,
+                    metrics=failed_metrics,
+                    job_context=job_context,
+                )
+            _store_cache(cache, target.repo, failed_log, parsed_lines, reduction_result)
+
+        snapshot = failed_metrics.snapshot()
+        total_anchors += float(snapshot["metrics"].get("number_of_anchors", 0.0))
+        total_blocks += float(snapshot["metrics"].get("number_of_blocks", 0.0))
+        failed_analyses.append(
+            FailedLogAnalysis(
+                log=failed_log,
+                logical_job_name=normalize_job_name(failed_log.job_name),
+                result=reduction_result,
+            )
+        )
+
+    collector.record_metric("anchors_detected", total_anchors)
+    collector.record_metric("blocks_generated", total_blocks)
+    log_stage_event(
+        logger,
+        "failed_log_analysis",
+        anchors_detected=total_anchors,
+        blocks_generated=total_blocks,
+    )
+
+    with measure_stage("extract_passed_context", collector, logger):
+        passed_contexts = extract_passed_context(failed_analyses, passed_logs)
+
+    with measure_stage("cross_run_analysis", collector, logger):
+        insights = analyze_cross_run(failed_analyses, passed_contexts)
+
+    return build_report(
+        runs=fetched.runs,
+        failed_logs=failed_logs,
+        passed_logs=passed_logs,
+        failed_analyses=failed_analyses,
+        passed_contexts=passed_contexts,
+        insights=insights,
+        top_k=top_k,
+        failure_types=failure_types,
+    )
+
+
+def fetch_with_cache_awareness(
+    fetcher: GitHubLogFetcher,
+    target,
+    *,
+    include_passed: bool,
+    max_runs: int,
+    max_passed_runs: int,
+    cache: Optional["JobCache"],
+):
+    """Plan the fetch, then fetch only the log content the cache doesn't already cover.
+
+    When ``cache`` is ``None`` behavior is identical to ``fetcher.fetch_logs``.
+    When a cache is provided, planned jobs whose ``(repo, run_id, job_id)`` is
+    already present in the cache are short-circuited: an empty-``content``
+    placeholder ``NormalizedLog`` is emitted so the downstream loop still sees
+    the job (and the cache-hit branch picks it up). Passed jobs are always
+    fetched because their reduction is consumed by ``extract_passed_context``
+    without going through the cache.
+    """
+    if cache is None:
+        return fetcher.fetch_logs(
+            target,
+            include_passed=include_passed,
+            max_runs=max_runs,
+            max_passed_runs=max_passed_runs,
+        )
+
+    plan = fetcher.plan_logs(
+        target,
+        include_passed=include_passed,
+        max_runs=max_runs,
+        max_passed_runs=max_passed_runs,
+    )
+
+    cached_logs: list = []
+    jobs_to_fetch: list = []
+    for run, job, _, status in plan.planned_jobs:
+        if status == "failed":
+            key = CacheKey(repo=target.repo, run_id=run.run_id, job_id=job.job_id)
+            if cache.get(key) is not None:
+                # Emit a placeholder log so the analyze loop iterates this job
+                # and takes the cache-hit branch. The empty ``content`` is
+                # never read because the cache lookup short-circuits it.
+                # See ``NormalizedLog`` docstring for the placeholder contract.
+                cached_logs.append(
+                    NormalizedLog(
+                        run_id=run.run_id,
+                        job_id=job.job_id,
+                        job_name=job.job_name,
+                        status="failed",
+                        content="",
+                    )
+                )
+                continue
+        jobs_to_fetch.append((run, job, _, status))
+
+    fetched_logs = fetcher.fetch_planned_log_content(target.repo, jobs_to_fetch) if jobs_to_fetch else []
+    all_logs = _sort_logs(cached_logs + fetched_logs)
+
+    # ``assemble_fetched_data`` handles both include_passed=True (group + cap)
+    # and include_passed=False (failed-only filter), so a single call covers
+    # both paths.
+    return fetcher.assemble_fetched_data(
+        plan,
+        all_logs,
+        include_passed=include_passed,
+        max_passed_runs=max_passed_runs,
+    )
+
+
+def _lookup_cache(
+    cache: Optional["JobCache"],
+    repo: str,
+    failed_log: NormalizedLog,
+) -> Optional["CachedJob"]:
+    if cache is None:
+        return None
+    key = CacheKey(repo=repo, run_id=failed_log.run_id, job_id=failed_log.job_id)
+    return cache.get(key)
+
+
+def _store_cache(
+    cache: Optional["JobCache"],
+    repo: str,
+    failed_log: NormalizedLog,
+    parsed_lines,
+    reduction_result,
+) -> None:
+    if cache is None:
+        return
+    key = CacheKey(repo=repo, run_id=failed_log.run_id, job_id=failed_log.job_id)
+    cache.put(
+        key,
+        CachedJob(
+            job_name=failed_log.job_name,
+            parsed_lines=list(parsed_lines),
+            reduction_result=reduction_result,
+        ),
+    )
+
+
+def _count_anchors(reduction_result) -> int:
+    return sum(len(scored.block.anchors) for scored in reduction_result.blocks)
+
+
+def _analyze_single_log(
+    content: str,
+    metrics: Optional[MetricsCollector] = None,
+    job_context: Optional[JobContext] = None,
+):
+    """Parse and reduce one log; returns ``(ReductionResult, parsed_lines)``.
+
+    Returning the parsed line list alongside the reduction result lets the cache
+    retain the raw line content needed by ``get_block`` without re-parsing.
+    """
+    logger = get_structured_logger("ci_log_intelligence")
+    collector = metrics or MetricsCollector()
+    backend = InMemoryStorage()
+    stored_log = ingest_log(content, backend)
+    try:
+        with measure_stage("parse", collector, logger):
+            parsed_lines = parse_log(stored_log, backend)
+
+        result = reduce_parsed_lines(
+            parsed_lines,
+            metrics=collector,
+            logger=logger,
+            job_context=job_context,
+        )
+
+        with measure_stage("summarize", collector, logger):
+            result.summary = summarize_reduction_result(result)
+
+        selected_lines = sum(len(scored.block.lines) for scored in result.blocks)
+        collector.record_metric("reduction_ratio", selected_lines / max(len(parsed_lines), 1))
+        collector.record_metric("number_of_blocks", float(len(result.blocks)))
+        return result, parsed_lines
+    finally:
+        backend.delete(stored_log.reference)

ci_log_intelligence/ci_report_builder.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional, Sequence
+
+from .ingestion.github.fetcher import normalize_job_name
+from .ingestion.github.models import (
+    AnalysisMetadata,
+    CIAnalysisReport,
+    FailedLogAnalysis,
+    FailureRecord,
+    NormalizedLog,
+    PassedContextView,
+    RootCauseSummary,
+    WorkflowRun,
+)
+from .models import ScoreComponents, ScoredBlock
+from .reducer.comparison import (
+    render_block_excerpt,
+    select_root_cause,
+    summarize_failed_block,
+)
+from .reducer.detectors import DetectedFailure
+
+
+def build_report(
+    *,
+    runs: Sequence[WorkflowRun],
+    failed_logs: Sequence[NormalizedLog],
+    passed_logs: Sequence[NormalizedLog],
+    failed_analyses: Sequence[FailedLogAnalysis],
+    passed_contexts: Iterable,
+    insights: Iterable[str],
+    top_k: Optional[int] = None,
+    failure_types: Optional[Sequence[str]] = None,
+) -> CIAnalysisReport:
+    """Assemble the final ``CIAnalysisReport`` from per-job analyses.
+
+    When ``failure_types`` is provided, the ``failures`` array is filtered to records whose
+    ``type`` matches one of the listed strings. When ``top_k`` is provided, the (already
+    score-sorted) array is truncated to that length. Both filters are reflected in
+    ``metadata.failures_returned`` / ``metadata.failures_total`` so callers can detect
+    truncation.
+    """
+    root_cause_candidate = select_root_cause(failed_analyses)
+    if root_cause_candidate is None:
+        root_cause = _empty_root_cause()
+        all_failures: list[FailureRecord] = []
+    else:
+        _, scored_block = root_cause_candidate
+        analysis = root_cause_candidate[0]
+        root_cause = _summarize_root_cause(
+            scored_block, analysis.log.job_name, analysis.log.run_id
+        )
+        all_failures = _build_failure_records(failed_analyses)
+
+    failures_total = len(all_failures)
+
+    if failure_types is not None:
+        allowed = {failure_type for failure_type in failure_types}
+        all_failures = [record for record in all_failures if record.type in allowed]
+
+    if top_k is not None:
+        all_failures = all_failures[: max(top_k, 0)]
+
+    failures_returned = len(all_failures)
+
+    passed_context_views = [
+        PassedContextView(job_name=context.job_name, excerpt=context.excerpt)
+        for context in passed_contexts
+    ]
+    metadata = AnalysisMetadata(
+        total_runs_analyzed=len({run.run_id for run in runs}),
+        failed_runs=len({log.run_id for log in failed_logs}),
+        passed_runs=len({log.run_id for log in passed_logs}),
+        failures_returned=failures_returned,
+        failures_total=failures_total,
+    )
+
+    return CIAnalysisReport(
+        root_cause=root_cause,
+        failures=all_failures,
+        passed_context=passed_context_views,
+        cross_run_insights=list(insights),
+        metadata=metadata,
+    )
+
+
+def _empty_root_cause() -> RootCauseSummary:
+    return RootCauseSummary(
+        summary="No failing jobs found in the analyzed CI runs.",
+        log_excerpt="",
+        has_traceback=False,
+        has_stack_trace=False,
+        has_assertion=False,
+        score=0.0,
+        score_components=ScoreComponents(
+            severity_weight=0.0,
+            signal_density=0.0,
+            duplicate_penalty=0.0,
+        ),
+    )
+
+
+def _build_failure_records(
+    failed_analyses: Iterable[FailedLogAnalysis],
+) -> list[FailureRecord]:
+    failures: list[FailureRecord] = []
+    for current_analysis in sorted(
+        failed_analyses,
+        key=lambda item: (-item.log.run_id, item.log.job_name.lower(), item.log.job_id),
+    ):
+        detected = current_analysis.result.detected_failures
+        for block in current_analysis.result.blocks:
+            failure_type, extracted = resolve_failure_type(block, detected)
+            highest_severity = max(
+                (anchor.severity for anchor in block.block.anchors),
+                default=0,
+            )
+            failures.append(
+                FailureRecord(
+                    type=failure_type,
+                    classification=block.classification,
+                    severity=highest_severity,
+                    score=block.score,
+                    start_line=block.block.start_line,
+                    end_line=block.block.end_line,
+                    summary=summarize_failed_block(
+                        block, current_analysis.log.job_name, current_analysis.log.run_id
+                    ),
+                    log_excerpt=render_block_excerpt(block),
+                    extracted_fields=extracted,
+                )
+            )
+    return failures
+
+
+def resolve_failure_type(
+    scored_block: ScoredBlock,
+    detected_failures: list[DetectedFailure],
+) -> tuple[str, dict[str, Any]]:
+    """Resolve the FailureRecord ``type`` and ``extracted_fields`` for a scored block.
+
+    Walks the DetectedFailures whose ``anchor_lines`` fall inside the block, picks the
+    most-specific type (``"generic"`` loses to anything else; ties between specialized
+    types break by highest severity then earliest anchor line), and merges
+    ``extracted_fields`` from contributors of the winning type ONLY.
+    """
+    block_line_range = range(
+        scored_block.block.start_line, scored_block.block.end_line + 1
+    )
+    contributors = [
+        failure
+        for failure in detected_failures
+        if any(line in block_line_range for line in failure.anchor_lines)
+    ]
+    if not contributors:
+        return "generic", {}
+
+    specialized = [c for c in contributors if c.type != "generic"]
+    if specialized:
+        primary = min(
+            specialized,
+            key=lambda failure: (-failure.severity, min(failure.anchor_lines, default=0)),
+        )
+        merged: dict[str, Any] = {}
+        for c in specialized:
+            if c.type == primary.type:
+                merged.update(c.extracted_fields)
+        return primary.type, merged
+
+    signal_names: list[str] = []
+    for c in contributors:
+        name = c.extracted_fields.get("signal_name")
+        if name and name not in signal_names:
+            signal_names.append(name)
+    return "generic", {"signal_names": signal_names}
+
+
+def _summarize_root_cause(
+    scored_block: ScoredBlock,
+    job_name: str,
+    run_id: int,
+) -> RootCauseSummary:
+    block_signals = {signal for line in scored_block.block.lines for signal in line.signals}
+    has_traceback = "traceback" in block_signals
+    has_stack_trace = any(
+        line.content.startswith("  File ") for line in scored_block.block.lines
+    )
+    has_assertion = "assertion_error" in block_signals or any(
+        "AssertionError" in line.content for line in scored_block.block.lines
+    )
+    return RootCauseSummary(
+        summary=summarize_failed_block(scored_block, job_name, run_id),
+        log_excerpt=render_block_excerpt(scored_block),
+        has_traceback=has_traceback,
+        has_stack_trace=has_stack_trace,
+        has_assertion=has_assertion,
+        score=scored_block.score,
+        score_components=scored_block.score_components,
+    )
+
+
+__all__ = ["build_report", "resolve_failure_type"]

ci_log_intelligence/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI entrypoints for CI Log Intelligence."""

ci_log_intelligence/cli/main.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from ..ci_analysis import analyze_ci_url
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ci-log-intel")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    analyze_parser = subparsers.add_parser("analyze")
+    analyze_parser.add_argument("--url", required=True)
+    analyze_parser.add_argument("--include-passed", action="store_true")
+    analyze_parser.add_argument("--max-passed-runs", type=int, default=3)
+    analyze_parser.add_argument("--json", action="store_true")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command != "analyze":
+        parser.error(f"Unsupported command: {args.command}")
+
+    report = analyze_ci_url(
+        args.url,
+        include_passed=args.include_passed,
+        max_passed_runs=args.max_passed_runs,
+    )
+
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2, sort_keys=True))
+        return 0
+
+    print(f"Root cause: {report.root_cause.summary}")
+    if report.root_cause.log_excerpt:
+        print()
+        print("Log excerpt:")
+        print(report.root_cause.log_excerpt)
+
+    if report.failures:
+        print()
+        print("Failures:")
+        for failure in report.failures:
+            print(f"- [{failure.type}/{failure.classification}] {failure.summary}")
+            if failure.extracted_fields:
+                kv = ", ".join(
+                    f"{k}={v}" for k, v in sorted(failure.extracted_fields.items())
+                )
+                print(f"    {kv}")
+
+    if report.passed_context:
+        print()
+        print("Passed context:")
+        for context in report.passed_context:
+            print(f"- {context.job_name}")
+            print(context.excerpt)
+
+    if report.cross_run_insights:
+        print()
+        print("Cross-run insights:")
+        for insight in report.cross_run_insights:
+            print(f"- {insight}")
+
+    print()
+    print(
+        "Metadata: "
+        f"runs={report.metadata.total_runs_analyzed} "
+        f"failed_runs={report.metadata.failed_runs} "
+        f"passed_runs={report.metadata.passed_runs}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ci_log_intelligence/ingestion/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from ..models import StoredLog
+from ..storage import StorageBackend
+
+
+def ingest_log(log: str, storage_backend: StorageBackend) -> StoredLog:
+    reference = storage_backend.write_text(log)
+    return StoredLog(
+        reference=reference,
+        byte_size=len(log.encode("utf-8")),
+        backend_name=storage_backend.name,
+    )