Skip to main content

Database Seeding & Agent Synchronization

Seeding boundaries​

Database deployment and data seeding are intentionally separate. The Core and aggregate DACPAC post-deployment scripts print guidance but do not execute agent or model seeds automatically.

MechanismResponsibility
Agent descriptor seedConfigCreates a default current profile at runtime when the owning agent factory is configured to seed.
db/sqlproj/seeds/**Explicit, idempotent local/operator SQL seeds for profiles, docs chat, taxonomy, and model-development data.
Model runtime workflowGenerates model-capability/parameter rows from the deployment manifest and seeds them through the reusable model-runtime stage.
Admin tools/UIVersioned operator updates to profiles and model parameters.
Snapshot scriptsExport/split/generate controlled profile seed artifacts through root db:agent-profiles:* commands.

Seed inventory​

db/sqlproj/seeds/
  _run_all.sql
  _run_by_env.sql
  core/       agent profiles, docs chat, local model capabilities
  handbook/   Handbook agent profiles
  k12/        K12 agent profiles
  reasoning/  optional Reasoning Engine profiles
  sdac/       SDAC agent profiles
  tap/        TAP profiles and topic taxonomy
  tools/      copy_agents_between_dbs.py, sync_agents_to_control.py

The scripts are source-controlled defaults, not proof of the current rows in a live environment.

Run explicit seeds​

# All checked-in profile/taxonomy seeds
sqlcmd -S <server> -d <database> -i "db/sqlproj/seeds/_run_all.sql"

# Project-oriented selection
sqlcmd -S <server> -d <database> \
  -i "db/sqlproj/seeds/_run_by_env.sql" -v ENV="k12_sdac"

# One seed
sqlcmd -S <server> -d <database> \
  -i "db/sqlproj/seeds/handbook/seed_agent_profiles.sql"

Accepted _run_by_env.sql values are tap_only, k12_only, sdac_only, k12_sdac, and all. Inspect that script before relying on the selection; it currently focuses on the long-standing Core/K12/SDAC/TAP/Reasoning profiles, while Handbook can be run directly.

Idempotency and versions​

Agent-profile seeds use profile hashes and current/version fields. An identical current profile is skipped; a changed profile expires the current row and adds a new version. Always inspect the seed diff before applying it to a shared environment: idempotent does not mean consequence-free.

Model runtime data​

Core.LLMModelCapabilities and Core.LLMParamsDim deployment rows should be derived from the actual model deployment manifest. The static core/seed_llm_capabilities.sql remains useful for local schema/UI work but is not the production promotion authority.

Profile export workflow​

Root scripts provide a reviewable snapshot flow:

npm run db:agent-profiles:export
npm run db:agent-profiles:split
npm run db:agent-profiles:seed-sql

The generated SQL defaults to temp/**; do not commit transient output. Review snapshots for secrets or environment-specific data before committing any intentional seed artifact.

Cross-environment utilities​

sync_agents_to_control.py and copy_agents_between_dbs.py are privileged operator tools. Supply credentials through secure environment configuration, never inline them in docs, shell history, or committed files. Confirm source, target, agent IDs, write gate, backup/rollback, and current profile hashes before running a bulk copy.