Janady13/missionmatch / internal/modules/ai/tag.go

Source identity

Field	Recorded value
Source type	GitHub source
Original record	Janady13/missionmatch / internal/modules/ai/tag.go
Date	Not specified in source
Repository	Janady13/missionmatch
Revision	43d56387270ef4da4cabd794d97ca6a49909bc7d
Branch	w3-ai-staffing-recommendations
Path or archive member	internal/modules/ai/tag.go
Original SHA-256	32cb6bf6bca13e0b11e4be72ed3370faee345806bb1d25066bcc189674072ff8
Git blob SHA	216ff56da04076c361747264d133fdaa63e0da30
Reading-copy SHA-256	32cb6bf6bca13e0b11e4be72ed3370faee345806bb1d25066bcc189674072ff8

Original source ↗

Every recorded occurrence

These 25 records contain identical original source bytes. Their paths and revisions remain part of the archive.

Original record	Branch or archive	Revision / identifier	Original location
Janady13/missionmatch / internal/modules/ai/tag.go	w3-ai-staffing-recommendations	43d56387270ef4da4cabd794d97ca6a49909bc7d	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws3-clearance	4b8e7ce594c068621867f9c9deed0ec64ae6c553	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ai-intelligence-layer	5d5ddff70393a197c5f54a45280bb5dd42b24755	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws7-federal-signal	6a9f6ce9cfb13345ffb47770d4960e7c2d9c17c2	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws6-retrieval	6c56e29231ec05735927fa265c97d517499dfeaf	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	per-tenant-routing	9bde0f9a74b89d01980fa658e5253acda7528d0c	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ai-brain-live	aac32fc49c878cc5bca099459307611562d0bac1	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws1-ontology-sync	b596f449a32a1016fbd403c36505cc00a1ac9ee6	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	deploy-and-ops	bdacd9d0b4d5998d25fc74bf4007f4c3ec538c7a	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws8-teaching-loop	c823f0fb6bb2aba0f39001eb6de96f4000d9321f	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	phase2-eval-fairness	d361af254701975fe239927656ababb56374655e	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws2-alias-relationship	e4dada4601c6eb101830f9d223a9655dfa120616	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws9-bench-ingestion	f585a9ef32fa554663ce1fba9a414a54b6e49cf0	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	per-tenant-routing	9bde0f9a74b89d01980fa658e5253acda7528d0c	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws6-retrieval	6c56e29231ec05735927fa265c97d517499dfeaf	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws1-ontology-sync	b596f449a32a1016fbd403c36505cc00a1ac9ee6	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws8-teaching-loop	c823f0fb6bb2aba0f39001eb6de96f4000d9321f	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	w3-ai-staffing-recommendations	43d56387270ef4da4cabd794d97ca6a49909bc7d	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws3-clearance	4b8e7ce594c068621867f9c9deed0ec64ae6c553	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	phase2-eval-fairness	d361af254701975fe239927656ababb56374655e	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ai-intelligence-layer	5d5ddff70393a197c5f54a45280bb5dd42b24755	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	deploy-and-ops	bdacd9d0b4d5998d25fc74bf4007f4c3ec538c7a	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws2-alias-relationship	e4dada4601c6eb101830f9d223a9655dfa120616	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ws7-federal-signal	6a9f6ce9cfb13345ffb47770d4960e7c2d9c17c2	Open original
Janady13/missionmatch / internal/modules/ai/tag.go	ai-brain-live	aac32fc49c878cc5bca099459307611562d0bac1	Open original

Recovered source transcript

Download complete source text ↓144 lines · 5.3 KB

package ai

import (
	"context"
	"errors"
	"fmt"

	"github.com/jackc/pgx/v5"

	"github.com/missionworkforce/missionmatch/internal/platform/tenant"
)

// TAG (table augmented generation) answers questions that require the database to COMPUTE (count, sum,
// filter, aggregate), which retrieval over text cannot do. The research is explicit that aggregation
// questions must go to the database, not to vector RAG (docs/AI_RESEARCH.md, TAG).
//
// For cleared data the safe design is structured tool use, NOT free form natural language to SQL: the
// model selects from a CURATED set of named, parameterized, read only intents and supplies typed
// parameters. The model never authors SQL. Every intent is validated at startup against the read only
// guard and the table allowlist, and references no eeo table, so a write or a demographics read is
// impossible from the natural language path by construction.

// ParamKind constrains an intent parameter so a model supplied value is type checked before binding.
type ParamKind string

