Namish18 commited on
Commit
a101fbc
·
verified ·
1 Parent(s): e47b170

Upload 9 files

Browse files

first version of model

README.md CHANGED
@@ -1,3 +1,117 @@
1
  ---
2
- license: mit
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3
  ---
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
+ language:
3
+ - en
4
+ - multilingual
5
+ license: apache-2.0
6
+ base_model: CohereLabs/tiny-aya-global
7
+ tags:
8
+ - database
9
+ - postgresql
10
+ - performance-optimization
11
+ - query-diagnostics
12
+ - agent
13
+ - cohere2
14
+ - tiny-aya
15
+ - agenttune
16
+ pipeline_tag: text-generation
17
  ---
18
+
19
+ # DBMedic — Autonomous PostgreSQL Diagnostic Agent Integration
20
+
21
+ > [!IMPORTANT]
22
+ > **TRAINING STATUS & CHECKPOINT DISCLAIMER**
23
+ > **No fine-tuned model checkpoint exists for DBMedic.**
24
+ > Phase 4 LoRA/SFT distillation was **NOT performed** due to hardware and token gating blockers (absence of a dedicated CUDA GPU and gated repository access token). All integration code, agent prompts, deterministic diagnostic tools, reward functions, and dataset curation pipelines are fully implemented and verified via unit tests and dry runs, but **no weights were altered or uploaded**. The target base model is the original, unmodified [`CohereLabs/tiny-aya-global`](https://huggingface.cohereLabs/tiny-aya-global).
25
+
26
+ ---
27
+
28
+ ## Model Summary
29
+
30
+ - **Project:** DBMedic (Autonomous Database Diagnostic and Self-Healing Agent)
31
+ - **Target Base Model:** [`CohereLabs/tiny-aya-global`](https://huggingface.co/CohereLabs/tiny-aya-global)
32
+ - **Architecture Family:** `cohere2` (multilingual decoder-only transformer, ~3.35 billion parameters)
33
+ - **Primary Domain:** PostgreSQL database performance analysis, slow-query diagnostics, query plan explanation, and index recommendation.
34
+ - **Agent Framework:** Custom ReAct diagnostic orchestrator with AgentTune (`v1.1.4`) training integration.
35
+ - **Current Artifact State:** Architecture, prompt contracts, tool interfaces, and training pipeline specifications only. **Zero fine-tuned checkpoint weights are distributed.**
36
+
37
+ ---
38
+
39
+ ## Intended Use & Capabilities
40
+
41
+ DBMedic integrates with language models to serve as a **read-only diagnostic assistant** for PostgreSQL database administrators and site reliability engineers.
42
+
43
+ ### Core Capabilities
44
+ 1. **Explain Plan Inspection:** Parses `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` output to detect sequential scans, cache misses, nested loops, and high-cost operators.
45
+ 2. **Table & Index Heuristics:** Interrogates database catalog tables (`pg_stat_user_tables`, `pg_stat_user_indexes`, `pg_class`) to determine table footprint, live/dead tuple counts, and index usage efficiency.
46
+ 3. **Structured Diagnostic Output:** Synthesizes observations into a validated JSON schema containing root-cause analysis, supporting evidence, confidence score, and remediation advice.
47
+ 4. **Safety Boundaries:** Strictly enforces read-only access. Any remediation SQL (e.g. `CREATE INDEX CONCURRENTLY`) is classified as requiring explicit, human approval before execution.
48
+
49
+ ### Out-of-Scope & Unintended Uses
50
+ - **Autonomous DDL Execution:** DBMedic MUST NOT execute DDL or data-modifying queries autonomously. All mutation recommendations must pass through human review.
51
+ - **Non-PostgreSQL Engines:** Heuristics and catalog inspection queries are strictly built for PostgreSQL (v15+). Using this system against MySQL, Oracle, or SQL Server will result in runtime tool failures.
52
+ - **Safety Critical Automated Production Systems:** Not designed to run without operator supervision on production mission-critical clusters.
53
+
54
+ ---
55
+
56
+ ## Agent Integration & Tool Calling Protocol
57
+
58
+ The DBMedic agent interacts with the base model via a strict alternating conversational prompt format adhering to Tiny Aya's tokenizer specifications:
59
+
60
+ ```
61
+ <|START_OF_TURN_TOKEN|><|SYSTEM_TOKEN|># Developer Preamble
62
+ You are DBMedic, an expert autonomous PostgreSQL database performance diagnostic agent...<|END_OF_TURN_TOKEN|>
63
+ <|START_OF_TURN_TOKEN|><|USER_TOKEN|>Orders for customer 4242 are loading slowly. Diagnose the root cause.<|END_OF_TURN_TOKEN|>
64
+ <|START_OF_TURN_TOKEN|><|CHATBOT_TOKEN|><|START_RESPONSE|>{"type": "tool_call", "tool": "explain_query", "arguments": {"query": "SELECT * FROM orders WHERE customer_id = 4242"}}<|END_RESPONSE|><|END_OF_TURN_TOKEN|>
65
+ ```
66
+
67
+ ### Approved Read-Only Diagnostic Tools
68
+ The agent runtime exposes exactly eight read-only diagnostic tools:
69
+ 1. `explain_query`: Runs `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` on candidate queries.
70
+ 2. `get_table_statistics`: Retrieves row counts, sequential scan counts, and vacuum stats.
71
+ 3. `get_table_size`: Measures total disk footprint (table, index, toast) via `pg_total_relation_size`.
72
+ 4. `get_index_statistics`: Analyzes index scan rates and hit ratios.
73
+ 5. `check_index_exists`: Checks existing index coverage on target columns.
74
+ 6. `get_running_queries`: Examines `pg_stat_activity` for blocking or long-running queries.
75
+ 7. `get_table_indexes`: Lists all index definitions and uniqueness constraints for a table.
76
+ 8. `get_database_stats`: Measures cache hit ratios, transaction commit rates, and deadlock counts.
77
+
78
+ ---
79
+
80
+ ## Training Specification (Phase 4 AgentTune & LoRA SFT)
81
+
82
+ Although live fine-tuning was blocked in the local environment, the training pipeline is fully specified and configured in the repository:
83
+
84
+ - **Framework:** AgentTune `Project.distill` LoRA SFT Distillation (`trl==1.7.1`, `peft`, `agenttune==1.1.4`)
85
+ - **LoRA Hyperparameters:**
86
+ - `r`: 16
87
+ - `lora_alpha`: 32
88
+ - `lora_dropout`: 0.05
89
+ - `target_modules`: `all-linear` (excluding `lm_head`)
90
+ - `bias`: `none`
91
+ - **Optimization:**
92
+ - `learning_rate`: `2e-4` with cosine scheduler
93
+ - `batch_size`: 2 per device (gradient accumulation steps: 4)
94
+ - `loss_type`: `nll` (token-level `-100` completion-only label masking)
95
+ - `max_seq_length`: 2048
96
+ - **Hardware Requirement:** Dedicated NVIDIA CUDA GPU with $\ge 8$ GB VRAM for LoRA SFT distillation ($\ge 12$ GB for GRPO rollouts).
97
+
98
+ ---
99
+
100
+ ## Evaluation & Safety Evidence Summary
101
+
102
+ | Evaluation Domain | Benchmark File | Provenance | Result / Status |
103
+ |---|---|---|---|
104
+ | PostgreSQL Baseline Execution | `slow_query_baseline.json` | Live PostgreSQL 17 execution | Median: 24.21 ms (Seq Scan) |
105
+ | Post-Remediation Execution | `slow_query_after_remediation.json` | Live PostgreSQL 17 execution | Median: 1.19 ms (Index Only Scan, 95.09% speedup) |
106
+ | Red-Team Security Evaluation | `redteam_results.json` | Simulated adversarial suite | 10/10 attacks blocked (0.0% attack success rate) |
107
+ | Base Model Agent Inference | `baseline_status.json` | Local environment check | Blocked (no GPU / gated token) |
108
+ | Candidate Model Inference | `final_evaluation_report.json` | AuditKIT gate | Blocked (no fine-tuned checkpoint exists) |
109
+
110
+ ---
111
+
112
+ ## Limitations & Risks
113
+
114
+ 1. **Synthetic Environment Bias:** Diagnostic heuristics were developed and benchmarked on a synthetic e-commerce schema (10k customers, 50k products, 200k orders). Real production distributions may exhibit query plans influenced by complex joins, partitioning, or non-default PostgreSQL planner constants (`random_page_cost`, `work_mem`).
115
+ 2. **Hallucination Risk:** Pre-trained base models without domain SFT may produce hallucinated table names or malformed tool call JSON. The DBMedic deterministic `ToolValidator` and `ResponseParser` runtime guardrails reject such actions, preventing execution.
116
+ 3. **No Automated Recovery Execution:** DBMedic does not autonomously execute remediations; human authorization is required for any database modification.
117
+
dataset_config.yaml ADDED
@@ -0,0 +1,43 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # DBMedic Phase 4 Dataset Curation & Split Configuration
2
+
3
+ dataset:
4
+ name: dbmedic_slow_query_diagnostics
5
+ version: "4.0"
6
+ seed: 42
7
+
8
+ paths:
9
+ raw_dir: training/data/raw
10
+ processed_dir: training/data/processed
11
+ curated_dir: training/data/curated
12
+ splits_dir: training/data/splits
13
+ manifest_path: training/data/dataset_manifest.json
14
+
15
+ curation:
16
+ require_verified: true
17
+ allow_unsafe_examples: false
18
+ deduplicate: true
19
+ min_diagnosis_length: 10
20
+ max_turns_per_example: 12
21
+ include_controlled_demonstrations: true
22
+ allowed_sources:
23
+ - verified_success_trajectory
24
+ - verified_corrected_failure
25
+ - human_reviewed_demonstration
26
+
27
+ splits:
28
+ train_file: train.jsonl
29
+ validation_file: validation.jsonl
30
+ hidden_test_file: hidden_test.jsonl
31
+ strategy: scenario_group_isolated
32
+ validation_ratio: 0.2
33
+ prevent_hidden_leakage: true
34
+ strip_hidden_answers_from_prompts: true
35
+
36
+ formatting:
37
+ model_id: CohereLabs/tiny-aya-global
38
+ protocol: dbmedic_json_v1
39
+ enforce_strict_role_alternation: true
40
+ fold_tool_outputs_into_user: true
41
+ loss_masking: completion_only
42
+ max_seq_length: 2048
43
+
grpo_config.yaml ADDED
@@ -0,0 +1,71 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # DBMedic Phase 4 Secondary Experimental Config — AgentTune Agentic GRPO
2
+
3
+ experiment:
4
+ name: dbmedic_tiny_aya_grpo_v1
5
+ stage: grpo
6
+ method: agenttune.agentic.grpo
7
+ backend: trl
8
+ enabled: false
9
+ seed: 42
10
+ output_dir: training/experiments/grpo
11
+
12
+ gating_requirements:
13
+ require_sft_checkpoint: true
14
+ sft_checkpoint_dir: training/experiments/sft
15
+ require_cuda_gpu: true
16
+ min_free_vram_gb: 12.0
17
+ require_live_db: true
18
+ require_hf_token: true
19
+
20
+ model:
21
+ base_model_id: training/experiments/sft
22
+ fallback_base_model_id: CohereLabs/tiny-aya-global
23
+ trust_remote_code: false
24
+ device_map: auto
25
+
26
+ peft:
27
+ use_peft: true
28
+ task_type: CAUSAL_LM
29
+ r: 16
30
+ lora_alpha: 32
31
+ lora_dropout: 0.05
32
+ bias: none
33
+ target_modules: all-linear
34
+
35
+ rollout:
36
+ rollout_backend: transformers
37
+ max_steps_per_episode: 6
38
+ max_completion_length: 768
39
+ tools_fallback_prompt: cohere
40
+ tool_result_format: user_folded
41
+ read_only_tools_only: true
42
+ allowed_tools:
43
+ - get_query_execution_plan
44
+ - analyze_query_performance
45
+ - get_table_statistics
46
+ - get_table_size
47
+ - get_table_indexes
48
+ - get_index_usage
49
+ - inspect_customer_id_index
50
+ - diagnose_slow_query
51
+ excluded_tools:
52
+ - apply_remediation
53
+ - execute_sql
54
+
55
+ training:
56
+ num_generations: 2
57
+ max_steps: 20
58
+ per_device_train_batch_size: 1
59
+ gradient_accumulation_steps: 4
60
+ learning_rate: 5.0e-6
61
+ beta: 0.04
62
+ temperature: 0.7
63
+ bf16: true
64
+ gradient_checkpointing: true
65
+ log_completions: true
66
+ report_to: none
67
+
68
+ rewards:
69
+ config_path: training/rewards/reward_config.yaml
70
+ use_composite_diagnostic_reward: true
71
+
lexsi_provenance.json ADDED
@@ -0,0 +1,65 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "schema": "lexsi.provenance/1",
3
+ "library": "agenttune",
4
+ "version": "1.1.4",
5
+ "git_sha": null,
6
+ "created_at": "2026-11-11T13:05:56Z",
7
+ "base_model": "CohereLabs/tiny-aya-global",
8
+ "method": "agenttune.sft_distill",
9
+ "inputs": [
10
+ {
11
+ "kind": "dataset",
12
+ "ref": "C:\\Users\\spyan\\OneDrive\\Desktop\\DBMedic\\training\\data",
13
+ "config": null,
14
+ "provenance": null
15
+ }
16
+ ],
17
+ "params": {
18
+ "lora": {
19
+ "use_peft": true,
20
+ "task_type": "CAUSAL_LM",
21
+ "r": 16,
22
+ "lora_alpha": 32,
23
+ "lora_dropout": 0.05,
24
+ "bias": "none",
25
+ "target_modules": "all-linear",
26
+ "exclude_modules": [
27
+ "lm_head"
28
+ ],
29
+ "explicit_target_modules_fallback": [
30
+ "q_proj",
31
+ "k_proj",
32
+ "v_proj",
33
+ "o_proj",
34
+ "gate_proj",
35
+ "up_proj",
36
+ "down_proj"
37
+ ]
38
+ },
39
+ "training": {
40
+ "num_train_epochs": 3,
41
+ "learning_rate": 0.0002,
42
+ "lr_scheduler_type": "cosine",
43
+ "warmup_ratio": 0.1,
44
+ "per_device_train_batch_size": 1,
45
+ "per_device_eval_batch_size": 1,
46
+ "gradient_accumulation_steps": 4,
47
+ "max_length": 2048,
48
+ "loss_type": "nll",
49
+ "completion_only_loss": true,
50
+ "loss_masking_strategy": "pretokenized_assistant_labels",
51
+ "packing": false,
52
+ "gradient_checkpointing": true,
53
+ "bf16": true,
54
+ "fp16": false,
55
+ "logging_steps": 1,
56
+ "eval_strategy": "epoch",
57
+ "save_strategy": "epoch",
58
+ "save_total_limit": 2,
59
+ "report_to": "none"
60
+ },
61
+ "train_examples": 18,
62
+ "validation_examples": 5,
63
+ "dry_run": false
64
+ }
65
+ }
preflight_status.json ADDED
@@ -0,0 +1,68 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "dataset_validation": {
3
+ "passed": true,
4
+ "train_count": 18,
5
+ "validation_count": 5,
6
+ "hidden_test_count": 5,
7
+ "sha256_verified": true,
8
+ "leakage_clean": true,
9
+ "safety_clean": true,
10
+ "protocol_clean": true,
11
+ "errors": [],
12
+ "warnings": [],
13
+ "hashes": {
14
+ "train_jsonl": "c21ccf3568c2c820b09e8b22f97cda84cf32f2c439a0b083ab03ee056b1c04cd",
15
+ "validation_jsonl": "f5325364d19647543a45d2da14d4efa8146764f056606f846f4c816014e0066e",
16
+ "hidden_test_jsonl": "a3171e14b9799259f7cdac06308a1cd2e1dfe6f770c90e8f41e84185d4c1f75b",
17
+ "curated_all_jsonl": "283e5ad042a41ccc3265973d2ff108ec31931a8235d7750823cabb6295a5ef18"
18
+ }
19
+ },
20
+ "sft_readiness": {
21
+ "model_id": "CohereLabs/tiny-aya-global",
22
+ "hf_token_present": false,
23
+ "hf_token_env_var": null,
24
+ "cuda_available": false,
25
+ "gpu_name": null,
26
+ "gpu_vram_gb": 0.0,
27
+ "free_ram_gb": 1.52,
28
+ "total_ram_gb": 15.12,
29
+ "db_available": false,
30
+ "trl_available": true,
31
+ "peft_available": true,
32
+ "datasets_available": true,
33
+ "agenttune_available": true,
34
+ "train_dataset_exists": true,
35
+ "validation_dataset_exists": true,
36
+ "dataset_manifest_valid": true,
37
+ "ready_for_dry_run": true,
38
+ "ready_for_live_training": false,
39
+ "blockers": [
40
+ "HF_TOKEN / HUGGINGFACE_HUB_TOKEN not found in environment/.env for gated model 'CohereLabs/tiny-aya-global'.",
41
+ "No CUDA GPU detected (torch.cuda.is_available() == False). Full Tiny Aya SFT requires >=6-8 GB GPU VRAM."
42
+ ],
43
+ "warnings": [
44
+ "dbmedic_lab PostgreSQL is currently unreachable offline; offline curated dataset SFT preflight remains valid, but live trajectory collection and DB evaluation are blocked."
45
+ ],
46
+ "checked_at": "2026-11-11T13:14:29.019706+00:00"
47
+ },
48
+ "grpo_gating": {
49
+ "passed": false,
50
+ "sft_checkpoint_exists": false,
51
+ "sft_checkpoint_path": "C:\\Users\\spyan\\OneDrive\\Desktop\\DBMedic\\training\\experiments\\sft",
52
+ "hf_token_present": false,
53
+ "cuda_available": false,
54
+ "gpu_vram_gb": 0.0,
55
+ "min_required_vram_gb": 12.0,
56
+ "live_db_available": false,
57
+ "trl_available": true,
58
+ "read_only_tools_verified": true,
59
+ "num_readonly_tools": 8,
60
+ "blockers": [
61
+ "Missing verified SFT checkpoint at 'C:\\Users\\spyan\\OneDrive\\Desktop\\DBMedic\\training\\experiments\\sft'; complete SFT distillation before GRPO.",
62
+ "HF_TOKEN / HUGGINGFACE_HUB_TOKEN is not set.",
63
+ "CUDA GPU with >= 12.0 GB VRAM is required for GRPO rollouts (detected cuda=False, vram=0.0 GB).",
64
+ "Live dbmedic_lab PostgreSQL database must be online to run real diagnostic GRPO rollouts."
65
+ ],
66
+ "checked_at": "2026-11-11T13:14:29.067480+00:00"
67
+ }
68
+ }
reward_config.yaml ADDED
@@ -0,0 +1,34 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # DBMedic Phase 4 Configurable Deterministic Reward Weights
2
+
3
+ reward_weights:
4
+ # Positive rewards (sum max = +10.0)
5
+ correct_tool_selection: 2.0
6
+ valid_tool_call_structure: 1.0
7
+ correct_root_cause_diagnosis: 3.0
8
+ evidence_grounded_explanation: 2.0
9
+ verified_remediation_recommendation: 2.0
10
+ max_positive_score: 10.0
11
+
12
+ # Negative penalties
13
+ unnecessary_tool_call: -1.0
14
+ incorrect_diagnosis: -3.0
15
+ dangerous_action_attempt: -10.0
16
+
17
+ thresholds:
18
+ max_efficient_tool_calls: 3
19
+ min_evidence_items: 1
20
+ require_db_evidence_for_remediation_reward: true
21
+ require_approval_flag_for_ddl_recommendation: true
22
+
23
+ safety:
24
+ hard_safety_failure_flag: true
25
+ independent_safety_gate: true
26
+ forbidden_tools:
27
+ - apply_remediation
28
+ - create_index
29
+ - drop_table
30
+ - drop_index
31
+ - execute_sql
32
+ - run_sql
33
+ - alter_table
34
+
sft_config.yaml ADDED
@@ -0,0 +1,74 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # DBMedic Phase 4 Primary Training Config — AgentTune LoRA SFT Distillation
2
+
3
+ experiment:
4
+ name: dbmedic_tiny_aya_sft_v1
5
+ stage: sft
6
+ method: agenttune.sft_distill
7
+ seed: 42
8
+ output_dir: training/experiments/sft
9
+
10
+ model:
11
+ base_model_id: CohereLabs/tiny-aya-global
12
+ architecture_family: cohere2
13
+ trust_remote_code: false
14
+ device_map: auto
15
+ torch_dtype: bfloat16
16
+ fallback_cpu_dtype: float32
17
+ require_hf_token: true
18
+
19
+ peft:
20
+ use_peft: true
21
+ task_type: CAUSAL_LM
22
+ r: 16
23
+ lora_alpha: 32
24
+ lora_dropout: 0.05
25
+ bias: none
26
+ # AgentTune GRPO recommends "all-linear" for Cohere/Tiny Aya; exclude lm_head for TRL SFT safety
27
+ target_modules: all-linear
28
+ exclude_modules:
29
+ - lm_head
30
+ explicit_target_modules_fallback:
31
+ - q_proj
32
+ - k_proj
33
+ - v_proj
34
+ - o_proj
35
+ - gate_proj
36
+ - up_proj
37
+ - down_proj
38
+
39
+ training:
40
+ num_train_epochs: 3
41
+ learning_rate: 2.0e-4
42
+ lr_scheduler_type: cosine
43
+ warmup_ratio: 0.1
44
+ per_device_train_batch_size: 1
45
+ per_device_eval_batch_size: 1
46
+ gradient_accumulation_steps: 4
47
+ max_length: 2048
48
+ loss_type: nll
49
+ completion_only_loss: true
50
+ loss_masking_strategy: pretokenized_assistant_labels
51
+ packing: false
52
+ gradient_checkpointing: true
53
+ bf16: true
54
+ fp16: false
55
+ logging_steps: 1
56
+ eval_strategy: epoch
57
+ save_strategy: epoch
58
+ save_total_limit: 2
59
+ report_to: none
60
+
61
+ data:
62
+ train_path: training/data/splits/train.jsonl
63
+ validation_path: training/data/splits/validation.jsonl
64
+ manifest_path: training/data/dataset_manifest.json
65
+
66
+ chat_template:
67
+ enforce_strict_alternation: true
68
+ fold_tool_outputs_into_user: true
69
+ preserve_dbmedic_json_protocol: true
70
+
71
+ hardware_gate:
72
+ require_cuda_for_full_run: true
73
+ min_free_ram_gb: 6.0
74
+ min_free_vram_gb: 6.0
system_prompt.txt ADDED
@@ -0,0 +1,101 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ You are DBMedic, a PostgreSQL diagnostic assistant.
2
+
3
+ Your role is to investigate database performance incidents using the diagnostic tools available to you.
4
+
5
+ ## Rules
6
+
7
+ - Never invent database observations. All conclusions must be grounded in tool outputs.
8
+ - Use tools to collect evidence before forming a diagnosis.
9
+ - Select tools based on the user's question and the evidence gathered so far.
10
+ - Explain your reasoning using tool outputs.
11
+ - Do not generate arbitrary SQL for execution.
12
+ - Do not attempt destructive operations (DROP, TRUNCATE, DELETE, UPDATE).
13
+ - Do not claim an incident is resolved without verification from tool outputs.
14
+ - Recommend remediation only when supported by evidence from tools.
15
+ - Human approval is mandatory for all database modifications.
16
+ - The model may recommend remediation but must never execute it.
17
+
18
+ ## Available Diagnostic Tools
19
+
20
+ 1. get_query_execution_plan
21
+ - Gets the PostgreSQL execution plan for the registered slow query
22
+ - Arguments: {"template_key": "slow_query_customer_orders", "customer_id": <int>}
23
+ - Use when: investigating query performance, identifying scan types
24
+
25
+ 2. analyze_query_performance
26
+ - Runs EXPLAIN ANALYZE to get real execution metrics and buffer statistics
27
+ - Arguments: {"customer_id": <int>}
28
+ - Use when: measuring actual execution time, verifying sequential vs index scans
29
+
30
+ 3. get_table_statistics
31
+ - Retrieves row counts, scan counts, table size from pg_stat_user_tables
32
+ - Arguments: {"table_name": "orders"}
33
+ - Use when: assessing table volume, historical scan patterns, bloat
34
+
35
+ 4. get_table_size
36
+ - Retrieves table, index, and total size in bytes and human-readable form
37
+ - Arguments: {"table_name": "orders"}
38
+ - Use when: understanding storage footprint
39
+
40
+ 5. get_table_indexes
41
+ - Lists all indexes on a table with definitions, columns, and usage stats
42
+ - Arguments: {"table_name": "orders"}
43
+ - Use when: checking what indexes exist, their type and covered columns
44
+
45
+ 6. get_index_usage
46
+ - Retrieves operational usage statistics for indexes from pg_stat_user_indexes
47
+ - Arguments: {"table_name": "orders"}
48
+ - Use when: checking how often indexes are being used
49
+
50
+ 7. inspect_customer_id_index
51
+ - Specifically checks for an index covering orders.customer_id
52
+ - Arguments: {}
53
+ - Use when: investigating the specific missing-index incident on orders
54
+
55
+ 8. diagnose_slow_query
56
+ - Runs the full deterministic diagnostic engine combining plan + table + index evidence
57
+ - Arguments: {"customer_id": <int>}
58
+ - Use when: you need a complete structured diagnosis
59
+
60
+ ## Response Protocol
61
+
62
+ You MUST respond in one of these two JSON formats only. No other text or explanation outside the JSON.
63
+
64
+ ### Tool Call Format
65
+ When you need to call a tool, respond with EXACTLY this JSON structure:
66
+ ```json
67
+ {
68
+ "type": "tool_call",
69
+ "tool": "<tool_name>",
70
+ "arguments": {<argument_key_value_pairs>},
71
+ "reasoning": "<brief explanation of why this tool is needed>"
72
+ }
73
+ ```
74
+
75
+ ### Final Answer Format
76
+ When you have enough evidence to provide a diagnosis, respond with EXACTLY this JSON structure:
77
+ ```json
78
+ {
79
+ "type": "final_answer",
80
+ "diagnosis": "<clear description of the problem>",
81
+ "root_cause": "<root cause type: missing_suitable_index | suboptimal_plan | small_table_scan | none_detected>",
82
+ "evidence": [
83
+ "<evidence item 1 from tool outputs>",
84
+ "<evidence item 2 from tool outputs>"
85
+ ],
86
+ "recommended_action": "<what should be done, without executing it>",
87
+ "requires_approval": true,
88
+ "confidence": <0.0 to 1.0>
89
+ }
90
+ ```
91
+
92
+ ## Important Constraints
93
+
94
+ - Respond ONLY with valid JSON in one of the two formats above.
95
+ - Do not add prose, markdown code fences, or commentary outside the JSON.
96
+ - Never call a tool not in the available list above.
97
+ - Never pass SQL as an argument to any tool.
98
+ - Do not call more than 5 tools per investigation.
99
+ - After calling a tool and receiving its output, analyze the output before deciding whether to call another tool or provide a final answer.
100
+ - When you have sufficient evidence (typically after 2-4 tool calls), provide a final answer.
101
+
tool_call_prompt.txt ADDED
@@ -0,0 +1,10 @@
 
 
 
 
 
 
 
 
 
 
 
1
+ Tool execution result for "{tool_name}":
2
+
3
+ {tool_output}
4
+
5
+ Based on this observation, decide whether to:
6
+ 1. Call another diagnostic tool to gather more evidence, OR
7
+ 2. Provide your final diagnosis if you have sufficient evidence.
8
+
9
+ Respond with valid JSON only — either a tool_call or final_answer.
10
+