PRism — Client / Vendor Setup Guide

1. What Is PRism?

PRism is an AI-powered pre-deployment risk gate that analyses every pull request before it ships. It runs 4 specialist agents in parallel:

These agent scores are weighted and combined into a Deployment Confidence Score (0–100):

• ≥ 70 → ✅ Greenlight — safe to deploy
• < 70 or any agent returns critical → 🚫 Blocked — risk brief + rollback playbook generated

PRism surfaces results in three places:

1. GitHub PR comment — automated via GitHub Actions
2. VS Code sidebar — live risk assessment in the IDE
3. API endpoint — programmatic access for custom integrations

2. Architecture Overview

PRism consists of a Setup Platform (this portal) and an Orchestrator that coordinates a set of specialised AI agents. The platform is a standalone FastAPI app that handles onboarding; the orchestrator is an independent service that processes webhook events.

┌──────────────────────────────────────────────────┐
│                 GitHub Repository                │
│   PR opened / updated ──► GitHub Actions fires   │
└────────────────────────┬─────────────────────────┘
                         │ POST /analyze
                         ▼
┌──────────────────────────────────────────────────┐
│              PRism FastAPI Backend                │
│         (Azure Container Apps or local)           │
│                                                  │
│  ┌────────────┐ ┌──────────────┐ ┌────────────┐ │
│  │Diff Analyst│ │History Agent │ │Coverage Agt│ │
│  └─────┬──────┘ └──────┬───────┘ └─────┬──────┘ │
│        │    ┌──────────┐│               │        │
│        │    │Timing Agt││               │        │
│        │    └─────┬────┘│               │        │
│        └──────┬───┴─────┴───────────────┘        │
│               ▼                                  │
│        ┌─────────────┐                           │
│        │Verdict Agent│ ── Azure OpenAI (optional)│
│        └─────┬───────┘                           │
│              │                                   │
│  ┌───────────┴────────────────────────────────┐  │
│  │ Foundry Governance (optional)              │  │
│  │  ∘ Content Safety  ∘ Tracing  ∘ Guardrails │  │
│  └────────────────────────────────────────────┘  │
└────────────────────────┬─────────────────────────┘
                         │ VerdictReport JSON
              ┌──────────┼──────────┐
              ▼          ▼          ▼
        PR Comment   VS Code    API Consumer
                     Sidebar

3. Prerequisites

Optional (for full Azure integration): An Azure subscription with permissions to create resources and a GitHub account with repo admin access (for Actions workflows).

4. Quick Start (5 Minutes — No Azure)

PRism is designed to work without any Azure resources. All Azure features degrade gracefully — the pipeline never crashes due to missing credentials.

4.1 — Clone and Install

git clone https://github.com/soni-ishan/PRism.git
cd PRism
pip install -r requirements.txt

4.2 — Create a Minimal .env

# Only needed if you want live GitHub data fetching
GITHUB_TOKEN=ghp_your_token_here

4.3 — Start the Server

uvicorn agents.orchestrator.server:app --reload --port 8000

4.4 — Test It

# Health check
curl http://localhost:8000/health
# → {"status": "ok", "service": "prism"}

# Run an analysis
curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "pr_number": 46,
    "repo": "your-org/your-repo",
    "changed_files": ["payment_service.py", "utils/retry.py"],
    "diff": "- retry_count=3\n+ pass",
    "timestamp": "2026-03-07T16:50:00Z"
  }'

What Works Without Azure

5. Azure Resource Provisioning

Resource Summary

Manual Provisioning (Azure Portal)

1. Azure CLI Login: az login
2. Create Resource Group: az group create --name rg-prism --location eastus
3. Azure OpenAI: Create via portal, deploy gpt-4o-mini model, copy endpoint and key
4. AI Foundry Project: Create at ai.azure.com, copy project connection string
5. Content Safety: Create via portal, same region as OpenAI, copy endpoint and key
6. Application Insights: Create workspace-based instance, copy connection string
7. Azure AI Search: Create free-tier instance, copy endpoint and admin key

Automated Provisioning (Bicep / IaC)

az deployment group create \
  --resource-group rg-prism \
  --template-file infra/main.bicep \
  --parameters environmentName=prod location=eastus

6. Environment Variables Reference

Complete .env File

