Upload app.py

app.py

@@ -0,0 +1,405 @@
+"""AISA Compliance Checker — HuggingFace Space App.
+
+A web interface for evaluating agentic AI projects against the
+AISA (Agentic AI Systems Architecture) reference architecture.
+"""
+
+import gradio as gr
+import tempfile
+import zipfile
+import shutil
+from pathlib import Path
+from datetime import datetime
+
+from aisa.scanner.detector import detect_frameworks
+from aisa.scanner.analyzer import scan_project
+from aisa.ai_checker.agent import ai_check_project, AICheckConfig
+from aisa.ai_checker.combined import combine_results
+from aisa.report.generator import generate_markdown_report
+from aisa.report.recommendations import get_recommendation, get_priority
+from aisa.layers import ALL_LAYERS, ALL_CONTRACTS
+
+
+# ---------------------------------------------------------------------------
+# Core Analysis Functions
+# ---------------------------------------------------------------------------
+
+def run_analysis(
+    zip_file,
+    analysis_mode: str,
+    provider: str,
+    api_key: str,
+    model_name: str,
+    progress=gr.Progress(),
+):
+    """Run AISA compliance analysis on an uploaded project."""
+    if zip_file is None:
+        raise gr.Error("Please upload a ZIP file of your project.")
+
+    # Step 1: Extract ZIP
+    progress(0.05, desc="Extracting project files...")
+    temp_dir = tempfile.mkdtemp(prefix="aisa_")
+    project_path = Path(temp_dir) / "project"
+    project_path.mkdir()
+
+    try:
+        with zipfile.ZipFile(zip_file.name, "r") as zf:
+            zf.extractall(project_path)
+    except (zipfile.BadZipFile, Exception) as e:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+        raise gr.Error(f"Invalid ZIP file: {e}")
+
+    # Check if ZIP has a single root folder
+    items = list(project_path.iterdir())
+    if len(items) == 1 and items[0].is_dir():
+        project_path = items[0]
+
+    try:
+        # Step 2: Detect frameworks
+        progress(0.15, desc="Detecting frameworks...")
+        frameworks = detect_frameworks(project_path)
+
+        # Step 3: Pattern scan
+        progress(0.25, desc="Running pattern-based scan...")
+        pattern_result = scan_project(project_path, frameworks)
+
+        ai_result = None
+
+        # Step 4: AI analysis (if requested)
+        if analysis_mode in ("AI Analysis", "Full Analysis (Pattern + AI)"):
+            if not api_key.strip():
+                if analysis_mode == "Full Analysis (Pattern + AI)":
+                    progress(0.60, desc="No API key provided, using pattern results only...")
+                else:
+                    shutil.rmtree(temp_dir, ignore_errors=True)
+                    raise gr.Error("API key is required for AI Analysis. Please enter your API key.")
+            else:
+                progress(0.40, desc=f"Running AI analysis with {provider}...")
+                config = AICheckConfig(
+                    provider=provider.lower(),
+                    model=model_name.strip() or "",
+                    api_key=api_key.strip(),
+                )
+                config = config.resolve()
+                try:
+                    ai_result = ai_check_project(project_path, config)
+                except Exception as e:
+                    if analysis_mode == "AI Analysis":
+                        shutil.rmtree(temp_dir, ignore_errors=True)
+                        raise gr.Error(f"AI analysis failed: {e}")
+                    # For full-check, fall back to pattern only
+
+        # Step 5: Combine results
+        progress(0.70, desc="Generating report...")
+        if analysis_mode == "AI Analysis" and ai_result:
+            result = ai_result
+        elif analysis_mode == "Full Analysis (Pattern + AI)" and ai_result:
+            result = combine_results(pattern_result, ai_result)
+        else:
+            result = pattern_result
+
+        # Step 6: Generate outputs
+        progress(0.85, desc="Formatting results...")
+
+        # Summary card
+        summary = _build_summary(result, analysis_mode)
+
+        # Layer details
+        layer_details = _build_layer_details(result)
+
+        # Full markdown report
+        full_report = generate_markdown_report(result)
+
+        # Save report to file for download
+        report_path = Path(temp_dir) / "aisa_report.md"
+        report_path.write_text(full_report)
+
+        progress(1.0, desc="Done!")
+
+        return summary, layer_details, full_report, str(report_path)
+
+    finally:
+        # Clean up extracted files but keep report
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Output Builders
+# ---------------------------------------------------------------------------
+
+def _build_summary(result, mode: str) -> str:
+    """Build the summary overview card."""
+    score = result.overall_score
+    grade = _get_grade(score)
+    layer_score = result.layer_score
+    contract_score = result.contract_score
+
+    # Framework detection
+    fw_text = ""
+    if result.frameworks_detected:
+        fw_list = sorted(result.frameworks_detected.items(), key=lambda x: -x[1])
+        fw_text = " | ".join(f"**{name}** ({conf:.0%})" for name, conf in fw_list[:5])
+    else:
+        fw_text = "No known frameworks detected"
+
+    # Stats
+    files_text = ""
+    if result.files_scanned > 0:
+        files_text = f"**Files Scanned:** {result.files_scanned} Python files ({result.total_lines:,} lines)"
+
+    # Score bar
+    filled = int(score / 100 * 30)
+    bar = "█" * filled + "░" * (30 - filled)
+
+    # Count gaps
+    total_criteria = sum(lr.total_count for lr in result.layer_results + result.contract_results)
+    total_covered = sum(lr.covered_count for lr in result.layer_results + result.contract_results)
+    gaps = total_criteria - total_covered
+
+    return f"""## AISA Compliance Score
+
+# {score:.0f}/100 — {grade}
+
+`{bar}`
+
+| Metric | Value |
+|--------|-------|
+| **Analysis Mode** | {mode} |
+| **Layer Score** | {layer_score:.0f}% |
+| **Contract Score** | {contract_score:.0f}% |
+| **Criteria Covered** | {total_covered}/{total_criteria} |
+| **Gaps Found** | {gaps} |
+| {files_text} | |
+
+### Detected Frameworks
+{fw_text}
+"""
+
+
+def _build_layer_details(result) -> str:
+    """Build detailed layer-by-layer breakdown."""
+    lines = ["## Layer-by-Layer Breakdown\n"]
+
+    # Layer table
+    lines.append("### Architectural Layers\n")
+    lines.append("| Layer | Coverage | Status | Covered | Gaps |")
+    lines.append("|-------|:--------:|:------:|:-------:|:----:|")
+
+    for lr in result.layer_results:
+        score = lr.coverage_score
+        status = _score_label(score)
+        bar = _mini_bar(score)
+        lines.append(f"| {lr.id}: {lr.name} | {bar} {score:.0f}% | {status} | {lr.covered_count}/{lr.total_count} | {lr.total_count - lr.covered_count} |")
+
+    lines.append("")
+
+    # Contract table
+    lines.append("### Cross-Layer Contracts\n")
+    lines.append("| Contract | Coverage | Status | Covered | Gaps |")
+    lines.append("|----------|:--------:|:------:|:-------:|:----:|")
+
+    for cr in result.contract_results:
+        score = cr.coverage_score
+        status = _score_label(score)
+        bar = _mini_bar(score)
+        lines.append(f"| {cr.id}: {cr.name} | {bar} {score:.0f}% | {status} | {cr.covered_count}/{cr.total_count} | {cr.total_count - cr.covered_count} |")
+
+    lines.append("")
+
+    # Top gaps with recommendations
+    gaps = []
+    for lr in result.layer_results + result.contract_results:
+        priority = get_priority(lr.id)
+        for cr in lr.criteria_results:
+            if not cr.covered:
+                rec = get_recommendation(cr.criterion_id) or ""
+                gaps.append((priority, cr.criterion_id, cr.criterion_name, rec))
+
+    priority_order = {"Critical": 0, "High": 1, "Medium": 2}
+    gaps.sort(key=lambda g: (priority_order.get(g[0], 3), g[1]))
+
+    if gaps:
+        lines.append("### Top Gaps & Recommendations\n")
+        lines.append("| Priority | Criterion | Gap | Recommendation |")
+        lines.append("|:--------:|-----------|-----|----------------|")
+        for priority, cid, name, rec in gaps[:15]:
+            lines.append(f"| **{priority}** | {cid} | {name} | {rec} |")
+        if len(gaps) > 15:
+            lines.append(f"\n*...and {len(gaps) - 15} more gaps. Download the full report for details.*")
+
+    return "\n".join(lines)
+
+
+def _get_grade(score: float) -> str:
+    if score >= 80:
+        return "Grade A — Production Ready"
+    elif score >= 60:
+        return "Grade B — Maturing"
+    elif score >= 40:
+        return "Grade C — Developing"
+    elif score >= 20:
+        return "Grade D — Early Stage"
+    else:
+        return "Grade F — Significant Gaps"
+
+
+def _score_label(score: float) -> str:
+    if score >= 80:
+        return "✅ Strong"
+    elif score >= 50:
+        return "🟡 Partial"
+    elif score >= 20:
+        return "🟠 Minimal"
+    else:
+        return "🔴 Absent"
+
+
+def _mini_bar(score: float) -> str:
+    filled = int(score / 100 * 10)
+    return "█" * filled + "░" * (10 - filled)
+
+
+# ---------------------------------------------------------------------------
+# Gradio UI
+# ---------------------------------------------------------------------------
+
+HEADER_MD = """
+# 🔍 AISA Compliance Checker
+
+**Evaluate your agentic AI project against the AISA reference architecture.**
+
+Upload your project as a **ZIP file** and get an instant compliance report across
+**7 architectural layers** and **4 cross-layer contracts**.
+
+| Layer | What's Checked |
+|-------|---------------|
+| L1: LLM Foundation | Model adapters, prompts, context management, safety |
+| L2: Tool & Environment | Tool schemas, sandboxing, permissions, MCP |
+| L3: Cognitive Agent | Planning, memory, goals, reflection |
+| L4: Infrastructure | Orchestration, state, multi-agent, tracing |
+| L5: Evaluation | Tests, monitoring, regression, human eval |
+| L6: Dev & Deployment | Versioning, CI/CD, A/B testing, rollout |
+| L7: Governance | Policy-as-code, privacy, fairness, oversight |
+
+**CLI version:** `pip install aisa-checker`
+
+---
+"""
+
+FOOTER_MD = """
+---
+
+**AISA** (Agentic AI Systems Architecture) — A unified layered reference architecture
+for designing, deploying, evaluating, and governing agentic AI systems.
+
+*Nacar, O., Alquffari, D., & Alkhalifa, M. (2026). Tuwaiq Academy — TRDC.*
+
+[Paper & Resources](https://huggingface.co/AISA-Framework) |
+[PyPI Package](https://pypi.org/project/aisa-checker/) |
+[Mapping Study](https://huggingface.co/AISA-Framework)
+"""
+
+
+def create_app():
+    """Build the Gradio application."""
+    with gr.Blocks(
+        title="AISA Compliance Checker",
+        theme=gr.themes.Soft(primary_hue="blue", secondary_hue="purple"),
+    ) as app:
+
+        gr.Markdown(HEADER_MD)
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("### Upload & Configure")
+
+                zip_input = gr.File(
+                    label="Upload Project (ZIP)",
+                    file_types=[".zip"],
+                    type="filepath",
+                )
+
+                analysis_mode = gr.Radio(
+                    choices=[
+                        "Pattern Scan (Fast)",
+                        "AI Analysis",
+                        "Full Analysis (Pattern + AI)",
+                    ],
+                    value="Pattern Scan (Fast)",
+                    label="Analysis Mode",
+                    info="Pattern scan is free. AI modes require an API key.",
+                )
+
+                with gr.Accordion("AI Settings (optional)", open=False):
+                    provider = gr.Dropdown(
+                        choices=["openai", "anthropic", "google"],
+                        value="openai",
+                        label="LLM Provider",
+                    )
+                    api_key = gr.Textbox(
+                        label="API Key",
+                        placeholder="sk-... or sk-ant-... or AIza...",
+                        type="password",
+                    )
+                    model_name = gr.Textbox(
+                        label="Model (optional, uses default if empty)",
+                        placeholder="e.g., gpt-4o, claude-sonnet-4-20250514, gemini-2.0-flash",
+                    )
+
+                run_btn = gr.Button(
+                    "Run AISA Check",
+                    variant="primary",
+                    size="lg",
+                )
+
+                gr.Markdown("""
+                **How to prepare your ZIP:**
+                1. ZIP your project's root directory
+                2. Include all Python files, configs, CI/CD files
+                3. Exclude `node_modules`, `.venv`, `.git` (they're auto-skipped)
+                """)
+
+            with gr.Column(scale=2):
+                gr.Markdown("### Results")
+
+                with gr.Tabs():
+                    with gr.Tab("Summary"):
+                        summary_output = gr.Markdown(
+                            value="*Upload a project and click 'Run AISA Check' to see results.*"
+                        )
+
+                    with gr.Tab("Layer Details"):
+                        details_output = gr.Markdown(
+                            value="*Results will appear here after analysis.*"
+                        )
+
+                    with gr.Tab("Full Report"):
+                        report_output = gr.Markdown(
+                            value="*Full markdown report will appear here.*"
+                        )
+
+                    with gr.Tab("Download"):
+                        download_output = gr.File(
+                            label="Download Full Report (Markdown)",
+                        )
+
+        # Wire up the button
+        run_btn.click(
+            fn=run_analysis,
+            inputs=[zip_input, analysis_mode, provider, api_key, model_name],
+            outputs=[summary_output, details_output, report_output, download_output],
+            show_progress="full",
+        )
+
+        gr.Markdown(FOOTER_MD)
+
+    return app
+
+
+# ---------------------------------------------------------------------------
+# Launch
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    app = create_app()
+    app.launch()