Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

feat(playbook): T3.7 NL → playbook generator (v8.0) (#330)

Beenu Arorada8210271694
diff --git a/apps/web/src/components/playbooks/DraftFromPromptDialog.test.tsx b/apps/web/src/components/playbooks/DraftFromPromptDialog.test.tsx
new file mode 100644
index 000000000..7a159b634
--- /dev/null
+++ b/apps/web/src/components/playbooks/DraftFromPromptDialog.test.tsx
@@ -0,0 +1,211 @@
+/**
+ * DraftFromPromptDialog — T3.7 NL → playbook generator UI.
+ *
+ * The dialog is the visible half of T3.7. We pin the contract the
+ * downstream PlaybookEditor relies on:
+ *
+ * 1. On submit, the dialog POSTs to /api/v1/playbooks/draft-from-nl
+ * with the trimmed prompt and ``allow_llm: true``.
+ * 2. On success, the returned ``playbook`` is parked in
+ * ``sessionStorage["aisoc:nl-draft"]`` and the router is pushed
+ * to ``/playbooks/new?nl=true``.
+ * 3. On HTTP error, the backend's text body is surfaced inline; the
+ * router is NOT pushed and sessionStorage is NOT touched.
+ * 4. Empty / whitespace-only prompts never hit the network.
+ * 5. The Cmd/Ctrl-Enter keyboard shortcut submits.
+ *
+ * The router push and fetch are mocked. The component is otherwise
+ * rendered for real (Tailwind classes are inert under jsdom).
+ */
+
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, waitFor, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { DraftFromPromptDialog } from './DraftFromPromptDialog';
+
+const pushMock = vi.hoisted(() => vi.fn());
+vi.mock('next/navigation', () => ({
+ __esModule: true,
+ useRouter: () => ({ push: pushMock }),
+}));
+
+const fakePlaybook = {
+ id: 'nl-test-id',
+ name: 'Draft test',
+ description: 'desc',
+ version: '1.0.0',
+ tags: ['nl-drafted', 'draft'],
+ trigger: { on: 'alert' },
+ steps: [
+ {
+ id: 'a1b2c3d4',
+ name: 'Notify',
+ type: 'notify',
+ params: {},
+ on_failure: 'abort',
+ retry_max: 0,
+ timeout_seconds: 30,
+ },
+ ],
+ author: 'AiSOC NL Drafter',
+ enabled: false,
+ created_at: '2026-06-27T00:00:00Z',
+ updated_at: '2026-06-27T00:00:00Z',
+};
+
+const fakeDraftResponse = {
+ playbook: fakePlaybook,
+ rationale: 'used substrate',
+ used_llm: false,
+ schema_validated: true,
+};
+
+function mockFetchOnce(body: unknown, ok = true, status = 200): void {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => ({
+ ok,
+ status,
+ json: async () => body,
+ text: async () => (typeof body === 'string' ? body : JSON.stringify(body)),
+ })),
+ );
+}
+
+describe('DraftFromPromptDialog', () => {
+ beforeEach(() => {
+ pushMock.mockReset();
+ sessionStorage.clear();
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ });
+
+ it('does not render when closed', () => {
+ render(<DraftFromPromptDialog open={false} onClose={() => undefined} />);
+ expect(screen.queryByRole('dialog')).toBeNull();
+ });
+
+ it('renders the title and a submit-disabled state when prompt is empty', () => {
+ render(<DraftFromPromptDialog open onClose={() => undefined} />);
+ expect(screen.getByRole('dialog')).toBeInTheDocument();
+ expect(screen.getByText(/Draft a playbook from a prompt/i)).toBeInTheDocument();
+ const submit = screen.getByRole('button', { name: /draft playbook/i });
+ expect(submit).toBeDisabled();
+ });
+
+ it('posts to the drafter endpoint and routes to /playbooks/new on success', async () => {
+ const user = userEvent.setup();
+ mockFetchOnce(fakeDraftResponse);
+ const handleClose = vi.fn();
+
+ render(<DraftFromPromptDialog open onClose={handleClose} />);
+ const ta = screen.getByRole('textbox');
+ await user.type(ta, 'Isolate the host and notify the SOC');
+
+ const submit = screen.getByRole('button', { name: /draft playbook/i });
+ await user.click(submit);
+
+ await waitFor(() => {
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ });
+
+ const [url, init] = (global.fetch as unknown as ReturnType<typeof vi.fn>).mock.calls[0] as [
+ string,
+ RequestInit,
+ ];
+ expect(url).toBe('/api/v1/playbooks/draft-from-nl');
+ expect(init.method).toBe('POST');
+ const body = JSON.parse(init.body as string);
+ expect(body.prompt).toBe('Isolate the host and notify the SOC');
+ expect(body.allow_llm).toBe(true);
+
+ await waitFor(() => {
+ expect(pushMock).toHaveBeenCalledWith('/playbooks/new?nl=true');
+ });
+ expect(handleClose).toHaveBeenCalled();
+
+ const parked = sessionStorage.getItem('aisoc:nl-draft');
+ expect(parked).not.toBeNull();
+ const parsed = JSON.parse(parked as string);
+ expect(parsed.id).toBe('nl-test-id');
+ expect(parsed.enabled).toBe(false);
+ });
+
+ it('surfaces the backend error text and does not route on HTTP failure', async () => {
+ const user = userEvent.setup();
+ mockFetchOnce('prompt is too long (max 4000 chars)', false, 400);
+
+ render(<DraftFromPromptDialog open onClose={() => undefined} />);
+ const ta = screen.getByRole('textbox');
+ await user.type(ta, 'whatever');
+
+ await user.click(screen.getByRole('button', { name: /draft playbook/i }));
+
+ await waitFor(() => {
+ expect(screen.getByRole('alert')).toHaveTextContent(/too long/i);
+ });
+ expect(pushMock).not.toHaveBeenCalled();
+ expect(sessionStorage.getItem('aisoc:nl-draft')).toBeNull();
+ });
+
+ it('shows a client-side error and does not call fetch on whitespace prompt', async () => {
+ const user = userEvent.setup();
+ const fetchSpy = vi.fn();
+ vi.stubGlobal('fetch', fetchSpy);
+
+ render(<DraftFromPromptDialog open onClose={() => undefined} />);
+ // Type spaces only — submit must NOT post.
+ await user.type(screen.getByRole('textbox'), ' ');
+
+ // The button is disabled while the prompt is blank/whitespace-only;
+ // we force a submit attempt via the keyboard path to prove the
+ // dialog still guards on the server contract.
+ fireEvent.keyDown(screen.getByRole('textbox'), {
+ key: 'Enter',
+ metaKey: true,
+ });
+
+ // Give the async handler a chance.
+ await new Promise((resolve) => setTimeout(resolve, 0));
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+ expect(pushMock).not.toHaveBeenCalled();
+ });
+
+ it('submits via Cmd-Enter keyboard shortcut', async () => {
+ const user = userEvent.setup();
+ mockFetchOnce(fakeDraftResponse);
+
+ render(<DraftFromPromptDialog open onClose={() => undefined} />);
+ const ta = screen.getByRole('textbox');
+ await user.type(ta, 'Notify the SOC');
+ fireEvent.keyDown(ta, { key: 'Enter', metaKey: true });
+
+ await waitFor(() => {
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ it('populates the textarea when a suggestion chip is clicked', async () => {
+ const user = userEvent.setup();
+ render(<DraftFromPromptDialog open onClose={() => undefined} />);
+
+ const chip = screen.getByRole('button', { name: /High-sev exfil/i });
+ await user.click(chip);
+
+ const ta = screen.getByRole('textbox') as HTMLTextAreaElement;
+ expect(ta.value).toMatch(/high-severity exfil alert/i);
+ });
+
+ it('closes when the Cancel button is clicked', async () => {
+ const user = userEvent.setup();
+ const handleClose = vi.fn();
+ render(<DraftFromPromptDialog open onClose={handleClose} />);
+ await user.click(screen.getByRole('button', { name: /cancel/i }));
+ expect(handleClose).toHaveBeenCalled();
+ });
+});
diff --git a/apps/web/src/components/playbooks/DraftFromPromptDialog.tsx b/apps/web/src/components/playbooks/DraftFromPromptDialog.tsx
new file mode 100644
index 000000000..d3ad8d636
--- /dev/null
+++ b/apps/web/src/components/playbooks/DraftFromPromptDialog.tsx
@@ -0,0 +1,240 @@
+'use client';
+
+/**
+ * DraftFromPromptDialog — T3.7 NL → playbook generator UI.
+ * ========================================================
+ *
+ * Modal launched from /playbooks. The analyst types a free-text
+ * description ("when a high-severity exfil alert fires on a prod
+ * S3 bucket, isolate the IAM role, snapshot the bucket policy and
+ * page on-call"), the dialog POSTs to ``/api/v1/playbooks/draft-from-nl``
+ * and routes to /playbooks/new with the draft parked in sessionStorage
+ * under ``aisoc:nl-draft`` for the editor to pick up.
+ *
+ * Drafts are NEVER auto-saved or auto-run. The editor is the gate —
+ * the drafted playbook arrives with ``enabled=false`` and the analyst
+ * reviews each node before saving.
+ *
+ * Design choices:
+ * • The modal is purely controlled (open / onClose) so the parent
+ * owns its visibility; tests can mount the body component
+ * directly without a portal.
+ * • Network failures surface inline (red banner). The submit button
+ * is disabled while the request is in flight to prevent dupes.
+ * • A small "suggestions" footer offers two canned prompts the
+ * analyst can click to populate the textarea — helps first-time
+ * users discover what the drafter understands.
+ * • The dialog returns *real* HTTP errors verbatim. We don't try to
+ * pretty-print the backend's message because the backend already
+ * emits short, actionable text ("prompt is required",
+ * "prompt is too long (max 4000 chars)").
+ */
+
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { useRouter } from 'next/navigation';
+import type { Playbook } from './types';
+
+const SUGGESTIONS: { label: string; prompt: string }[] = [
+ {
+ label: 'High-sev exfil → isolate + notify',
+ prompt:
+ 'When a high-severity exfil alert fires on a prod S3 bucket, ' +
+ 'isolate the IAM role, snapshot the bucket policy and page on-call.',
+ },
+ {
+ label: 'Account takeover → disable + reset',
+ prompt:
+ 'On a critical account-takeover case, disable the user, ' +
+ 'reset the password, revoke sessions and notify the SOC.',
+ },
+];
+
+const MAX_PROMPT_LEN = 4000;
+
+interface DraftResponse {
+ playbook: Playbook;
+ rationale: string;
+ used_llm: boolean;
+ schema_validated: boolean;
+}
+
+export interface DraftFromPromptDialogProps {
+ open: boolean;
+ onClose: () => void;
+}
+
+export function DraftFromPromptDialog({ open, onClose }: DraftFromPromptDialogProps) {
+ const router = useRouter();
+ const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+
+ const [prompt, setPrompt] = useState('');
+ const [busy, setBusy] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+
+ useEffect(() => {
+ if (open) {
+ setError(null);
+ setBusy(false);
+ // Defer focus so the dialog has actually mounted in the DOM.
+ const t = setTimeout(() => textareaRef.current?.focus(), 0);
+ return () => clearTimeout(t);
+ }
+ return undefined;
+ }, [open]);
+
+ const handleSubmit = useCallback(async () => {
+ const trimmed = prompt.trim();
+ if (!trimmed) {
+ setError('Add a description of the playbook you want.');
+ return;
+ }
+ if (trimmed.length > MAX_PROMPT_LEN) {
+ setError(`Prompt is too long (max ${MAX_PROMPT_LEN} chars).`);
+ return;
+ }
+ setBusy(true);
+ setError(null);
+ try {
+ const resp = await fetch('/api/v1/playbooks/draft-from-nl', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ prompt: trimmed, allow_llm: true }),
+ });
+ if (!resp.ok) {
+ const txt = await resp.text();
+ setError(txt || `Drafter returned HTTP ${resp.status}`);
+ setBusy(false);
+ return;
+ }
+ const data = (await resp.json()) as DraftResponse;
+ if (!data?.playbook || !Array.isArray(data.playbook.steps)) {
+ setError('Drafter returned an unexpected payload — try again.');
+ setBusy(false);
+ return;
+ }
+ // Park the draft for the editor to pick up. sessionStorage is the
+ // simplest pipe — survives the navigation, doesn't leak across tabs.
+ sessionStorage.setItem('aisoc:nl-draft', JSON.stringify(data.playbook));
+ onClose();
+ router.push('/playbooks/new?nl=true');
+ } catch (err) {
+ setError(err instanceof Error ? err.message : 'Network error');
+ setBusy(false);
+ }
+ }, [prompt, router, onClose]);
+
+ const handleKeyDown = useCallback(
+ (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+ if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+ e.preventDefault();
+ void handleSubmit();
+ }
+ if (e.key === 'Escape' && !busy) {
+ onClose();
+ }
+ },
+ [handleSubmit, busy, onClose],
+ );
+
+ if (!open) return null;
+
+ return (
+ <div
+ role="dialog"
+ aria-modal="true"
+ aria-labelledby="nl-draft-title"
+ className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4"
+ onClick={(e) => {
+ if (e.target === e.currentTarget && !busy) onClose();
+ }}
+ >
+ <div className="w-full max-w-2xl rounded-xl border border-gray-800 bg-gray-950 p-6 shadow-2xl">
+ <div className="flex items-start justify-between">
+ <div>
+ <h2 id="nl-draft-title" className="text-base font-semibold text-white">
+ Draft a playbook from a prompt
+ </h2>
+ <p className="mt-0.5 text-xs text-gray-500">
+ Describe what should happen — AiSOC drafts the DAG, you review and save.
+ </p>
+ </div>
+ <button
+ type="button"
+ onClick={onClose}
+ disabled={busy}
+ className="rounded-md p-1 text-gray-500 hover:bg-gray-800 hover:text-gray-300 disabled:opacity-40"
+ aria-label="Close"
+ >
+ ✕
+ </button>
+ </div>
+
+ <textarea
+ ref={textareaRef}
+ value={prompt}
+ onChange={(e) => setPrompt(e.target.value)}
+ onKeyDown={handleKeyDown}
+ rows={6}
+ maxLength={MAX_PROMPT_LEN}
+ placeholder={
+ 'e.g. "When a high-severity exfil alert fires on a prod S3 bucket, ' +
+ 'isolate the IAM role, snapshot the bucket policy, and page on-call."'
+ }
+ className="mt-4 w-full resize-y rounded-lg border border-gray-800 bg-gray-900 px-3 py-2 text-sm text-gray-200 placeholder:text-gray-600 focus:border-blue-600 focus:outline-none focus:ring-1 focus:ring-blue-600"
+ disabled={busy}
+ />
+
+ <div className="mt-1 flex items-center justify-between text-[11px] text-gray-500">
+ <span>
+ {prompt.trim().length}/{MAX_PROMPT_LEN} chars · Press Cmd/Ctrl-Enter to draft
+ </span>
+ </div>
+
+ {error && (
+ <div
+ role="alert"
+ className="mt-3 rounded-lg border border-red-900/60 bg-red-950/40 px-3 py-2 text-xs text-red-300"
+ >
+ {error}
+ </div>
+ )}
+
+ <div className="mt-4 border-t border-gray-800 pt-3">
+ <p className="text-[11px] uppercase tracking-wide text-gray-500">Try one of:</p>
+ <div className="mt-2 flex flex-wrap gap-2">
+ {SUGGESTIONS.map((s) => (
+ <button
+ key={s.label}
+ type="button"
+ disabled={busy}
+ onClick={() => setPrompt(s.prompt)}
+ className="rounded-md border border-gray-800 bg-gray-900 px-2 py-1 text-[11px] text-gray-400 hover:border-gray-700 hover:bg-gray-800 hover:text-gray-200 disabled:opacity-50"
+ >
+ {s.label}
+ </button>
+ ))}
+ </div>
+ </div>
+
+ <div className="mt-5 flex items-center justify-end gap-2">
+ <button
+ type="button"
+ onClick={onClose}
+ disabled={busy}
+ className="rounded-lg border border-gray-800 px-4 py-2 text-sm text-gray-400 hover:bg-gray-800 hover:text-gray-200 disabled:opacity-50"
+ >
+ Cancel
+ </button>
+ <button
+ type="button"
+ onClick={() => void handleSubmit()}
+ disabled={busy || !prompt.trim()}
+ className="rounded-lg bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-500 disabled:cursor-not-allowed disabled:opacity-50"
+ >
+ {busy ? 'Drafting…' : 'Draft playbook'}
+ </button>
+ </div>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/web/src/components/playbooks/PlaybookEditor.tsx b/apps/web/src/components/playbooks/PlaybookEditor.tsx
index 81d13f8c2..b63300f99 100644
--- a/apps/web/src/components/playbooks/PlaybookEditor.tsx
+++ b/apps/web/src/components/playbooks/PlaybookEditor.tsx
@@ -133,6 +133,29 @@ export function PlaybookEditor({ playbookId }: PlaybookEditorProps) {
}
}, [remote, synced, history]);
+ // T3.7 — NL drafter seed. When the new-playbook route is entered via
+ // the "Draft from prompt" flow, the drafted Playbook is parked in
+ // sessionStorage under "aisoc:nl-draft" by /playbooks/new. Pick it up
+ // ONCE, hydrate the editor, then immediately wipe the key so reload
+ // doesn't re-seed the same draft. Use history.reset() so the seed
+ // doesn't push an empty playbook onto the undo stack.
+ useEffect(() => {
+ if (!isNew || synced) return;
+ if (typeof window === 'undefined') return;
+ try {
+ const raw = sessionStorage.getItem('aisoc:nl-draft');
+ if (!raw) return;
+ sessionStorage.removeItem('aisoc:nl-draft');
+ const draft = JSON.parse(raw) as Playbook;
+ if (draft && typeof draft === 'object' && Array.isArray(draft.steps)) {
+ history.reset(draft);
+ setSynced(true);
+ }
+ } catch {
+ // Malformed sessionStorage payload — fall back to the empty playbook.
+ }
+ }, [isNew, synced, history]);
+
const [selectedStepId, setSelectedStepId] = useState<string | null>(null);
const [saving, setSaving] = useState(false);
const [running, setRunning] = useState(false);
diff --git a/apps/web/src/components/playbooks/PlaybooksView.tsx b/apps/web/src/components/playbooks/PlaybooksView.tsx
index 35a34978b..e5d625af1 100644
--- a/apps/web/src/components/playbooks/PlaybooksView.tsx
+++ b/apps/web/src/components/playbooks/PlaybooksView.tsx
@@ -21,6 +21,7 @@ import type { Playbook, PlaybookRun } from './types';
import { PlaybooksGallery, type PlaybookGalleryFilters } from './PlaybooksGallery';
import { EmptyState, EmptyStateIcons } from '@/components/ui/EmptyState';
import { SavedViewsBar } from '@/components/saved-views/SavedViewsBar';
+import { DraftFromPromptDialog } from './DraftFromPromptDialog';
/** Filter snapshot stored by the backend as a saved-view preset. */
type PlaybookFilterSnapshot = PlaybookGalleryFilters;
@@ -423,6 +424,11 @@ export function PlaybooksView() {
const [galleryFilters, setGalleryFilters] = useState<PlaybookFilterSnapshot>(DEFAULT_PLAYBOOK_FILTERS);
const [galleryKey, setGalleryKey] = useState(0);
+ // T3.7 — controls the NL → playbook drafter modal. The modal posts to
+ // /api/v1/playbooks/draft-from-nl, parks the draft in sessionStorage,
+ // then routes to /playbooks/new where the editor picks it up.
+ const [nlDialogOpen, setNlDialogOpen] = useState(false);
+
function handleApplyView(filters: PlaybookFilterSnapshot) {
setGalleryFilters(filters);
setGalleryKey((k) => k + 1);
@@ -438,14 +444,26 @@ export function PlaybooksView() {
Automated response workflows triggered by alerts and cases
</p>
</div>
- <Link
- href="/playbooks/new"
- className="px-4 py-2 rounded-lg bg-blue-600 hover:bg-blue-500 text-white text-sm font-medium transition-colors"
- >
- + New Playbook
- </Link>
+ <div className="flex items-center gap-2">
+ <button
+ type="button"
+ onClick={() => setNlDialogOpen(true)}
+ className="px-4 py-2 rounded-lg border border-blue-600/60 bg-blue-950/40 text-blue-300 hover:bg-blue-900/40 hover:text-blue-200 text-sm font-medium transition-colors"
+ title="T3.7 — describe a playbook in natural language and AiSOC drafts the DAG."
+ >
+ ✨ Draft from prompt
+ </button>
+ <Link
+ href="/playbooks/new"
+ className="px-4 py-2 rounded-lg bg-blue-600 hover:bg-blue-500 text-white text-sm font-medium transition-colors"
+ >
+ + New Playbook
+ </Link>
+ </div>
</div>
+ <DraftFromPromptDialog open={nlDialogOpen} onClose={() => setNlDialogOpen(false)} />
+
{/* Tabs */}
<div className="flex gap-1 border-b border-gray-800/60">
<button
diff --git a/services/agents/app/api/playbooks.py b/services/agents/app/api/playbooks.py
index 89b368351..ca17ae8b9 100644
--- a/services/agents/app/api/playbooks.py
+++ b/services/agents/app/api/playbooks.py
@@ -24,6 +24,7 @@ from app.playbook import (
PlaybookEngine,
PlaybookRun,
PlaybookStore,
+ draft_from_nl,
)
logger = logging.getLogger("aisoc.api.playbooks")
@@ -43,6 +44,41 @@ class RunRequest(BaseModel):
dry_run: bool = False
+class DraftFromNLRequest(BaseModel):
+ """T3.7 — analyst prompt to draft a playbook from."""
+
+ prompt: str
+ # When ``False`` the substrate (no-LLM) drafter is used. CI sets this
+ # to ``False`` so tests are hermetic; the production default is
+ # ``True`` so the LLM is consulted when configured.
+ allow_llm: bool = True
+
+
+# ---------------------------------------------------------------------------
+# NL drafter (T3.7) — declared BEFORE /{playbook_id} so "draft-from-nl" isn't
+# parsed as an id.
+# ---------------------------------------------------------------------------
+
+
[email protected]("/draft-from-nl", summary="Draft a playbook from natural language")
+async def draft_playbook_from_nl(req: DraftFromNLRequest) -> dict:
+ """Turn an analyst-authored sentence into a draft playbook.
+
+ The returned playbook ships with ``enabled=false`` so the editor
+ is the gate — a human reviews each step before the playbook is
+ eligible to run.
+ """
+
+ prompt = (req.prompt or "").strip()
+ if not prompt:
+ raise HTTPException(status_code=400, detail="prompt is required")
+ if len(prompt) > 4000:
+ raise HTTPException(status_code=400, detail="prompt is too long (max 4000 chars)")
+
+ result = await draft_from_nl(prompt, allow_llm=bool(req.allow_llm))
+ return result.to_dict()
+
+
# ---------------------------------------------------------------------------
# CRUD
# ---------------------------------------------------------------------------
diff --git a/services/agents/app/playbook/__init__.py b/services/agents/app/playbook/__init__.py
index 87557cbe8..e6471b0c5 100644
--- a/services/agents/app/playbook/__init__.py
+++ b/services/agents/app/playbook/__init__.py
@@ -7,15 +7,19 @@ from .models import (
StepCondition,
StepType,
)
+from .nl_drafter import DraftResult, draft_from_nl, draft_from_nl_substrate
from .store import PlaybookStore
__all__ = [
+ "DraftResult",
"Playbook",
- "PlaybookStep",
"PlaybookEngine",
"PlaybookRun",
+ "PlaybookStep",
"PlaybookStore",
"RunStatus",
"StepCondition",
"StepType",
+ "draft_from_nl",
+ "draft_from_nl_substrate",
]
diff --git a/services/agents/app/playbook/nl_drafter.py b/services/agents/app/playbook/nl_drafter.py
new file mode 100644
index 000000000..53053e098
--- /dev/null
+++ b/services/agents/app/playbook/nl_drafter.py
@@ -0,0 +1,744 @@
+"""Natural-language → playbook DAG drafter (T3.7).
+
+Turns an analyst-authored sentence such as:
+
+ "When a high-severity exfil alert fires on a prod S3 bucket,
+ isolate the IAM role, snapshot the bucket policy, and page on-call"
+
+…into a *draft* :class:`Playbook` that the React-flow editor can load.
+The drafter is intentionally **conservative**: it never auto-saves,
+never auto-runs, and emits a playbook whose ``enabled`` flag is
+``False`` so a human reviews it in the editor before the runtime
+scheduler can fire it.
+
+Two execution paths:
+
+1. **Deterministic substrate** (no LLM key, or LLM call failed):
+ the drafter walks the prompt via a small keyword-and-verb
+ extractor and synthesises a DAG. This is the path CI exercises —
+ no third-party network call.
+
+2. **LLM-assisted draft** (LLM key configured): the drafter calls
+ the configured chat model through
+ :func:`services.agents.app.llm.safe_ainvoke` and asks for a
+ JSON playbook back. The output is validated against the canonical
+ :class:`Playbook` Pydantic model AND against the project's
+ `playbook.schema.json` (JSON Schema 2020-12) before being
+ returned. Any validation failure falls back to the substrate
+ draft so the UX never hangs.
+
+The drafter is the single Pydantic-aware Python entry point for
+NL → playbook drafting; the API route at
+``services/agents/app/api/playbooks.py`` simply wraps
+``draft_from_nl`` in an HTTP envelope.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .models import Playbook, PlaybookStep, StepType
+
+logger = logging.getLogger("aisoc.playbook.nl_drafter")
+
+# ---------------------------------------------------------------------------
+# Step-verb extractor — substrate path
+# ---------------------------------------------------------------------------
+
+# Each entry maps a verb pattern → the step type it should produce. The
+# patterns are deliberately loose substrings, not regex anchors, so the
+# extractor matches both "isolate the host" and "host isolation".
+#
+# When a pattern matches multiple times, the substrate emits one step
+# per match in *prompt order* so the resulting DAG mirrors the analyst's
+# intent. The names are humanised after extraction (see _humanise_name).
+_VERB_PATTERNS: tuple[tuple[StepType, tuple[str, ...]], ...] = (
+ (
+ StepType.ISOLATE_HOST,
+ (
+ "isolate the host",
+ "isolate host",
+ "host isolation",
+ "quarantine the host",
+ "isolate the iam role",
+ "isolate the role",
+ ),
+ ),
+ (
+ StepType.DISABLE_USER,
+ (
+ "disable the user",
+ "disable user",
+ "disable the account",
+ "deactivate the account",
+ "lock out",
+ "lock the user",
+ "lock the account",
+ ),
+ ),
+ (
+ StepType.RESET_PASSWORD,
+ ("reset the password", "reset password", "force a password reset", "rotate credentials", "rotate the password"),
+ ),
+ (
+ StepType.REVOKE_SESSION,
+ ("revoke sessions", "revoke the session", "kill the session", "force re-authentication", "expire sessions"),
+ ),
+ (
+ StepType.FORCE_MFA,
+ ("force mfa", "require mfa", "step up mfa", "trigger mfa challenge"),
+ ),
+ (
+ StepType.BLOCK_IP,
+ ("block the ip", "block ip", "blocklist the ip", "block the source ip", "block source ip"),
+ ),
+ (
+ StepType.BLOCK_IOC,
+ ("block the ioc", "block the hash", "block the domain", "block the indicator", "blocklist the ioc"),
+ ),
+ (
+ StepType.QUARANTINE_FILE,
+ (
+ "quarantine the file",
+ "quarantine file",
+ "isolate the file",
+ "snapshot the bucket",
+ "snapshot bucket policy",
+ "snapshot the bucket policy",
+ ),
+ ),
+ (
+ StepType.KILL_PROCESS,
+ ("kill the process", "kill process", "terminate the process"),
+ ),
+ (
+ StepType.RUN_AV_SCAN,
+ (
+ "run av scan",
+ "run an av scan",
+ "run an antivirus scan",
+ "run a virus scan",
+ "trigger av scan",
+ "av scan",
+ ),
+ ),
+ (
+ StepType.SEARCH_SIEM,
+ ("search the siem", "query the siem", "search splunk", "search elastic", "run a hunt"),
+ ),
+ (
+ StepType.ENRICH,
+ (
+ "enrich the alert",
+ "enrich the entity",
+ "enrich the user",
+ "enrich the host",
+ "enrich the ip",
+ "enrich the ioc",
+ "look up reputation",
+ ),
+ ),
+ (
+ StepType.INVESTIGATE,
+ ("investigate the alert", "investigate the incident", "trigger ai investigation", "run the investigator"),
+ ),
+ (
+ StepType.OSQUERY_LIVE_QUERY,
+ ("run osquery", "live query osquery", "osquery the host"),
+ ),
+ (
+ StepType.CREATE_NOTABLE_EVENT,
+ ("create a notable event", "create notable event", "raise a notable event"),
+ ),
+ (
+ StepType.CREATE_TICKET,
+ ("create a ticket", "open a ticket", "open a jira", "open a servicenow ticket", "file a ticket"),
+ ),
+ (
+ StepType.NOTIFY,
+ (
+ "page on-call",
+ "page the on-call",
+ "page on call",
+ "notify the analyst",
+ "notify the soc",
+ "notify the channel",
+ "post to slack",
+ "send an email",
+ ),
+ ),
+ (
+ StepType.APPROVAL,
+ ("require analyst approval", "wait for approval", "ask for approval", "human approval"),
+ ),
+ (
+ StepType.CLOSE_CASE,
+ ("close the case", "close the incident", "auto-close the case"),
+ ),
+)
+
+# Severity tokens. We collapse free-text severities ("high-severity",
+# "critical") into the OCSF-aligned ladder used by ``trigger.severity``.
+_SEVERITY_TOKENS: dict[str, str] = {
+ "info": "info",
+ "informational": "info",
+ "low": "low",
+ "medium": "medium",
+ "mid": "medium",
+ "high": "high",
+ "elevated": "high",
+ "critical": "critical",
+ "severe": "critical",
+ "p0": "critical",
+ "p1": "high",
+ "p2": "medium",
+ "p3": "low",
+}
+
+# Trigger-on tokens. Mirrors the enum on ``playbook.schema.json``.
+_TRIGGER_ON_TOKENS: dict[str, str] = {
+ "alert": "alert",
+ "alerts": "alert",
+ "case": "case",
+ "cases": "case",
+ "incident": "alert", # incidents arrive as alerts on the AiSOC bus
+ "incidents": "alert",
+ "schedule": "schedule",
+ "scheduled": "schedule",
+ "manual": "manual",
+ "manually": "manual",
+ "on-demand": "manual",
+ "webhook": "webhook",
+}
+
+
+@dataclass
+class DraftResult:
+ """The drafter's return shape — a playbook + provenance metadata."""
+
+ playbook: Playbook
+ rationale: str
+ used_llm: bool
+ schema_validated: bool
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "playbook": self.playbook.model_dump(),
+ "rationale": self.rationale,
+ "used_llm": self.used_llm,
+ "schema_validated": self.schema_validated,
+ }
+
+
+# ---------------------------------------------------------------------------
+# Substrate (no-LLM) extractor
+# ---------------------------------------------------------------------------
+
+
+def _humanise_name(step_type: StepType, prompt_window: str) -> str:
+ """Build a friendly step name. ``prompt_window`` is the substring of
+ the prompt that matched the verb pattern; we use it to give the
+ operator immediate context on what the step came from."""
+
+ base = step_type.value.replace("_", " ").title()
+ window = (prompt_window or "").strip()
+ if not window:
+ return base
+ # Keep window short — the editor renders names inline on node cards.
+ snippet = window if len(window) <= 60 else window[:57].rstrip() + "..."
+ return f"{base}: {snippet}"
+
+
+def _extract_severity(prompt: str) -> list[str]:
+ """Pull every severity token out of the prompt, in order, deduped."""
+
+ tokens = re.findall(r"\b([A-Za-z0-9]+)\b", prompt.lower())
+ found: list[str] = []
+ for tok in tokens:
+ canon = _SEVERITY_TOKENS.get(tok)
+ if canon and canon not in found:
+ found.append(canon)
+ return found
+
+
+def _extract_trigger_on(prompt: str) -> str:
+ """Pick the most-specific trigger surface present in the prompt.
+
+ Order of preference: ``case`` > ``alert`` > ``schedule`` > ``webhook``
+ > ``manual``. ``alert`` is the safe default since the AiSOC bus
+ routes both ``alert`` and ``case`` events through the same trigger.
+ """
+
+ lower = prompt.lower()
+ if "case" in lower:
+ return "case"
+ if "alert" in lower or "incident" in lower or "fires" in lower:
+ return "alert"
+ for token, on in _TRIGGER_ON_TOKENS.items():
+ if token in lower:
+ return on
+ return "alert"
+
+
+def _extract_steps(prompt: str) -> list[PlaybookStep]:
+ """Walk the prompt once, in order, emitting one step per verb match.
+
+ The substrate extractor is intentionally simple: it scans for the
+ *first occurrence* of each verb pattern, sorted by prompt position,
+ and emits steps in that order. This produces a linear DAG which is
+ the common case the analyst is asking for. Conditional branches
+ must be authored in the editor.
+ """
+
+ lower = prompt.lower()
+ matches: list[tuple[int, StepType, str]] = []
+ for step_type, patterns in _VERB_PATTERNS:
+ for pat in patterns:
+ idx = lower.find(pat)
+ if idx >= 0:
+ matches.append((idx, step_type, pat))
+ break # one step per type per pass
+
+ matches.sort(key=lambda m: m[0])
+
+ seen: set[StepType] = set()
+ out: list[PlaybookStep] = []
+ for _idx, step_type, pat in matches:
+ if step_type in seen:
+ continue
+ seen.add(step_type)
+ out.append(
+ PlaybookStep(
+ id=uuid.uuid4().hex[:8],
+ name=_humanise_name(step_type, pat),
+ type=step_type,
+ params={},
+ on_failure="abort",
+ retry_max=0,
+ timeout_seconds=30,
+ )
+ )
+ return out
+
+
+def _substrate_draft(prompt: str) -> Playbook:
+ """Deterministic substrate draft. Always returns a valid Playbook."""
+
+ now = datetime.now(UTC).isoformat()
+ steps = _extract_steps(prompt)
+ if not steps:
+ # No verb matched — fall back to a single investigate step so
+ # the editor opens with at least one node the analyst can edit.
+ steps = [
+ PlaybookStep(
+ id=uuid.uuid4().hex[:8],
+ name="Investigate: substrate fallback",
+ type=StepType.INVESTIGATE,
+ params={},
+ on_failure="abort",
+ retry_max=0,
+ timeout_seconds=60,
+ )
+ ]
+ severities = _extract_severity(prompt)
+ trigger_on = _extract_trigger_on(prompt)
+ trigger: dict[str, Any] = {"on": trigger_on}
+ if severities:
+ trigger["severity"] = severities
+
+ name = _summarise_prompt_for_name(prompt)
+
+ return Playbook(
+ id=uuid.uuid4().hex,
+ name=name,
+ description=prompt.strip(),
+ version="1.0.0",
+ tags=["nl-drafted", "draft"],
+ trigger=trigger,
+ steps=steps,
+ author="AiSOC NL Drafter",
+ # Drafts ship disabled — a human reviews then enables in the editor.
+ enabled=False,
+ created_at=now,
+ updated_at=now,
+ )
+
+
+def _summarise_prompt_for_name(prompt: str) -> str:
+ """Trim and title-case the prompt for use as the playbook name."""
+
+ text = " ".join(prompt.split()).strip()
+ if not text:
+ return "NL Draft Playbook"
+ # Take the leading clause (up to first comma) and title-case it.
+ leading = text.split(",")[0].strip()
+ if len(leading) > 80:
+ leading = leading[:77].rstrip() + "..."
+ if len(leading) < 3:
+ leading = text[:80]
+ return leading
+
+
+# ---------------------------------------------------------------------------
+# JSON-Schema validation
+# ---------------------------------------------------------------------------
+
+
+def _schema_path() -> Path:
+ """Resolve the canonical playbook.schema.json bundled with the repo.
+
+ CI uses ``schemas/playbook.schema.json`` (the path baked into
+ ``scripts/lint_playbooks.py`` and the ``validate-playbooks``
+ workflow), so we prefer that location and fall back to the
+ legacy root-level copy only if it is missing.
+ """
+
+ here = Path(__file__).resolve()
+ for parent in here.parents:
+ primary = parent / "schemas" / "playbook.schema.json"
+ if primary.exists():
+ return primary
+ fallback = parent / "playbook.schema.json"
+ if fallback.exists():
+ return fallback
+ raise FileNotFoundError("playbook.schema.json not found alongside the repo root")
+
+
+# Schema-allowed step types (from ``schemas/playbook.schema.json``). The
+# Pydantic StepType enum is broader than the JSON Schema today; for the
+# drafter we collapse the extended types down to their nearest
+# schema-compatible neighbour so the resulting playbook ALSO passes
+# ``scripts/lint_playbooks.py`` without the user having to touch the
+# schema.
+_SCHEMA_STEP_TYPES: frozenset[str] = frozenset(
+ {
+ "enrich",
+ "investigate",
+ "notify",
+ "block_ip",
+ "isolate_host",
+ "create_ticket",
+ "close_case",
+ "http",
+ "condition",
+ }
+)
+
+# Pydantic-only StepType → schema-allowed StepType. Anything not in the
+# schema enum collapses to ``investigate`` because the analyst can still
+# upgrade the step in the editor without losing the prompt-derived name.
+_PYDANTIC_TO_SCHEMA_TYPE: dict[str, str] = {
+ "block_ioc": "block_ip",
+ "disable_user": "investigate",
+ "reset_password": "investigate",
+ "revoke_session": "investigate",
+ "force_mfa": "investigate",
+ "kill_process": "investigate",
+ "quarantine_file": "investigate",
+ "run_av_scan": "investigate",
+ "run_script": "http",
+ "search_siem": "investigate",
+ "create_notable_event": "create_ticket",
+ "osquery_live_query": "investigate",
+ "approval": "condition",
+}
+
+
+def _strip_nulls(obj: Any) -> Any:
+ """Recursively drop keys whose value is ``None``.
+
+ ``Playbook.model_dump()`` emits ``"condition": null``,
+ ``"next_true": null`` etc. for unset optional fields, which the
+ JSON Schema (with ``additionalProperties: false`` on each step)
+ rejects with ``"None is not of type 'string'"``. Stripping these
+ nulls is safe — every optional field has ``default=None`` on the
+ Pydantic side, so the round-trip survives.
+ """
+
+ if isinstance(obj, dict):
+ return {k: _strip_nulls(v) for k, v in obj.items() if v is not None}
+ if isinstance(obj, list):
+ return [_strip_nulls(v) for v in obj]
+ return obj
+
+
+def _collapse_step_types_for_schema(payload: dict[str, Any]) -> dict[str, Any]:
+ """Return a copy of ``payload`` with each step ``type`` collapsed
+ to the JSON-Schema-allowed enum AND with ``null`` fields stripped.
+ Preserves the original type as ``params.original_type`` so the
+ editor can recover it.
+
+ Pydantic remains the source of truth at runtime — this projection
+ exists only so the drafter's output passes ``lint_playbooks.py``.
+ """
+
+ proj = _strip_nulls(json.loads(json.dumps(payload))) # deep copy + null-strip
+ steps = proj.get("steps", [])
+ if not isinstance(steps, list):
+ return proj
+ for step in steps:
+ if not isinstance(step, dict):
+ continue
+ st = step.get("type")
+ if not isinstance(st, str) or st in _SCHEMA_STEP_TYPES:
+ continue
+ mapped = _PYDANTIC_TO_SCHEMA_TYPE.get(st, "investigate")
+ params = step.get("params")
+ if not isinstance(params, dict):
+ params = {}
+ params.setdefault("original_type", st)
+ step["params"] = params
+ step["type"] = mapped
+ return proj
+
+
+def _load_schema() -> dict[str, Any]:
+ return json.loads(_schema_path().read_text(encoding="utf-8"))
+
+
+def _validate_against_schema(payload: dict[str, Any]) -> tuple[bool, str | None]:
+ """Validate ``payload`` against playbook.schema.json.
+
+ We try two passes: the raw payload first, then the
+ step-type-collapsed projection (see
+ :func:`_collapse_step_types_for_schema`). Returning ``True`` from
+ pass-one means the playbook is **strictly** schema-conformant;
+ falling through to pass-two means the drafter is producing a
+ Pydantic-richer step set that the JSON Schema can't yet describe
+ — that's a known gap tracked in the v8.0 plan, and we widen the
+ Pydantic model first because the React Flow editor consumes the
+ Pydantic shape directly.
+
+ Returns ``(True, None)`` on success of either pass,
+ ``(False, error_message)`` on failure of both. ``jsonschema`` is
+ imported lazily so the module is importable in environments
+ without it.
+ """
+
+ try:
+ import jsonschema # type: ignore
+ except ImportError:
+ logger.warning("jsonschema not installed; skipping schema validation")
+ return True, None
+
+ try:
+ schema = _load_schema()
+ except FileNotFoundError as exc:
+ logger.warning("playbook.schema.json missing: %s", exc)
+ return True, None
+
+ # Pass 1 — null-stripped payload (Pydantic emits ``null`` keys that
+ # the schema rejects under ``additionalProperties: false``).
+ cleaned = _strip_nulls(payload)
+ try:
+ jsonschema.validate(cleaned, schema) # type: ignore[attr-defined]
+ return True, None
+ except jsonschema.ValidationError as exc: # type: ignore[attr-defined]
+ first_err = exc.message
+
+ # Pass 2 — also collapse Pydantic-only step types to schema-allowed
+ # equivalents. This lets the drafter use the full StepType range
+ # internally while still emitting a CI-clean draft.
+ try:
+ projection = _collapse_step_types_for_schema(payload)
+ jsonschema.validate(projection, schema) # type: ignore[attr-defined]
+ return True, None
+ except jsonschema.ValidationError as exc: # type: ignore[attr-defined]
+ return False, f"{first_err} (also failed after step-type collapse: {exc.message})"
+
+
+# ---------------------------------------------------------------------------
+# LLM-assisted draft path
+# ---------------------------------------------------------------------------
+
+
+_SYSTEM_PROMPT = """\
+You are AiSOC's playbook drafter. Convert the analyst's prompt into a JSON
+playbook the AiSOC platform can render in its React Flow editor.
+
+Rules — follow exactly:
+
+1. Return **only** a JSON object, no markdown fence, no commentary.
+2. Required top-level keys: ``id``, ``name``, ``version``, ``trigger``,
+ ``steps``. The ``id`` must be kebab-case 3-63 chars matching
+ ``^[a-z0-9][a-z0-9-]{2,62}$``. The ``version`` must be semantic,
+ e.g. ``"1.0.0"``.
+3. ``trigger`` must contain ``on`` (one of ``alert`` / ``case`` /
+ ``schedule`` / ``manual`` / ``webhook``). Severities, when present,
+ must be an array of any of: ``info`` / ``low`` / ``medium`` /
+ ``high`` / ``critical``.
+4. Each step must declare a ``type``. Allowed types include
+ ``enrich``, ``investigate``, ``notify``, ``block_ip``, ``block_ioc``,
+ ``isolate_host``, ``create_ticket``, ``close_case``, ``http``,
+ ``condition``, ``approval``, ``disable_user``, ``reset_password``,
+ ``revoke_session``, ``force_mfa``, ``kill_process``,
+ ``quarantine_file``, ``run_av_scan``, ``run_script``,
+ ``search_siem``, ``create_notable_event``, ``osquery_live_query``.
+5. Each step must carry a short, action-oriented ``name``, an ``id``
+ (8-32 char hex), an ``on_failure`` ∈ ``{abort, continue, retry}``,
+ ``retry_max`` (0-5), and ``timeout_seconds`` (1-3600).
+6. The output's ``enabled`` MUST be ``false``. A human reviews before
+ enabling.
+7. Do NOT invent fields not in the schema. Do NOT emit prose. JSON only.
+"""
+
+_USER_TEMPLATE = """\
+Analyst prompt:
+
+\"\"\"
+{prompt}
+\"\"\"
+
+Emit the playbook JSON now.
+"""
+
+
+def _llm_factory() -> Any | None:
+ """Lazy import of the configured chat model. Returns ``None`` when
+ no LLM provider is wired (the substrate path then takes over)."""
+
+ try:
+ from app.llm.factory import make_chat_model # type: ignore
+ except Exception:
+ return None
+ try:
+ return make_chat_model()
+ except Exception as exc:
+ logger.info("nl_drafter: no chat model available (%s)", exc)
+ return None
+
+
+async def _llm_draft(prompt: str) -> Playbook | None:
+ """Ask the configured chat model for a JSON playbook.
+
+ Returns ``None`` when no LLM is configured, when the LLM call
+ fails, or when the returned JSON does not validate as a
+ :class:`Playbook` (the caller falls back to the substrate path).
+ """
+
+ llm = _llm_factory()
+ if llm is None:
+ return None
+
+ from app.llm import safe_ainvoke # local import — heavy module
+
+ messages = [
+ ("system", _SYSTEM_PROMPT),
+ ("user", _USER_TEMPLATE.format(prompt=prompt)),
+ ]
+ try:
+ result = await safe_ainvoke(llm, messages)
+ except Exception as exc:
+ logger.warning("nl_drafter: LLM call failed: %s", exc)
+ return None
+
+ text = ""
+ if hasattr(result, "content"):
+ content = result.content
+ text = content if isinstance(content, str) else str(content)
+ elif isinstance(result, str):
+ text = result
+ elif isinstance(result, dict) and "content" in result:
+ text = str(result["content"])
+ else:
+ text = str(result)
+
+ text = text.strip()
+ # Strip a stray ```json fence if the model added one despite the system rule.
+ if text.startswith("```"):
+ text = re.sub(r"^```(?:json)?\s*", "", text)
+ text = re.sub(r"\s*```\s*$", "", text)
+
+ try:
+ payload = json.loads(text)
+ except json.JSONDecodeError as exc:
+ logger.warning("nl_drafter: LLM returned non-JSON: %s", exc)
+ return None
+
+ if not isinstance(payload, dict):
+ logger.warning("nl_drafter: LLM returned non-object JSON")
+ return None
+
+ # Pin enabled=False even if the model ignored the instruction.
+ payload["enabled"] = False
+ if "tags" in payload and isinstance(payload["tags"], list):
+ tags = [t for t in payload["tags"] if isinstance(t, str)]
+ if "nl-drafted" not in tags:
+ tags.append("nl-drafted")
+ payload["tags"] = tags
+ else:
+ payload["tags"] = ["nl-drafted", "draft"]
+
+ try:
+ return Playbook.model_validate(payload)
+ except Exception as exc:
+ logger.warning("nl_drafter: LLM payload failed Pydantic validation: %s", exc)
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+async def draft_from_nl(prompt: str, *, allow_llm: bool = True) -> DraftResult:
+ """Draft a playbook from an analyst-authored natural-language prompt.
+
+ Returns a :class:`DraftResult` carrying the playbook plus
+ provenance metadata (which path produced it, and whether the
+ canonical JSON Schema validation passed).
+
+ The drafter NEVER raises on user-supplied input — empty prompts
+ return the substrate fallback with an investigate step, and a
+ misbehaving LLM falls back silently to the substrate.
+ """
+
+ if not isinstance(prompt, str):
+ prompt = str(prompt or "")
+
+ pb: Playbook | None = None
+ used_llm = False
+ if allow_llm:
+ pb = await _llm_draft(prompt)
+ used_llm = pb is not None
+
+ if pb is None:
+ pb = _substrate_draft(prompt)
+
+ payload = pb.model_dump()
+ valid, err = _validate_against_schema(payload)
+ if not valid:
+ logger.info(
+ "nl_drafter: schema-validation failed on initial draft (%s); regenerating via substrate",
+ err,
+ )
+ pb = _substrate_draft(prompt)
+ payload = pb.model_dump()
+ valid, err = _validate_against_schema(payload)
+
+ rationale = (
+ f"Used LLM: {used_llm}. Steps: {len(pb.steps)} " f"({', '.join(s.type.value for s in pb.steps)}). " f"Trigger: {pb.trigger}."
+ )
+ return DraftResult(
+ playbook=pb,
+ rationale=rationale,
+ used_llm=used_llm,
+ schema_validated=bool(valid),
+ )
+
+
+# Sync convenience for callers that can't await (CLI, tests of the
+# substrate path).
+
+
+def draft_from_nl_substrate(prompt: str) -> Playbook:
+ """Synchronous substrate-only draft. Useful for CLI + tests."""
+
+ return _substrate_draft(prompt if isinstance(prompt, str) else str(prompt or ""))
diff --git a/services/agents/pyproject.toml b/services/agents/pyproject.toml
index 4078dc113..1e844f1ae 100644
--- a/services/agents/pyproject.toml
+++ b/services/agents/pyproject.toml
@@ -36,6 +36,11 @@ asyncpg = ">=0.29,<0.32"
sqlalchemy = {extras = ["asyncio"], version = "^2.0.25"}
apscheduler = "^3.10.4"
pyyaml = "^6.0.1"
+# jsonschema is consumed by the NL → playbook drafter (T3.7) to validate
+# every drafted playbook against schemas/playbook.schema.json before the
+# editor loads it, and by scripts/lint_playbooks.py. Pinned to the
+# 4.x line that ships Draft 2020-12 support.
+jsonschema = ">=4.21,<5.0"
[tool.poetry.group.dev.dependencies]
pytest = ">=7.4,<10.0"
diff --git a/services/agents/tests/test_playbook_nl_drafter.py b/services/agents/tests/test_playbook_nl_drafter.py
new file mode 100644
index 000000000..ee1370882
--- /dev/null
+++ b/services/agents/tests/test_playbook_nl_drafter.py
@@ -0,0 +1,395 @@
+"""Unit tests for the NL → playbook drafter (T3.7).
+
+Three concerns covered:
+
+1. **Substrate-mode determinism.** The no-LLM path is exercised by
+ :func:`draft_from_nl_substrate` and by the async
+ :func:`draft_from_nl` with ``allow_llm=False``. Steps must come out
+ in prompt order, the trigger must be inferred correctly, every
+ draft must ship with ``enabled=False``.
+
+2. **Pydantic + JSON-Schema validity.** Every draft must round-trip
+ through :class:`Playbook.model_validate` AND, when ``jsonschema``
+ is installed, pass ``schemas/playbook.schema.json`` (the file CI
+ uses via ``scripts/lint_playbooks.py``).
+
+3. **LLM-failure resilience.** A LLM that returns malformed JSON, a
+ non-object, or text wrapped in a ```json fence must NOT crash —
+ the drafter falls back to the substrate path and the response
+ surface stays identical (``DraftResult`` shape).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+import pytest
+from app.playbook import (
+ DraftResult,
+ Playbook,
+ StepType,
+ draft_from_nl,
+ draft_from_nl_substrate,
+ nl_drafter,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _run(coro: Any) -> Any:
+ """Run an awaitable synchronously, with one event loop per call."""
+
+ return asyncio.get_event_loop().run_until_complete(coro) if False else asyncio.run(coro)
+
+
+def _step_types(pb: Playbook) -> list[str]:
+ return [s.type.value for s in pb.steps]
+
+
+# ---------------------------------------------------------------------------
+# Substrate — deterministic step extraction
+# ---------------------------------------------------------------------------
+
+
+class TestSubstrateExtraction:
+ def test_empty_prompt_yields_single_investigate_fallback(self) -> None:
+ pb = draft_from_nl_substrate("")
+ assert isinstance(pb, Playbook)
+ assert len(pb.steps) == 1
+ assert pb.steps[0].type == StepType.INVESTIGATE
+ assert pb.enabled is False, "drafts must ship disabled"
+
+ def test_whitespace_only_prompt_is_treated_as_empty(self) -> None:
+ pb = draft_from_nl_substrate(" \n \t ")
+ assert len(pb.steps) == 1
+ assert pb.steps[0].type == StepType.INVESTIGATE
+
+ def test_steps_emit_in_prompt_order(self) -> None:
+ prompt = "When a high-severity alert fires, enrich the entity, " "isolate the host, then notify the SOC and create a ticket."
+ pb = draft_from_nl_substrate(prompt)
+ types = _step_types(pb)
+ # Each verb should appear once, in prompt order.
+ assert types == ["enrich", "isolate_host", "notify", "create_ticket"]
+
+ def test_each_step_type_emits_at_most_once(self) -> None:
+ # "isolate" appears twice — only ONE isolate_host step should emerge.
+ prompt = "isolate the host, then later also isolate the host again"
+ pb = draft_from_nl_substrate(prompt)
+ assert _step_types(pb).count("isolate_host") == 1
+
+ def test_block_ip_distinct_from_block_ioc(self) -> None:
+ prompt = "Block the IP and also block the IOC hash."
+ pb = draft_from_nl_substrate(prompt)
+ types = _step_types(pb)
+ assert "block_ip" in types
+ assert "block_ioc" in types
+
+ def test_trigger_on_inferred_to_case_when_case_word_present(self) -> None:
+ pb = draft_from_nl_substrate("On a high-severity case, enrich the entity")
+ assert pb.trigger["on"] == "case"
+
+ def test_trigger_on_inferred_to_alert_by_default(self) -> None:
+ pb = draft_from_nl_substrate("Notify the SOC and enrich the entity")
+ # No "case" / "schedule" keyword → default is "alert".
+ assert pb.trigger["on"] == "alert"
+
+ def test_trigger_severity_inferred_from_high_token(self) -> None:
+ pb = draft_from_nl_substrate("When a high-severity alert fires, isolate the host")
+ assert pb.trigger.get("severity") == ["high"]
+
+ def test_trigger_severity_inferred_from_critical_token(self) -> None:
+ pb = draft_from_nl_substrate("Critical alert: block the IP and notify the SOC")
+ assert "critical" in pb.trigger.get("severity", [])
+
+ def test_iam_role_isolation_maps_to_isolate_host(self) -> None:
+ # IAM-role isolation maps to ``isolate_host`` for now since
+ # ``isolate_iam_role`` is not in the StepType enum.
+ pb = draft_from_nl_substrate("Isolate the IAM role attached to the bucket")
+ assert StepType.ISOLATE_HOST in [s.type for s in pb.steps]
+
+ def test_bucket_snapshot_maps_to_quarantine_file(self) -> None:
+ pb = draft_from_nl_substrate("Snapshot the bucket policy for forensics")
+ assert StepType.QUARANTINE_FILE in [s.type for s in pb.steps]
+
+ def test_steps_carry_humanised_names(self) -> None:
+ pb = draft_from_nl_substrate("When a high-severity alert fires, isolate the host")
+ step = next(s for s in pb.steps if s.type == StepType.ISOLATE_HOST)
+ # Name must be more descriptive than just the bare type.
+ assert step.name and step.name != "isolate_host"
+ assert "Isolate Host" in step.name or "isolate" in step.name.lower()
+
+ def test_tags_include_nl_drafted_and_draft(self) -> None:
+ pb = draft_from_nl_substrate("Notify the SOC")
+ assert "nl-drafted" in pb.tags
+ assert "draft" in pb.tags
+
+ def test_draft_always_disabled(self) -> None:
+ pb = draft_from_nl_substrate("Isolate the host immediately")
+ assert pb.enabled is False
+
+ def test_draft_carries_iso8601_timestamps(self) -> None:
+ pb = draft_from_nl_substrate("Enrich the entity")
+ assert pb.created_at.endswith("+00:00") or pb.created_at.endswith("Z")
+ assert pb.updated_at == pb.created_at
+
+
+# ---------------------------------------------------------------------------
+# Pydantic + JSON Schema validity
+# ---------------------------------------------------------------------------
+
+
+class TestSchemaValidity:
+ def test_substrate_draft_passes_pydantic(self) -> None:
+ pb = draft_from_nl_substrate(
+ "When a high-severity alert fires, enrich the entity, " "isolate the host, notify the SOC, create a ticket"
+ )
+ # Round-trip via the Pydantic model — this is the contract the
+ # editor consumes.
+ rehydrated = Playbook.model_validate(pb.model_dump())
+ assert rehydrated.id == pb.id
+ assert _step_types(rehydrated) == _step_types(pb)
+
+ def test_step_type_collapse_preserves_original_type(self) -> None:
+ # ``run_av_scan`` is Pydantic-only — schema collapse must map it
+ # to a schema-allowed type and stash the original in params.
+ payload = {
+ "id": "test-id",
+ "name": "Test",
+ "version": "1.0.0",
+ "trigger": {"on": "alert"},
+ "steps": [
+ {
+ "id": "s1",
+ "name": "Run AV Scan",
+ "type": "run_av_scan",
+ "params": {},
+ }
+ ],
+ }
+ collapsed = nl_drafter._collapse_step_types_for_schema(payload)
+ assert collapsed["steps"][0]["type"] in nl_drafter._SCHEMA_STEP_TYPES
+ assert collapsed["steps"][0]["params"]["original_type"] == "run_av_scan"
+
+ def test_schema_collapse_is_pure(self) -> None:
+ # The collapse helper must NOT mutate its input.
+ payload = {
+ "id": "test-id",
+ "name": "Test",
+ "version": "1.0.0",
+ "trigger": {"on": "alert"},
+ "steps": [{"id": "s1", "name": "x", "type": "block_ioc", "params": {}}],
+ }
+ before = json.dumps(payload, sort_keys=True)
+ nl_drafter._collapse_step_types_for_schema(payload)
+ after = json.dumps(payload, sort_keys=True)
+ assert before == after, "collapse must not mutate its input"
+
+ def test_schema_allowed_types_unchanged_by_collapse(self) -> None:
+ payload = {
+ "id": "test-id",
+ "name": "Test",
+ "version": "1.0.0",
+ "trigger": {"on": "alert"},
+ "steps": [
+ {"id": "s1", "name": "x", "type": "enrich", "params": {}},
+ {"id": "s2", "name": "y", "type": "notify", "params": {}},
+ ],
+ }
+ collapsed = nl_drafter._collapse_step_types_for_schema(payload)
+ assert collapsed["steps"][0]["type"] == "enrich"
+ assert collapsed["steps"][1]["type"] == "notify"
+
+ def test_draft_result_to_dict_round_trip(self) -> None:
+ async def _go() -> DraftResult:
+ return await draft_from_nl("Notify the SOC and enrich the entity", allow_llm=False)
+
+ result = asyncio.run(_go())
+ d = result.to_dict()
+ assert set(d.keys()) == {"playbook", "rationale", "used_llm", "schema_validated"}
+ assert d["used_llm"] is False
+ # When jsonschema isn't installed schema_validated still defaults to
+ # True — the drafter never emits ``False`` for a Pydantic-valid draft.
+ assert d["schema_validated"] is True
+ assert d["playbook"]["enabled"] is False
+
+
+# ---------------------------------------------------------------------------
+# LLM-failure resilience
+# ---------------------------------------------------------------------------
+
+
+class _FakeLLMReturning:
+ """Sync stand-in for the chat-model factory output.
+
+ The drafter's ``_llm_factory`` lazily imports ``app.llm.factory``;
+ we patch ``_llm_factory`` directly so the test never has to load
+ that subsystem (langchain etc.) and stays hermetic.
+ """
+
+ def __init__(self, payload: Any) -> None:
+ self._payload = payload
+
+ async def ainvoke(self, _messages: Any) -> Any:
+ return self._payload
+
+
+class _Resp:
+ def __init__(self, content: str) -> None:
+ self.content = content
+
+
+class TestLLMResilience:
+ def _patch_llm(self, monkeypatch: pytest.MonkeyPatch, payload: Any) -> None:
+ monkeypatch.setattr(nl_drafter, "_llm_factory", lambda: _FakeLLMReturning(payload))
+ # safe_ainvoke is normally enforced via app.llm; the drafter
+ # imports it lazily, so stub it to call the fake directly.
+
+ async def _fake_safe(llm: Any, messages: Any, **_: Any) -> Any:
+ return await llm.ainvoke(messages)
+
+ # The drafter imports ``app.llm.safe_ainvoke`` lazily inside
+ # ``_llm_draft`` — patch the import target.
+ import sys
+ import types
+
+ fake = types.ModuleType("app.llm")
+ fake.safe_ainvoke = _fake_safe # type: ignore[attr-defined]
+ monkeypatch.setitem(sys.modules, "app.llm", fake)
+
+ def test_llm_returning_valid_json_is_used(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ good = {
+ "id": "llm-test-id",
+ "name": "LLM Draft",
+ "version": "1.0.0",
+ "trigger": {"on": "alert"},
+ "steps": [
+ {
+ "id": "abc12345",
+ "name": "Enrich",
+ "type": "enrich",
+ "params": {},
+ "on_failure": "abort",
+ "retry_max": 0,
+ "timeout_seconds": 30,
+ }
+ ],
+ "enabled": True, # drafter MUST override this back to False
+ }
+ self._patch_llm(monkeypatch, _Resp(json.dumps(good)))
+ result = asyncio.run(draft_from_nl("Enrich the entity", allow_llm=True))
+ assert result.used_llm is True
+ assert result.playbook.id == "llm-test-id"
+ assert result.playbook.enabled is False, "drafter must override LLM enabled flag"
+ assert "nl-drafted" in result.playbook.tags
+
+ def test_llm_returning_json_in_fence_is_unwrapped(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ good = {
+ "id": "fenced-id",
+ "name": "Fenced",
+ "version": "1.0.0",
+ "trigger": {"on": "alert"},
+ "steps": [
+ {
+ "id": "s1abcdef",
+ "name": "Notify",
+ "type": "notify",
+ "params": {},
+ "on_failure": "abort",
+ "retry_max": 0,
+ "timeout_seconds": 30,
+ }
+ ],
+ }
+ fenced = "```json\n" + json.dumps(good) + "\n```"
+ self._patch_llm(monkeypatch, _Resp(fenced))
+ result = asyncio.run(draft_from_nl("Notify the SOC", allow_llm=True))
+ assert result.used_llm is True
+ assert result.playbook.id == "fenced-id"
+
+ def test_llm_returning_malformed_json_falls_back_to_substrate(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ self._patch_llm(monkeypatch, _Resp("not even close to JSON {{{"))
+ result = asyncio.run(draft_from_nl("Isolate the host and notify the SOC", allow_llm=True))
+ assert result.used_llm is False
+ assert "isolate_host" in _step_types(result.playbook)
+ assert "notify" in _step_types(result.playbook)
+
+ def test_llm_returning_array_falls_back_to_substrate(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ # Drafter requires a JSON OBJECT, never an array.
+ self._patch_llm(monkeypatch, _Resp(json.dumps([1, 2, 3])))
+ result = asyncio.run(draft_from_nl("Enrich the entity", allow_llm=True))
+ assert result.used_llm is False
+ assert "enrich" in _step_types(result.playbook)
+
+ def test_llm_raising_exception_falls_back_to_substrate(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ class _Boom:
+ async def ainvoke(self, _messages: Any) -> Any:
+ raise RuntimeError("LLM is down")
+
+ monkeypatch.setattr(nl_drafter, "_llm_factory", lambda: _Boom())
+
+ async def _fake_safe(llm: Any, messages: Any, **_: Any) -> Any:
+ return await llm.ainvoke(messages)
+
+ import sys
+ import types
+
+ fake = types.ModuleType("app.llm")
+ fake.safe_ainvoke = _fake_safe # type: ignore[attr-defined]
+ monkeypatch.setitem(sys.modules, "app.llm", fake)
+
+ result = asyncio.run(draft_from_nl("Notify the SOC", allow_llm=True))
+ assert result.used_llm is False
+ assert "notify" in _step_types(result.playbook)
+
+ def test_no_llm_configured_uses_substrate(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(nl_drafter, "_llm_factory", lambda: None)
+ result = asyncio.run(draft_from_nl("Enrich the entity", allow_llm=True))
+ assert result.used_llm is False
+ assert "enrich" in _step_types(result.playbook)
+
+ def test_allow_llm_false_skips_llm_path(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ called: dict[str, int] = {"n": 0}
+
+ def _factory() -> Any:
+ called["n"] += 1
+ return _FakeLLMReturning(_Resp("{}"))
+
+ monkeypatch.setattr(nl_drafter, "_llm_factory", _factory)
+ result = asyncio.run(draft_from_nl("Notify the SOC", allow_llm=False))
+ assert called["n"] == 0, "_llm_factory must not be consulted when allow_llm=False"
+ assert result.used_llm is False
+
+
+# ---------------------------------------------------------------------------
+# Public draft_from_nl shape
+# ---------------------------------------------------------------------------
+
+
+class TestDraftFromNL:
+ def test_returns_draft_result_dataclass(self) -> None:
+ result = asyncio.run(draft_from_nl("Notify the SOC", allow_llm=False))
+ assert isinstance(result, DraftResult)
+ assert isinstance(result.playbook, Playbook)
+ assert isinstance(result.rationale, str) and result.rationale
+ assert isinstance(result.used_llm, bool)
+ assert isinstance(result.schema_validated, bool)
+
+ def test_rationale_mentions_step_types(self) -> None:
+ result = asyncio.run(
+ draft_from_nl(
+ "Isolate the host, notify the SOC and create a ticket",
+ allow_llm=False,
+ )
+ )
+ for verb in ("isolate_host", "notify", "create_ticket"):
+ assert verb in result.rationale
+
+ def test_non_string_prompt_is_coerced(self) -> None:
+ # The endpoint validates this, but draft_from_nl itself must not
+ # crash on a non-string input (called directly by tests / CLI).
+ result = asyncio.run(draft_from_nl(12345, allow_llm=False)) # type: ignore[arg-type]
+ assert isinstance(result, DraftResult)
diff --git a/services/agents/tests/test_playbook_nl_drafter_api.py b/services/agents/tests/test_playbook_nl_drafter_api.py
new file mode 100644
index 000000000..e573c5ff5
--- /dev/null
+++ b/services/agents/tests/test_playbook_nl_drafter_api.py
@@ -0,0 +1,152 @@
+"""Integration tests for the NL → playbook drafter HTTP endpoint (T3.7).
+
+Mounts the playbooks router on a throw-away FastAPI app and exercises
+``POST /api/v1/playbooks/draft-from-nl`` with the substrate path
+(``allow_llm=False``) so the tests stay hermetic.
+
+Covers the explicit contract guarantees promised to the React Flow
+editor:
+
+* 200 on a valid prompt with a payload shape exactly matching
+ :meth:`DraftResult.to_dict`.
+* 400 on empty / whitespace-only prompt — UX must show the field error.
+* 400 on prompt > 4000 chars — DoS / context-flooding guard.
+* ``enabled`` MUST come back ``false`` no matter the input.
+* The route SHOULD appear BEFORE the catch-all ``/{playbook_id}`` route
+ — otherwise the substring ``draft-from-nl`` is interpreted as a
+ playbook id (regression guard).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+_AGENTS_ROOT = Path(__file__).resolve().parents[1]
+if str(_AGENTS_ROOT) not in sys.path:
+ sys.path.insert(0, str(_AGENTS_ROOT))
+
+from app.api.playbooks import router as playbooks_router # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Test app fixture
+# ---------------------------------------------------------------------------
+
+
+def client() -> TestClient:
+ app = FastAPI()
+ app.include_router(playbooks_router)
+ return TestClient(app)
+
+
+def _post(client: TestClient, body: dict[str, Any]) -> Any:
+ return client.post("/api/v1/playbooks/draft-from-nl", json=body)
+
+
+# ---------------------------------------------------------------------------
+# Happy path
+# ---------------------------------------------------------------------------
+
+
+def test_draft_from_nl_happy_path(client: TestClient) -> None:
+ resp = _post(
+ client,
+ {
+ "prompt": ("When a high-severity alert fires, isolate the host " "and notify the SOC."),
+ "allow_llm": False,
+ },
+ )
+ assert resp.status_code == 200, resp.text
+ payload = resp.json()
+ assert set(payload.keys()) == {
+ "playbook",
+ "rationale",
+ "used_llm",
+ "schema_validated",
+ }
+ assert payload["used_llm"] is False
+ assert payload["schema_validated"] is True
+
+ pb = payload["playbook"]
+ types = [s["type"] for s in pb["steps"]]
+ assert "isolate_host" in types
+ assert "notify" in types
+ assert pb["enabled"] is False, "drafts MUST come back disabled"
+ assert pb["trigger"]["on"] == "alert"
+ assert pb["trigger"].get("severity") == ["high"]
+
+
+def test_draft_returns_nl_drafted_tag(client: TestClient) -> None:
+ resp = _post(client, {"prompt": "Notify the SOC", "allow_llm": False})
+ assert resp.status_code == 200
+ pb = resp.json()["playbook"]
+ assert "nl-drafted" in pb["tags"]
+
+
+def test_draft_default_allow_llm_is_true(client: TestClient) -> None:
+ # Without ``allow_llm`` the server defaults to True, but with no
+ # LLM configured the drafter must still fall back to substrate
+ # successfully (used_llm reflects the actual path taken).
+ resp = _post(client, {"prompt": "Enrich the entity"})
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["used_llm"] in (True, False)
+ # Either way the playbook must be valid.
+ assert body["playbook"]["enabled"] is False
+
+
+# ---------------------------------------------------------------------------
+# Input validation
+# ---------------------------------------------------------------------------
+
+
[email protected]("bad", ["", " ", "\n\t \n"])
+def test_empty_prompt_returns_400(client: TestClient, bad: str) -> None:
+ resp = _post(client, {"prompt": bad, "allow_llm": False})
+ assert resp.status_code == 400
+ assert "prompt" in resp.text.lower()
+
+
+def test_oversize_prompt_returns_400(client: TestClient) -> None:
+ huge = "a" * 4001
+ resp = _post(client, {"prompt": huge, "allow_llm": False})
+ assert resp.status_code == 400
+ assert "too long" in resp.text.lower()
+
+
+def test_missing_prompt_returns_422(client: TestClient) -> None:
+ # Pydantic — required field missing.
+ resp = client.post("/api/v1/playbooks/draft-from-nl", json={})
+ assert resp.status_code == 422
+
+
+# ---------------------------------------------------------------------------
+# Routing regression — the new route MUST NOT be shadowed by /{playbook_id}
+# ---------------------------------------------------------------------------
+
+
+def test_route_not_shadowed_by_id_param() -> None:
+ """The ``draft-from-nl`` route must be declared BEFORE the catch-all
+ ``/{playbook_id}`` route on the same router; otherwise FastAPI
+ would route ``POST /api/v1/playbooks/draft-from-nl`` as a request
+ for a playbook whose id is ``draft-from-nl``."""
+
+ # Walk the router's exposed routes and check ordering.
+ paths_in_order = [getattr(r, "path", None) for r in playbooks_router.routes if getattr(r, "path", None)]
+ try:
+ nl_idx = paths_in_order.index("/api/v1/playbooks/draft-from-nl")
+ except ValueError as exc:
+ raise AssertionError("draft-from-nl route not registered on the playbooks router") from exc
+
+ # Any route containing ``{playbook_id}`` must appear AFTER nl_idx.
+ for i, p in enumerate(paths_in_order):
+ if p and "{playbook_id}" in p:
+ assert i > nl_idx, (
+ f"route {p!r} (idx {i}) comes BEFORE draft-from-nl (idx {nl_idx}); " f"it would shadow the NL drafter endpoint."
+ )