dna-sdk 0.1.0

package/dist/extensions/modelreg/kinds/model-profile.kind.yaml

@@ -0,0 +1,155 @@
+# ModelProfile — per-LLM-model capability/limit registry (record plane).
+# One doc per model: hard limits (instruction_token_cap, context_window,
+# tools_cap, max_output_tokens) + modalities + cost, as first-class GLOBAL
+# data so limits are project data, not implicit knowledge. Ported from the
+# internal SDK's model registry, motivated by a real outage: a 17269-token
+# voice persona silently exceeded the realtime model's 16384-token
+# session-instructions cap because the cap lived in nobody's code.
+#
+# CONTRACT — never hardcode token caps: the prompt-budget write guard
+# (dna/extensions/helix/write_guards.py :: prompt_budget_guard and its TS
+# twin) reads instruction_token_cap from THIS registry via
+# kernel.model_profile(id_or_alias); a cap literal in code is a bug.
+#
+# Profiles live in the `_lib` scope (`model-profiles/<model_id>.yaml`) —
+# ModelProfile is GLOBAL (base only, no per-tenant override) and NOT
+# inheritable; kernel.model_profile() queries `_lib` directly regardless
+# of the caller's scope.
+#
+# PARITY-CRITICAL package data: the byte-identical mirror lives at
+# packages/sdk-{py,ts}/{dna/extensions,src/extensions}/modelreg/kinds/
+# model-profile.kind.yaml (tests/test_descriptor_hash_parity.py enforces).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: model-profile
+spec:
+  target_api_version: github.com/ruinosus/dna/modelreg/v1
+  target_kind: ModelProfile
+  alias: modelreg-model-profile
+  origin: github.com/ruinosus/dna/modelreg
+  tenant_scope: global
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: yaml
+    container: model-profiles
+  schema:
+    type: object
+    required:
+    - model_id
+    - provider
+    properties:
+      model_id:
+        type: string
+        description: Canonical model identifier, e.g. 'gpt-realtime-2'. The doc
+          name SHOULD equal the model_id; kernel.model_profile() matches on this
+          field first.
+      provider:
+        type: string
+        description: Who serves the model — 'openai', 'anthropic', 'azure', a
+          proxy alias, etc.
+      family:
+        type:
+        - string
+        - 'null'
+        description: Model family/lineage for grouping, e.g. 'gpt-realtime'.
+      realtime:
+        type: boolean
+        default: false
+        description: 'True for realtime voice models. STRICT marker: the
+          prompt-budget guard VETOES an over-cap write against a realtime
+          profile (voice sessions silently degrade past the cap); chat profiles
+          only warn.'
+      context_window:
+        type: integer
+        description: Total context window in tokens.
+      instruction_token_cap:
+        type:
+        - integer
+        - 'null'
+        description: Hard cap for the system-instruction/persona in tokens.
+          Null = no cap known (the guard fails open). THE value the
+          prompt-budget guard enforces — never hardcode it in code.
+      max_output_tokens:
+        type:
+        - integer
+        - 'null'
+        description: Max completion/output tokens per response.
+      tools_cap:
+        type:
+        - integer
+        - 'null'
+        description: Max number of tools the model accepts per session.
+      modalities:
+        type: array
+        items:
+          type: string
+        description: Supported modalities, e.g. [text], [text, audio],
+          [text, image].
+      cost_per_1m_input_usd:
+        type:
+        - number
+        - 'null'
+        description: USD per 1M input tokens (informational).
+      cost_per_1m_output_usd:
+        type:
+        - number
+        - 'null'
+        description: USD per 1M output tokens (informational).
+      aliases:
+        type: array
+        items:
+          type: string
+        description: Alternate ids that resolve to this profile (deployment
+          names, dated snapshots). kernel.model_profile() matches these on
+          pass 2.
+      deprecated:
+        type: boolean
+        default: false
+        description: True when the model is scheduled for removal.
+      deprecated_message:
+        type:
+        - string
+        - 'null'
+        description: Human guidance shown when a deprecated model is used.
+      notes:
+        type:
+        - string
+        - 'null'
+        description: Free-form operator notes.
+  describe: '{provider}/{model_id}'
+  summary:
+    model_id: ''
+    provider: ''
+    family: null
+    realtime: false
+    context_window: null
+    instruction_token_cap: null
+    deprecated: false
+  ui:
+    mode: govern
+    label:
+      en: Model Profiles
+      pt-BR: Perfis de Modelo
+    icon: 🧬
+    description:
+      en: Per-LLM-model limits/capabilities.
+      pt-BR: Limites/capacidades por modelo LLM.
+    routes:
+      list: docs/ModelProfile
+      detail: docs/ModelProfile/:name
+    permissions:
+      list: any
+      detail: any
+    in_sidebar: true
+    display_order: 52
+  ascii_icon: 🧬
+  display_label: Model Profiles
+  docs: A ModelProfile records one LLM model's hard limits and capabilities
+    (instruction_token_cap, context_window, tools_cap, modalities, cost). It is
+    the single source of truth the prompt-budget write guard reads — never
+    hardcode token caps in code; read them from the ModelProfile registry via
+    kernel.model_profile().