# ─── Required for live GitHub data ───
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# ─── Azure OpenAI (LLM-enhanced risk briefs) ───
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-key-here
AZURE_OPENAI_DEPLOYMENT=gpt-4o-mini

# ─── Azure AI Foundry (audit trail, evaluation) ───
AZURE_FOUNDRY_PROJECT_CONNECTION_STRING=your-connection-string

# ─── Azure Content Safety (LLM output filtering) ───
AZURE_CONTENT_SAFETY_ENDPOINT=https://your-cs.cognitiveservices.azure.com/
AZURE_CONTENT_SAFETY_KEY=your-key-here

# ─── Application Insights (tracing) ───
APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=xxx

# ─── Azure AI Search (History Agent) ───
AZURE_AI_SEARCH_ENDPOINT=https://your-search.search.windows.net
AZURE_AI_SEARCH_KEY=your-admin-key

Which Vars Are Actually Required?

None of them are strictly required. The system works with zero env vars — every feature degrades gracefully:

7. GitHub Actions Integration (PR Comments)

This is how PRism automatically comments on every PR with a risk assessment.

7.1 — Add the Workflow File

Create .github/workflows/prism-gate.yml in your repository:

name: PRism Risk Gate

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  prism-analysis:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      statuses: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get PR diff
        id: diff
        run: |
          DIFF=$(gh pr diff ${{ github.event.pull_request.number }} \
            --repo ${{ github.repository }})
          echo "diff<<EOF" >> $GITHUB_OUTPUT
          echo "$DIFF" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Get changed files
        id: files
        run: |
          FILES=$(gh pr view ${{ github.event.pull_request.number }} \
            --json files -q '.files[].path' \
            --repo ${{ github.repository }})
          echo "files=$FILES" >> $GITHUB_OUTPUT
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Call PRism API
        id: prism
        run: |
          RESPONSE=$(curl -s -X POST \
            "${{ vars.PRISM_API_URL }}/analyze" \
            -H "Content-Type: application/json" \
            -d '{
              "pr_number": ${{ github.event.pull_request.number }},
              "repo": "${{ github.repository }}",
              "changed_files": ${{ steps.files.outputs.files }},
              "diff": ${{ toJSON(steps.diff.outputs.diff) }},
              "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"    
            }')
          echo "response=$RESPONSE" >> $GITHUB_OUTPUT

      - name: Post PR Comment
        run: |
          SCORE=$(echo '${{ steps.prism.outputs.response }}' \
            | jq -r '.confidence_score')
          DECISION=$(echo '${{ steps.prism.outputs.response }}' \
            | jq -r '.decision')
          BRIEF=$(echo '${{ steps.prism.outputs.response }}' \
            | jq -r '.risk_brief')
          gh pr comment ${{ github.event.pull_request.number }} \
            --repo ${{ github.repository }} \
            --body "## 🔬 PRism Deployment Risk Assessment
          **Confidence Score:** $SCORE / 100
          **Decision:** $DECISION
          $BRIEF"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Set commit status
        run: |
          DECISION=$(echo '${{ steps.prism.outputs.response }}' \
            | jq -r '.decision')
          if [ "$DECISION" = "greenlight" ]; then
            STATE="success"
            DESC="PRism: Deploy approved"
          else
            STATE="failure"
            DESC="PRism: Deploy blocked"
          fi
          gh api repos/${{ github.repository }}/statuses/${{ github.event.pull_request.head.sha }} \
            -f state="$STATE" -f description="$DESC" \
            -f context="PRism Risk Gate"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

7.2 — Configure Repository Variables

Go to your repo → Settings → Secrets and variables → Actions → Variables tab:

7.3 — What the PR Comment Looks Like

A commit status check is also set, which can be made required in branch protection rules to physically prevent merging blocked PRs.

8. VS Code Extension

The PRism VS Code extension provides a sidebar panel showing the Deployment Confidence Score, per-agent findings, and rollback playbook — directly in the IDE. Publisher: thegooddatalab (VS Code Marketplace).

8.1 — Install

From the Marketplace (recommended):

Search "PRism" in the VS Code Extensions view, or install via the command line:

code --install-extension thegooddatalab.prism

From source (development):

cd vscode_extension
npm install
npm run compile
# Press F5 to launch the Extension Development Host

