| --- |
| 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. |
|
|