const (
	ParamText    ParamKind = "text"
	ParamInt     ParamKind = "int"
	ParamUUID    ParamKind = "uuid"
	ParamEnum    ParamKind = "enum" // value must be in Allowed
	ParamBoolean ParamKind = "bool"
)

// Param describes one bound parameter of an intent.
type Param struct {
	Name    string
	Kind    ParamKind
	Allowed []string // for ParamEnum
}

// QueryIntent is one safe, named, read only question the TAG layer can answer. SQL is parameterized
// ($1, $2, ...) and runs RLS scoped as the application role, so it sees only the caller's tenant.
type QueryIntent struct {
	Name        string
	Description string // what question it answers, used for model routing
	SQL         string
	Params      []Param
}

// Registry is the closed set of TAG intents. Adding one is a reviewed security decision.
var Registry = []QueryIntent{
	{
		Name:        "count_candidates_by_clearance",
		Description: "How many candidates hold a given clearance level (and optionally are available).",
		SQL:         "SELECT clearance_level, count(*) AS n FROM candidates WHERE deleted_at IS NULL AND anonymized_at IS NULL AND ($1 = '' OR clearance_level = $1) GROUP BY clearance_level ORDER BY n DESC",
		Params:      []Param{{Name: "clearance_level", Kind: ParamEnum, Allowed: []string{"", "none", "confidential", "secret", "top_secret", "ts_sci"}}},
	},
	{
		Name:        "proposal_ready_for_requirement",
		Description: "How many persisted evaluations for a requirement are in the Green (proposal ready) band.",
		SQL:         "SELECT band, count(*) AS n FROM candidate_evaluations WHERE requirement_id = $1 GROUP BY band ORDER BY n DESC",
		Params:      []Param{{Name: "requirement_id", Kind: ParamUUID}},
	},
	{
		Name:        "open_requirements_count",
		Description: "How many requirements are open (not soft deleted), optionally for one customer agency.",
		SQL:         "SELECT count(*) AS n FROM requirements WHERE deleted_at IS NULL AND ($1 = '' OR customer_agency = $1)",
		Params:      []Param{{Name: "customer_agency", Kind: ParamText}},
	},
	{
		Name:        "slate_decision_mix",
		Description: "The approve/reject/pending decision mix of a slate's members.",
		SQL:         "SELECT decision, count(*) AS n FROM slate_members WHERE slate_id = $1 GROUP BY decision ORDER BY n DESC",
		Params:      []Param{{Name: "slate_id", Kind: ParamUUID}},
	},
}

// ValidateRegistry asserts every intent is safe: read only, references no eeo, and touches only
// allowlisted tables. It is called at startup and by a test, so an unsafe intent cannot ship.
func ValidateRegistry() error {
	for _, it := range Registry {
		if err := GuardReadOnlyQuery(it.SQL, ReadAllowlist); err != nil {
			return fmt.Errorf("ai: intent %q is unsafe: %w", it.Name, err)
		}
	}
	return nil
}

// IntentByName returns a registered intent.
func IntentByName(name string) (QueryIntent, bool) {
	for _, it := range Registry {
		if it.Name == name {
			return it, true
		}
	}
	return QueryIntent{}, false
}

// TAGResult is the executed answer: the column names and the rows, ready to narrate. It carries no free
// text from the model, only data the database returned.
type TAGResult struct {
	Intent  string
	Columns []string
	Rows    [][]any
}

// ExecuteIntent binds the model supplied args (in the order of Params) and runs the intent RLS scoped as
// the tenant. It re validates the SQL through the guard at execution time too (defense in depth), so even
// a tampered registry cannot run a write or reach eeo.
func ExecuteIntent(ctx context.Context, db *tenant.DB, intent QueryIntent, args []any) (*TAGResult, error) {
	if db == nil {
		return nil, errors.New("ai: no database")
	}
	if err := GuardReadOnlyQuery(intent.SQL, ReadAllowlist); err != nil {
		return nil, err
	}
	if len(args) != len(intent.Params) {
		return nil, fmt.Errorf("ai: intent %q expects %d params, got %d", intent.Name, len(intent.Params), len(args))
	}
	out := &TAGResult{Intent: intent.Name}
	err := db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error {
		rows, err := tx.Query(ctx, intent.SQL, args...)
		if err != nil {
			return err
		}
		defer rows.Close()
		for _, fd := range rows.FieldDescriptions() {
			out.Columns = append(out.Columns, string(fd.Name))
		}
		for rows.Next() {
			vals, err := rows.Values()
			if err != nil {
				return err
			}
			out.Rows = append(out.Rows, vals)
		}
		return rows.Err()
	})
	if err != nil {
		return nil, err
	}
	return out, nil
}