8.2 — GitHub Authorization (First-Time Setup)

On first activation, the extension prompts you to authorize your GitHub account via VS Code's built-in GitHub authentication. This is optional but strongly recommended.

Two modes of operation based on your choice:

Scenario A — GitHub not authorized

The extension performs a local analysis using VS Code's git extension helpers to extract the current diff and changed files. This means:

• Diff Analyst and Coverage Agent work using local git diff HEAD~1 data
• Timing Agent always works (it only needs the current timestamp)
• History Agent is skipped — it requires GitHub repository context to look up past incidents in Azure AI Search
• The extension calls /analyze on the PRism backend, consuming one free-tier analysis run

Scenario B — GitHub authorized (recommended)

The extension connects to your GitHub account and looks up the open PR for your current branch. It then reads the existing PRism deployment analysis comment directly from the PR — no new analysis is triggered.

Benefits of this approach:

• Zero free-tier runs consumed — just reading an existing comment
• Most accurate results — the PR comment analysis has full repo context, including incident history from the History Agent
• Consistent view — you see exactly the same assessment as team members looking at the PR on GitHub

8.3 — When Does Analysis Run?

8.4 — Configuration

Open VS Code Settings (Ctrl+,) and search for "PRism":

8.5 — Features

• Activity bar icon — click the PRism icon in the left sidebar
• Score gauge — color-coded (green ≥70, yellow 40–69, red <40)
• Agent cards — each agent shows status badge, risk modifier, and specific findings
• Rollback playbook drawer — expandable section with step-by-step rollback instructions when deploy is blocked
• Freemium credit meter — shows remaining free-tier analysis runs out of 500
• Re-run button — toolbar button triggers immediate fresh analysis
• Full Report panel — PRism: Show Full Report command opens a detailed panel
• HTTP 402 handling — when free-tier credits are exhausted, a notification appears with an "Open Settings" link to configure a self-hosted backend

9. Production Deployment (Azure Container Apps)

Why Azure Container Apps?

• Scale-to-zero — no cost when idle (perfect for PR-driven workloads)
• Serverless containers — no VM management, no Kubernetes complexity
• Built-in HTTPS — automatic TLS certificates
• Azure RBAC + Managed Identity — zero API keys in production
• Qualifies for Azure Integration Prize — deep Azure service integration

Build & Deploy

# Build locally
docker build -t prism-api .
docker run -p 8000:8000 --env-file .env prism-api

# Or deploy to Azure
az acr create --name prismacr --resource-group rg-prism \
  --sku Basic --admin-enabled true

az acr build --registry prismacr --image prism-api:latest .

az containerapp create --name prism-api \
  --resource-group rg-prism --environment prism-env \
  --image prismacr.azurecr.io/prism-api:latest \
  --target-port 8000 --ingress external \
  --min-replicas 0 --max-replicas 3

Get Your Public URL

az containerapp show --name prism-api \
  --resource-group rg-prism \
  --query "properties.configuration.ingress.fqdn" \
  --output tsv

Use this URL as PRISM_API_URL in GitHub Actions and prism.serverUrl in the VS Code extension.

10. Production: Managed Identity (Zero API Keys)

In production on Azure, use Managed Identities and RBAC role assignments instead of API keys. The Container App gets an identity that Azure trusts — no secrets to manage, rotate, or leak.

Enable & Assign Roles

# Enable system-assigned identity
az containerapp identity assign --name prism-api \
  --resource-group rg-prism --system-assigned

# Assign RBAC roles
az role assignment create --assignee $IDENTITY \
  --role "Cognitive Services OpenAI User" --scope <openai-scope>

az role assignment create --assignee $IDENTITY \
  --role "Cognitive Services User" --scope <content-safety-scope>

az role assignment create --assignee $IDENTITY \
  --role "Search Index Data Reader" --scope <search-scope>

Dev vs Production Auth

11. Verifying the Setup

Health Check

curl https://your-prism-url/health
# Expected: {"status": "ok", "service": "prism"}

Run an Analysis

curl -X POST https://your-prism-url/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "pr_number": 1,
    "repo": "your-org/your-repo",
    "changed_files": ["src/main.py"],
    "diff": "- old_code\n+ new_code",
    "timestamp": "2026-03-10T10:00:00Z"
  }'