package/dist/extensions/modelreg.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ModelRegExtension — per-model capability/limit registry.
+ *
+ * 1:1 parity with Python `dna.extensions.modelreg`.
+ *
+ * Registers 1 Kind, from a descriptor (F3 — record Kinds are data, not
+ * classes):
+ *
+ *   - ModelProfile (`modelreg-model-profile`) — hard limits
+ *     (`instruction_token_cap`, `context_window`, `tools_cap`) +
+ *     modalities + cost of one LLM model, as a first-class GLOBAL Kind so
+ *     limits are project data, not implicit knowledge. Ported from the
+ *     internal SDK's model registry, motivated by a real outage: a
+ *     17269-token voice persona silently exceeded the realtime model's
+ *     16384-token session-instructions cap because the cap lived in
+ *     nobody's code.
+ *
+ * CONTRACT — never hardcode token caps. The single source of truth for a
+ * model's limits is its ModelProfile doc (`_lib` scope,
+ * `model-profiles/<model_id>.yaml`), resolved via
+ * `kernel.modelProfile(idOrAlias)`. The prompt-budget write guard
+ * (`src/extensions/helix/write-guards.ts` + Python twin) reads the cap
+ * from there — a token-cap literal in code is a bug.
+ */
+import type { ExtensionHost, Extension } from "../kernel/protocols.js";
+export declare class ModelRegExtension implements Extension {
+    name: string;
+    version: string;
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/modelreg.js

@@ -0,0 +1,38 @@
+/**
+ * ModelRegExtension — per-model capability/limit registry.
+ *
+ * 1:1 parity with Python `dna.extensions.modelreg`.
+ *
+ * Registers 1 Kind, from a descriptor (F3 — record Kinds are data, not
+ * classes):
+ *
+ *   - ModelProfile (`modelreg-model-profile`) — hard limits
+ *     (`instruction_token_cap`, `context_window`, `tools_cap`) +
+ *     modalities + cost of one LLM model, as a first-class GLOBAL Kind so
+ *     limits are project data, not implicit knowledge. Ported from the
+ *     internal SDK's model registry, motivated by a real outage: a
+ *     17269-token voice persona silently exceeded the realtime model's
+ *     16384-token session-instructions cap because the cap lived in
+ *     nobody's code.
+ *
+ * CONTRACT — never hardcode token caps. The single source of truth for a
+ * model's limits is its ModelProfile doc (`_lib` scope,
+ * `model-profiles/<model_id>.yaml`), resolved via
+ * `kernel.modelProfile(idOrAlias)`. The prompt-budget write guard
+ * (`src/extensions/helix/write-guards.ts` + Python twin) reads the cap
+ * from there — a token-cap literal in code is a bug.
+ */
+import { loadDescriptors } from "../kernel/descriptor-loader.js";
+export class ModelRegExtension {
+    name = "modelreg";
+    version = "1.0.0";
+    register(kernel) {
+        // F3: ModelProfile ships as kinds/model-profile.kind.yaml package data
+        // (byte-identical Py↔TS mirror), registered through the SAME funnel as
+        // per-scope KindDefinitions (plane lint + digest idempotency + builtin
+        // conflict marker).
+        for (const raw of loadDescriptors(import.meta.url, "modelreg/kinds")) {
+            kernel.kindFromDescriptor(raw);
+        }
+    }
+}

package/dist/extensions/recognizer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * RecognizerExtension — Recognizer kind (Presidio ad-hoc recognizer).
+ *
+ * Declares PII detection patterns as manifest documents. Recognizers are
+ * referenced by SafetyPolicy documents via dep_filters and exported to
+ * LiteLLM/Presidio at runtime.
+ *
+ * 1:1 parity with Python dna.extensions.recognizer.
+ */
+import type { BundleHandle } from "../kernel/bundle-handle.js";
+import type { FSLike } from "../kernel/fs.js";
+import type { ExtensionHost, Extension, ReaderPort, SerializedFile, WriterPort } from "../kernel/protocols.js";
+export declare class RecognizerReader implements ReaderPort {
+    private fs;
+    readonly _marker = "RECOGNIZER.md";
+    constructor(fs?: FSLike);
+    detect(bundle: BundleHandle): boolean;
+    read(bundle: BundleHandle): Record<string, unknown>;
+}
+export declare class RecognizerWriter implements WriterPort {
+    private fs;
+    readonly _kind = "Recognizer";
+    constructor(fs?: FSLike);
+    canWrite(raw: Record<string, unknown>): boolean;
+    write(bundle: BundleHandle, raw: Record<string, unknown>): void;
+    serialize(raw: Record<string, unknown>): SerializedFile[];
+}
+export declare class RecognizerExtension implements Extension {
+    private fs;
+    readonly name = "recognizer";
+    readonly version = "1.0.0";
+    constructor(fs?: FSLike);
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/recognizer.js

@@ -0,0 +1,272 @@
+/**
+ * RecognizerExtension — Recognizer kind (Presidio ad-hoc recognizer).
+ *
+ * Declares PII detection patterns as manifest documents. Recognizers are
+ * referenced by SafetyPolicy documents via dep_filters and exported to
+ * LiteLLM/Presidio at runtime.
+ *
+ * 1:1 parity with Python dna.extensions.recognizer.
+ */
+import yaml from "js-yaml";
+import { nodeFS } from "../kernel/fs.js";
+import { KindBase } from "../kernel/kind_base.js";
+import { RecognizerSchema, RecognizerSpecSchema, zodSpecToJsonSchema } from "../kernel/models.js";
+import { SD } from "../kernel/protocols.js";
+// ---------------------------------------------------------------------------
+// RecognizerKind
+// ---------------------------------------------------------------------------
+class RecognizerKind extends KindBase {
+    apiVersion = "presidio/v1";
+    kind = "Recognizer";
+    alias = "presidio-recognizer";
+    isSchemaAffecting = true;
+    origin = "microsoft.github.io/presidio";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    descriptionFallbackField = "entity_type";
+    storage = SD.bundle("recognizers", "RECOGNIZER.md", "text", "patterns");
+    graphStyle = { fill: "#6366F1", stroke: "#4F46E5", textColor: "#fff" };
+    asciiIcon = "\uD83D\uDD0D";
+    displayLabel = "Recognizers";
+    _sourceUrl = import.meta.url;
+    docs = "A Recognizer is a Presidio ad-hoc recognizer that detects PII entities " +
+        "using regex patterns or deny lists. Recognizers are referenced by " +
+        "SafetyPolicy documents and exported to LiteLLM/Presidio at runtime.";
+    uiSchema = {
+        entity_type: {
+            widget: "input",
+            label: "Entity Type",
+            help: "Presidio entity name, e.g. BR_CPF, BR_CNPJ",
+            order: 1,
+        },
+        language: {
+            widget: "select",
+            options: ["en", "pt", "es", "de", "fr"],
+            label: "Language",
+            order: 2,
+        },
+        patterns: {
+            widget: "code",
+            language: "yaml",
+            label: "Patterns",
+            help: "List of {name, regex, score} objects",
+            height: 200,
+            order: 3,
+        },
+        deny_list: {
+            widget: "tags",
+            label: "Deny List",
+            help: "Words that always match this entity",
+            order: 4,
+        },
+        context: {
+            widget: "tags",
+            label: "Context Words",
+            help: "Words near the entity that boost confidence",
+            order: 5,
+        },
+    };
+    schema() { return zodSpecToJsonSchema(RecognizerSpecSchema); }
+    parse(raw) {
+        // patterns comes as raw text (body_as=text). Parse as YAML to get array of pattern objects.
+        const spec = (raw.spec ?? {});
+        if (typeof spec.patterns === "string" && spec.patterns.trim()) {
+            try {
+                const parsed = yaml.load(spec.patterns);
+                if (Array.isArray(parsed)) {
+                    spec.patterns = parsed;
+                }
+                else {
+                    spec.patterns = [];
+                }
+            }
+            catch {
+                spec.patterns = [];
+            }
+        }
+        return RecognizerSchema.parse(raw);
+    }
+    describe(doc) {
+        const spec = (doc.spec ?? {});
+        return `Recognizer: ${doc.name} (entity=${spec.entity_type})`;
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        return {
+            entity_type: typeof spec.entity_type === "string" ? spec.entity_type : "",
+            language: typeof spec.language === "string" ? spec.language : "en",
+            patterns: Array.isArray(spec.patterns) ? spec.patterns.length : 0,
+            deny_list: Array.isArray(spec.deny_list) ? spec.deny_list.length : 0,
+        };
+    }
+    preview(doc) {
+        const spec = (doc.spec ?? {});
+        const blocks = [];
+        const meta = [];
+        if (typeof spec.entity_type === "string")
+            meta.push({ label: "Entity Type", value: spec.entity_type });
+        if (typeof spec.language === "string")
+            meta.push({ label: "Language", value: spec.language });
+        if (meta.length > 0) {
+            blocks.push({ kind: "fields", title: "Recognizer", fields: meta });
+        }
+        const patterns = spec.patterns;
+        if (Array.isArray(patterns) && patterns.length > 0) {
+            blocks.push({
+                kind: "code",
+                title: "Patterns",
+                body: yaml.dump(patterns, { flowLevel: 3 }).trim(),
+                language: "yaml",
+            });
+        }
+        const denyList = spec.deny_list;
+        if (Array.isArray(denyList) && denyList.length > 0) {
+            blocks.push({
+                kind: "code",
+                title: "Deny List",
+                body: denyList.join(", "),
+                language: "text",
+            });
+        }
+        const context = spec.context;
+        if (Array.isArray(context) && context.length > 0) {
+            blocks.push({
+                kind: "code",
+                title: "Context Words",
+                body: context.join(", "),
+                language: "text",
+            });
+        }
+        if (blocks.length === 0) {
+            return [{ kind: "empty", title: "Recognizer (empty)" }];
+        }
+        return blocks;
+    }
+}
+// ---------------------------------------------------------------------------
+// RecognizerReader
+// ---------------------------------------------------------------------------
+function parseFrontmatter(text) {
+    const match = text.match(/^---\n([\s\S]*?)---\n?/);
+    if (!match)
+        return [{}, text];
+    let fm = {};
+    try {
+        const parsed = yaml.load(match[1]);
+        if (typeof parsed === "object" && parsed !== null) {
+            fm = parsed;
+        }
+    }
+    catch { /* ignore */ }
+    const body = text.slice(match[0].length);
+    return [fm, body];
+}
+export class RecognizerReader {
+    fs;
+    _marker = "RECOGNIZER.md";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    detect(bundle) {
+        const path = bundle.path ?? "";
+        return this.fs.exists(`${path}/RECOGNIZER.md`);
+    }
+    read(bundle) {
+        const path = bundle.path ?? "";
+        const text = this.fs.readFile(`${path}/RECOGNIZER.md`);
+        const [fm, body] = parseFrontmatter(text);
+        const name = String(fm.name || "") || path.split("/").pop() || "";
+        const description = String(fm.description || "");
+        const entity_type = String(fm.entity_type || "");
+        const language = String(fm.language || "en");
+        // Parse deny_list and context from frontmatter
+        const deny_list = Array.isArray(fm.deny_list) ? fm.deny_list.map(String) : [];
+        const context = Array.isArray(fm.context) ? fm.context.map(String) : [];
+        // Parse body as YAML list of pattern objects
+        let patterns = [];
+        const trimmedBody = body.trim();
+        if (trimmedBody) {
+            try {
+                const parsed = yaml.load(trimmedBody);
+                if (Array.isArray(parsed)) {
+                    patterns = parsed;
+                }
+            }
+            catch { /* ignore invalid YAML */ }
+        }
+        return {
+            apiVersion: "presidio/v1",
+            kind: "Recognizer",
+            metadata: { name, description },
+            spec: { entity_type, language, patterns, deny_list, context },
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// RecognizerWriter
+// ---------------------------------------------------------------------------
+export class RecognizerWriter {
+    fs;
+    _kind = "Recognizer";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    canWrite(raw) {
+        return raw.kind === "Recognizer";
+    }
+    write(bundle, raw) {
+        const path = bundle.path ?? "";
+        this.fs.mkdir(path);
+        for (const f of this.serialize(raw)) {
+            this.fs.writeFile(`${path}/${f.relativePath}`, f.content ?? "");
+        }
+    }
+    serialize(raw) {
+        const meta = (raw.metadata ?? {});
+        const spec = (raw.spec ?? {});
+        const fmParts = [];
+        if (meta.name)
+            fmParts.push(`name: ${meta.name}`);
+        if (meta.description)
+            fmParts.push(`description: ${meta.description}`);
+        if (spec.entity_type)
+            fmParts.push(`entity_type: ${spec.entity_type}`);
+        fmParts.push(`language: ${spec.language ?? "en"}`);
+        const denyList = spec.deny_list;
+        if (denyList && denyList.length > 0) {
+            fmParts.push(`deny_list:\n${denyList.map(w => `  - ${w}`).join("\n")}`);
+        }
+        const context = spec.context;
+        if (context && context.length > 0) {
+            fmParts.push(`context:\n${context.map(w => `  - ${w}`).join("\n")}`);
+        }
+        const frontmatter = fmParts.join("\n");
+        // Serialize patterns as YAML list
+        const patterns = spec.patterns ?? [];
+        let body = "";
+        if (patterns.length > 0) {
+            body = yaml.dump(patterns, { flowLevel: 3 }).trim();
+        }
+        const content = body
+            ? `---\n${frontmatter}\n---\n\n${body}\n`
+            : `---\n${frontmatter}\n---\n`;
+        return [{ relativePath: "RECOGNIZER.md", content }];
+    }
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+export class RecognizerExtension {
+    fs;
+    name = "recognizer";
+    version = "1.0.0";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    register(kernel) {
+        kernel.kind(new RecognizerKind());
+        kernel.reader(new RecognizerReader(this.fs));
+        kernel.writer(new RecognizerWriter(this.fs));
+    }
+}

package/dist/extensions/research.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ResearchExtension — curated research syntheses with evidence ratings (TS twin).
+ *
+ * 1:1 parity with python/dna/extensions/research/__init__.py.
+ *
+ * Storage layout per doc:
+ *
+ *   .dna/<scope>/research/<name>/
+ *       RESEARCH.md            ← marker (frontmatter = spec)
+ *
+ * A Research synthesizes N Reference docs with objective, methodology,
+ * evidence-rated findings, and priority recommendations — agent-facing
+ * knowledge WITH provenance (the declarative counter to LLM-generated
+ * repo-wiki prose).
+ *
+ * Tenancy: PERMISSIVE — no `scope` attribute declared, so the write
+ * pipeline treats it as permissive (base writes with or without a
+ * tenant). Research is repo-authored knowledge, not per-client data.
+ *
+ * The Reference companion Kind is provided by the sdlc extension
+ * (alias sdlc-reference); it is NOT registered here.
+ */
+import type { ExtensionHost, Extension } from "../kernel/protocols.js";
+export declare const METHODOLOGIES: readonly ["web-search-curated", "literature-review", "interview", "field-study", "experiment", "synthesis", "other"];
+export declare const EVIDENCE_RATINGS: readonly ["evidence-based", "opinion-practice", "anecdotal"];
+export declare const STATUSES: readonly ["brief", "ready", "draft", "published", "superseded", "retracted"];
+export declare const VISIBILITY: readonly ["scope-private", "shared"];
+export declare class ResearchExtension implements Extension {
+    name: string;
+    version: string;
+    register(kernel: ExtensionHost): void;
+}