---
title: AKD - Scope Interview Agent
emoji: 📋
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
short_description: Requirements interview → Scope Requirements Document
---

# 📋 Scope Interview Agent

A strict, structured **requirements interviewer**: it extracts a complete
**Scope Requirements Document** from engineers, scientists, and project managers
*before any design or implementation begins* — one focused question at a time,
across nine mandatory interview steps.

**Artifacts-driven:** the agent's instructions are NOT hardcoded. They are loaded
at startup from `./artifact/agents.md` — the **CARE v2 artifact**: the
`scope-interview` skill from
[NASA-IMPACT/akd-plugins](https://github.com/NASA-IMPACT/akd-plugins)
(`plugins/scope-interview/skills/scope-interview/SKILL.md`), bundled verbatim.
A web-chat session addendum adapts its Claude-Code-specific parts (codebase
exploration, file saving) to this UI. If reference files ever ship alongside
the skill, they are exposed through a `read_reference` tool automatically.

**Guardrailed (pydantic-ai v2 harness):** every turn is checked by the
[NASA-IMPACT/akd-guardrails](https://github.com/NASA-IMPACT/akd-guardrails)
service, attached as `InputGuard` / `OutputGuard` capabilities on the agent —
`gliguard` (GLiNER) screens each user prompt *before the model is invoked*
(hard block, zero tokens), and `risk_agent` (LLM judge) reviews the final
answer with the interview's recent turns as grounding context before it
renders. No guard logic lives in this app; it only relays verdicts. Blocked
turns show `⛔ Blocked by AKD input/output guardrails: <risks>`, and blocked
answers never enter the conversation memory. If the guardrails service itself
is unreachable, checks fail open (logged).

## What it does

- Guides you through 9 interview steps (problem understanding, stakeholder mapping,
  scope boundaries, assumptions, requirements, entities, workflows, risks)
- Live progress bar tracks the interview step
- Streams a collapsible reasoning trace per reply
- Produces a Scope Requirements Document at the end, downloadable as `.md`
- Strictly scoped: extracts requirements only — no design, no architecture, no code
- Model + reasoning-effort selectors (bring-your-own OpenAI key)

## Run locally

```bash
cd scope-interview-agent
pip install -r requirements.txt
python app.py
```

## Configuration

| Variable | Required | Purpose |
| --- | --- | --- |
| OpenAI API key | yes | Entered by each visitor in the UI (bring-your-own-key). |
| `AKD_GUARDRAILS_URL` | no | AKD guardrails service base URL (default: the dev ALB). |
| `ARTIFACT_DIR` | no | Artifact folder override (default `./artifact`). |
| `AGENT_MODEL` | no | Default model id (default `gpt-5.2`). |

No server-side secrets are required. Each visitor supplies their own OpenAI key at runtime.