Expected response:

{
  "confidence_score": 67,
  "decision": "blocked",
  "risk_brief": "...",
  "rollback_playbook": "...",
  "agent_results": [
    {"agent_name": "Diff Analyst", "risk_score_modifier": 20, "status": "warning", ...},
    {"agent_name": "History Agent", "risk_score_modifier": 15, "status": "warning", ...},
    {"agent_name": "Coverage Agent", "risk_score_modifier": 10, "status": "pass", ...},
    {"agent_name": "Timing Agent", "risk_score_modifier": 0, "status": "pass", ...}
  ]
}

VS Code Extension

1. Install the extension from the Marketplace (publisher: thegooddatalab)
2. Open a Git repository in VS Code
3. On first activation, approve the GitHub authorization prompt (optional but recommended)
4. Click the PRism icon in the activity bar
5. If GitHub is authorized and the repo has an open PR with a PRism comment: you'll see the score from that PR comment
6. If not authorized (or no open PR): the extension runs a local analysis — you should see the score gauge, per-agent cards, and (if deploy is blocked) the rollback playbook
7. Make a commit to verify the sidebar auto-refreshes

GitHub Actions

1. Add PRISM_API_URL as a repository variable
2. Open a new PR
3. The prism-gate.yml workflow should fire
4. A PR comment should appear with the risk assessment
5. A commit status check should appear (success or failure)

12. FAQ / Troubleshooting

Do I need all the Azure resources to use PRism?

No. PRism works with zero Azure resources — all features degrade gracefully. Start with the Quick Start (Section 4) and add Azure resources incrementally as needed.

What if I only want the GitHub PR comment, not the VS Code extension?

That's fine — each delivery channel is independent. Just set up the GitHub Actions workflow (Section 7) and skip the VS Code extension.

Can I use a different LLM provider?

The core scoring engine does not use any LLM. LLMs are only used for enhancing the human-readable risk brief and rollback playbook. To swap providers, modify foundry/deployment_config/__init__.py — specifically the get_instrumented_openai_client() function.

How do I add my own incident history?

The History Agent queries Azure AI Search. Create an index, upload your incident documents (JSON with fields: file_path, severity, description, date), and set the AZURE_AI_SEARCH_* env vars. Without AI Search, mock data is used.

Can I customize the agent weights?

Yes. Edit agents/orchestrator/__init__.py — the AGENT_WEIGHTS dictionary. Weights must sum to 1.0:

AGENT_WEIGHTS = {
    "Diff Analyst":   0.30,  # Code change risk
    "History Agent":  0.25,  # Past incident risk
    "Coverage Agent": 0.25,  # Test coverage impact
    "Timing Agent":   0.20,  # Deploy window risk
}

VS Code shows "Server unreachable — showing mock data"

This means the extension can't reach the backend at the configured prism.serverUrl. Check:

1. Is the backend running? (curl http://localhost:8000/health)
2. Is the URL correct in VS Code settings? (search "PRism" in Settings)
3. If using Azure Container Apps, is the container app running? (az containerapp show ...)

If you're authorized with GitHub and your branch has an open PR with a PRism comment, the extension reads the comment directly and does not call the backend — so this error won't appear in that case.

The extension used up my free-tier credits without me doing anything

This was a known issue with the earlier polling design (the extension used to re-analyze every 30 seconds). It is fixed. The extension now only runs analysis when:

• You open it on a new repo/folder (once)
• You make a git commit
• You click the Re-run button

The free tier is 500 runs, which is more than enough for thorough evaluation.

Workflow installation fails

Ensure your PAT has the repo scope and that you have write access to the target repository. If the repo already contains .github/workflows/prism.yml, the installer will update it in place.

How to make the PRism check required for merging?

1. Go to your repo → Settings → Branches → Branch protection rules
2. Edit the rule for your main branch
3. Under "Require status checks to pass", add "PRism Risk Gate"
4. Now PRs with a blocked verdict cannot be merged

Setup Complexity Summary

PRism scales from a zero-config local tool to a fully governed enterprise deployment — incrementally, with no breaking changes at any step.

API Reference

The setup platform exposes a RESTful API documented with OpenAPI. Visit /api/docs for the interactive Swagger UI, or /api/redoc for ReDoc.