nl2sql-agents 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. nl2sql_agents-0.1.0/.env.example +20 -0
  2. nl2sql_agents-0.1.0/.gitignore +63 -0
  3. nl2sql_agents-0.1.0/Assets/architecture.svg +432 -0
  4. nl2sql_agents-0.1.0/Assets/nl2sql-architecture.svg +364 -0
  5. nl2sql_agents-0.1.0/Assets/nl2sql.gif +0 -0
  6. nl2sql_agents-0.1.0/FAME_PLAN.md +415 -0
  7. nl2sql_agents-0.1.0/LICENSE +21 -0
  8. nl2sql_agents-0.1.0/MEMORY_IMPLEMENTATION.md +629 -0
  9. nl2sql_agents-0.1.0/PKG-INFO +540 -0
  10. nl2sql_agents-0.1.0/README.md +498 -0
  11. nl2sql_agents-0.1.0/logs/nl2sql_20260303_213721.log +96 -0
  12. nl2sql_agents-0.1.0/logs/nl2sql_20260305_214621.log +174 -0
  13. nl2sql_agents-0.1.0/logs/nl2sql_20260305_215644.log +42 -0
  14. nl2sql_agents-0.1.0/logs/nl2sql_20260305_223227.log +42 -0
  15. nl2sql_agents-0.1.0/main.py +12 -0
  16. nl2sql_agents-0.1.0/nl2sql_agents/__init__.py +9 -0
  17. nl2sql_agents-0.1.0/nl2sql_agents/agents/__init__.py +0 -0
  18. nl2sql_agents-0.1.0/nl2sql_agents/agents/base_agent.py +74 -0
  19. nl2sql_agents-0.1.0/nl2sql_agents/agents/discovery/__init__.py +0 -0
  20. nl2sql_agents-0.1.0/nl2sql_agents/agents/discovery/discovery_agent.py +117 -0
  21. nl2sql_agents-0.1.0/nl2sql_agents/agents/discovery/fk_graph_agent.py +75 -0
  22. nl2sql_agents-0.1.0/nl2sql_agents/agents/discovery/keyword_agent.py +61 -0
  23. nl2sql_agents-0.1.0/nl2sql_agents/agents/discovery/semantic_agent.py +61 -0
  24. nl2sql_agents-0.1.0/nl2sql_agents/agents/explainer/__init__.py +0 -0
  25. nl2sql_agents-0.1.0/nl2sql_agents/agents/explainer/explainer_agent.py +45 -0
  26. nl2sql_agents-0.1.0/nl2sql_agents/agents/explainer/explanation_agent.py +32 -0
  27. nl2sql_agents-0.1.0/nl2sql_agents/agents/explainer/optimization_agent.py +31 -0
  28. nl2sql_agents-0.1.0/nl2sql_agents/agents/explainer/safety_report_agent.py +42 -0
  29. nl2sql_agents-0.1.0/nl2sql_agents/agents/query_generator.py +133 -0
  30. nl2sql_agents-0.1.0/nl2sql_agents/agents/schema_formatter.py +69 -0
  31. nl2sql_agents-0.1.0/nl2sql_agents/agents/validator/__init__.py +0 -0
  32. nl2sql_agents-0.1.0/nl2sql_agents/agents/validator/logic_validator.py +59 -0
  33. nl2sql_agents-0.1.0/nl2sql_agents/agents/validator/performance_validator.py +74 -0
  34. nl2sql_agents-0.1.0/nl2sql_agents/agents/validator/security_validator.py +51 -0
  35. nl2sql_agents-0.1.0/nl2sql_agents/agents/validator/syntax_validator.py +74 -0
  36. nl2sql_agents-0.1.0/nl2sql_agents/agents/validator/validator_agent.py +104 -0
  37. nl2sql_agents-0.1.0/nl2sql_agents/cli.py +291 -0
  38. nl2sql_agents-0.1.0/nl2sql_agents/config/__init__.py +0 -0
  39. nl2sql_agents-0.1.0/nl2sql_agents/config/settings.py +66 -0
  40. nl2sql_agents-0.1.0/nl2sql_agents/db/__init__.py +0 -0
  41. nl2sql_agents-0.1.0/nl2sql_agents/db/connector.py +107 -0
  42. nl2sql_agents-0.1.0/nl2sql_agents/filters/__init__.py +0 -0
  43. nl2sql_agents-0.1.0/nl2sql_agents/filters/gate.py +62 -0
  44. nl2sql_agents-0.1.0/nl2sql_agents/filters/security_filter.py +36 -0
  45. nl2sql_agents-0.1.0/nl2sql_agents/models/__init__.py +0 -0
  46. nl2sql_agents-0.1.0/nl2sql_agents/models/schemas.py +120 -0
  47. nl2sql_agents-0.1.0/nl2sql_agents/orchestrator/__init__.py +0 -0
  48. nl2sql_agents-0.1.0/nl2sql_agents/orchestrator/nodes.py +142 -0
  49. nl2sql_agents-0.1.0/nl2sql_agents/orchestrator/pipeline.py +70 -0
  50. nl2sql_agents-0.1.0/nl2sql_agents/py.typed +0 -0
  51. nl2sql_agents-0.1.0/pyproject.toml +88 -0
  52. nl2sql_agents-0.1.0/requirements.txt +9 -0
nl2sql_agents-0.1.0/.env.example ADDED
@@ -0,0 +1,20 @@
1
+ # ── OpenAI Provider ──────────────────────────────
2
+ OPENAI_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxx
3
+ OPENAI_BASE_URL=https://openrouter.ai/api/v1
4
+ OPENAI_MODEL=openai/gpt-4o
5
+
6
+ # ── Gemini Provider ──────────────────────────────
7
+ GEMINI_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxx
8
+ GEMINI_BASE_URL=https://openrouter.ai/api/v1
9
+ GEMINI_MODEL=google/gemini-2.5-flash
10
+
11
+ # ── Database ─────────────────────────────────────
12
+ DB_TYPE=sqlite
13
+ DB_PATH=./data/spider/database/concert_singer/concert_singer.sqlite
14
+
15
+ # ── Pipeline Tuning ─────────────────────────────
16
+ CACHE_TTL_HOURS=24
17
+ N_CANDIDATES=3
18
+ MAX_RETRIES=2
19
+ DISCOVERY_TOP_K=5
20
+ KEYWORD_PRE_FILTER_TOP_N=50
nl2sql_agents-0.1.0/.gitignore ADDED
@@ -0,0 +1,63 @@
1
+ # Byte-compiled / optimized files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # Virtual environments
7
+ .venv/
8
+ venv/
9
+ env/
10
+ ENV/
11
+
12
+ # Packaging / build artifacts
13
+ build/
14
+ dist/
15
+ *.egg-info/
16
+ *.egg
17
+ .eggs/
18
+ pip-wheel-metadata/
19
+
20
+ # Test / coverage
21
+ .pytest_cache/
22
+ .coverage
23
+ .coverage.*
24
+ htmlcov/
25
+ .tox/
26
+
27
+ # Type checker / linters
28
+ .mypy_cache/
29
+ .ruff_cache/
30
+ .pyright/
31
+
32
+ # Local env files
33
+ .env
34
+ .env.*
35
+ !.env.example
36
+
37
+ # Editor / OS files
38
+ .vscode/
39
+ .idea/
40
+ *.swp
41
+ *.swo
42
+ .DS_Store
43
+ Thumbs.db
44
+
45
+ # Project cache/output
46
+ cache/
47
+
48
+ # Large database files (download separately - see README.md)
49
+ spider/
50
+ data/
51
+ archive.zip
52
+ *.sqlite
53
+ *.sqlite3
54
+ *.db
55
+
56
+ # Notebooks
57
+ .ipynb_checkpoints/
58
+
59
+ # Keys / local secrets
60
+ *.pem
61
+ *.key
62
+ secrets.yaml
63
+ secrets.json
nl2sql_agents-0.1.0/Assets/architecture.svg ADDED
@@ -0,0 +1,432 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 2420" width="1200" height="2420"
3
+ font-family="'Segoe UI','Helvetica Neue',system-ui,Arial,sans-serif">
4
+
5
+ <defs>
6
+ <marker id="ah" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
7
+ <path d="M 0 0 L 10 5 L 0 10 z" fill="#546E7A"/>
8
+ </marker>
9
+ <marker id="ah-warn" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
10
+ <path d="M 0 0 L 10 5 L 0 10 z" fill="#C62828"/>
11
+ </marker>
12
+ <marker id="ah-ok" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
13
+ <path d="M 0 0 L 10 5 L 0 10 z" fill="#2E7D32"/>
14
+ </marker>
15
+ </defs>
16
+
17
+ <!-- ============================================================ -->
18
+ <!-- BACKGROUND -->
19
+ <!-- ============================================================ -->
20
+ <rect width="1200" height="2420" fill="#FFFFFF"/>
21
+
22
+ <!-- ============================================================ -->
23
+ <!-- TITLE -->
24
+ <!-- ============================================================ -->
25
+ <text x="600" y="30" text-anchor="middle" font-size="22" font-weight="700" fill="#1A237E"
26
+ letter-spacing="0.5">NL2SQL — Multi-Agent System Architecture</text>
27
+ <text x="600" y="52" text-anchor="middle" font-size="12" fill="#546E7A">
28
+ LangGraph-Orchestrated Pipeline · Multi-Signal Discovery · Parallel Validation · Explainable Output</text>
29
+
30
+ <!-- ============================================================ -->
31
+ <!-- 1. USER INTERFACE LAYER -->
32
+ <!-- ============================================================ -->
33
+ <text x="600" y="80" text-anchor="middle" font-size="11" font-weight="600" fill="#37474F"
34
+ letter-spacing="1.5" text-decoration="none" opacity="0.7">USER INTERFACE LAYER</text>
35
+
36
+ <rect x="295" y="90" width="270" height="42" rx="8" fill="#E1F5FE" stroke="#0277BD" stroke-width="1.5"/>
37
+ <text x="430" y="110" text-anchor="middle" font-size="12" font-weight="600" fill="#01579B">Natural Language Query Input</text>
38
+ <text x="430" y="124" text-anchor="middle" font-size="9.5" fill="#0277BD">Free-form English Questions</text>
39
+
40
+ <rect x="595" y="90" width="270" height="42" rx="8" fill="#E1F5FE" stroke="#0277BD" stroke-width="1.5"/>
41
+ <text x="730" y="110" text-anchor="middle" font-size="12" font-weight="600" fill="#01579B">Command Line Interface</text>
42
+ <text x="730" y="124" text-anchor="middle" font-size="9.5" fill="#0277BD">Interactive / Batch Mode</text>
43
+
44
+ <!-- Arrow: User Interface → LangGraph -->
45
+ <line x1="560" y1="132" x2="560" y2="162" stroke="#546E7A" stroke-width="1.5" marker-end="url(#ah)"/>
46
+
47
+ <!-- ============================================================ -->
48
+ <!-- 2. LANGGRAPH ORCHESTRATION LAYER -->
49
+ <!-- ============================================================ -->
50
+ <rect x="80" y="155" width="1040" height="155" rx="12" fill="#FAFBFC" stroke="#90A4AE" stroke-width="1.5" stroke-dasharray="8,4"/>
51
+ <text x="600" y="148" text-anchor="middle" font-size="12" font-weight="700" fill="#1A237E"
52
+ letter-spacing="1">LANGGRAPH ORCHESTRATION LAYER</text>
53
+
54
+ <!-- StateGraph Controller -->
55
+ <rect x="110" y="178" width="290" height="58" rx="8" fill="#E0F2F1" stroke="#00695C" stroke-width="1.5"/>
56
+ <text x="255" y="200" text-anchor="middle" font-size="13" font-weight="700" fill="#004D40">StateGraph Controller</text>
57
+ <text x="255" y="216" text-anchor="middle" font-size="10" fill="#00695C">Graph/State Management</text>
58
+ <text x="255" y="229" text-anchor="middle" font-size="10" fill="#00695C">Conditional Edge Routing</text>
59
+
60
+ <!-- GraphState TypedDict -->
61
+ <rect x="470" y="170" width="580" height="130" rx="8" fill="#E0F2F1" stroke="#00695C" stroke-width="1.5"/>
62
+ <text x="760" y="190" text-anchor="middle" font-size="13" font-weight="700" fill="#004D40">GraphState (TypedDict)</text>
63
+
64
+ <text x="595" y="210" text-anchor="middle" font-size="9.5" fill="#00695C" font-family="'Courier New',monospace">user_query</text>
65
+ <text x="595" y="224" text-anchor="middle" font-size="9.5" fill="#00695C" font-family="'Courier New',monospace">tables</text>
66
+ <text x="595" y="238" text-anchor="middle" font-size="9.5" fill="#00695C" font-family="'Courier New',monospace">security_passed</text>
67
+ <text x="595" y="252" text-anchor="middle" font-size="9.5" fill="#00695C" font-family="'Courier New',monospace">discovery_result</text>
68
+ <text x="595" y="266" text-anchor="middle" font-size="9.5" fill="#00695C" font-family="'Courier New',monospace">gated_tables</text>
69
+
70
+ <text x="895" y="210" text-anchor="middle" font-size="9.5" fill="#00695C" font-family="'Courier New',monospace">formatted_schema</text>
71
+ <text x="895" y="224" text-anchor="middle" font-size="9.5" fill="#00695C" font-family="'Courier New',monospace">generation</text>
72
+ <text x="895" y="238" text-anchor="middle" font-size="9.5" fill="#00695C" font-family="'Courier New',monospace">validation</text>
73
+ <text x="895" y="252" text-anchor="middle" font-size="9.5" fill="#00695C" font-family="'Courier New',monospace">retry_context</text>
74
+ <text x="895" y="266" text-anchor="middle" font-size="9.5" fill="#00695C" font-family="'Courier New',monospace">attempt · output</text>
75
+
76
+ <!-- Arrow: LangGraph → Pre-Processing -->
77
+ <line x1="560" y1="310" x2="560" y2="343" stroke="#546E7A" stroke-width="1.5" marker-end="url(#ah)"/>
78
+
79
+ <!-- ============================================================ -->
80
+ <!-- 3. PRE-PROCESSING LAYER -->
81
+ <!-- ============================================================ -->
82
+ <rect x="45" y="340" width="1110" height="175" rx="12" fill="#FAFBFC" stroke="#90A4AE" stroke-width="1.5" stroke-dasharray="8,4"/>
83
+ <text x="600" y="334" text-anchor="middle" font-size="12" font-weight="700" fill="#1A237E"
84
+ letter-spacing="1">PRE-PROCESSING LAYER</text>
85
+
86
+ <!-- Schema Loader -->
87
+ <rect x="370" y="358" width="320" height="55" rx="8" fill="#E8EAF6" stroke="#3949AB" stroke-width="1.5"/>
88
+ <text x="530" y="380" text-anchor="middle" font-size="13" font-weight="700" fill="#1A237E">Schema Loader</text>
89
+ <text x="530" y="396" text-anchor="middle" font-size="10" fill="#3949AB">Async DB Introspection · Table, Column, FK Discovery</text>
90
+
91
+ <!-- Arrows from Schema Loader to sub-components -->
92
+ <line x1="370" y1="400" x2="195" y2="432" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
93
+ <line x1="530" y1="413" x2="530" y2="432" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
94
+ <line x1="690" y1="400" x2="850" y2="432" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
95
+
96
+ <!-- Cache flow labels -->
97
+ <text x="315" y="418" text-anchor="middle" font-size="8.5" fill="#78909C" font-style="italic">Cache Miss</text>
98
+ <text x="530" y="428" text-anchor="middle" font-size="8.5" fill="#78909C" font-style="italic">Schema Data</text>
99
+ <text x="730" y="418" text-anchor="middle" font-size="8.5" fill="#78909C" font-style="italic">Cache Hit</text>
100
+
101
+ <!-- Data Layer -->
102
+ <rect x="60" y="435" width="250" height="62" rx="8" fill="#F3E5F5" stroke="#7B1FA2" stroke-width="1.5"/>
103
+ <text x="185" y="457" text-anchor="middle" font-size="12" font-weight="700" fill="#4A148C">Data Layer</text>
104
+ <text x="185" y="472" text-anchor="middle" font-size="10" fill="#7B1FA2">SQLite Databases · Spider Dataset</text>
105
+ <text x="185" y="486" text-anchor="middle" font-size="10" fill="#7B1FA2">200+ Domains</text>
106
+
107
+ <!-- Schema Cache -->
108
+ <rect x="380" y="435" width="280" height="62" rx="8" fill="#E8EAF6" stroke="#3949AB" stroke-width="1.5"/>
109
+ <text x="520" y="457" text-anchor="middle" font-size="12" font-weight="700" fill="#1A237E">Schema Cache</text>
110
+ <text x="520" y="472" text-anchor="middle" font-size="10" fill="#3949AB">Dictionary LRU Cache</text>
111
+ <text x="520" y="486" text-anchor="middle" font-size="10" fill="#3949AB">TTL-based Invalidation</text>
112
+
113
+ <!-- Security Filter -->
114
+ <rect x="730" y="435" width="280" height="62" rx="8" fill="#E8EAF6" stroke="#3949AB" stroke-width="1.5"/>
115
+ <text x="870" y="457" text-anchor="middle" font-size="12" font-weight="700" fill="#1A237E">Security Filter</text>
116
+ <text x="870" y="472" text-anchor="middle" font-size="10" fill="#3949AB">Rule-based Threat Detection</text>
117
+ <text x="870" y="486" text-anchor="middle" font-size="10" fill="#3949AB">Regex Pattern Matching</text>
118
+
119
+ <!-- Arrow: Pre-Processing → Discovery (with "Safe" label) -->
120
+ <line x1="560" y1="515" x2="560" y2="555" stroke="#2E7D32" stroke-width="1.5" marker-end="url(#ah-ok)"/>
121
+ <rect x="535" y="525" width="50" height="16" rx="4" fill="#E8F5E9"/>
122
+ <text x="560" y="537" text-anchor="middle" font-size="9" font-weight="600" fill="#2E7D32">Safe</text>
123
+
124
+ <!-- ============================================================ -->
125
+ <!-- 4. DISCOVERY LAYER — MULTI-SIGNAL FUSION -->
126
+ <!-- ============================================================ -->
127
+ <rect x="45" y="555" width="1110" height="330" rx="12" fill="#FAFBFC" stroke="#90A4AE" stroke-width="1.5" stroke-dasharray="8,4"/>
128
+ <text x="600" y="549" text-anchor="middle" font-size="12" font-weight="700" fill="#1A237E"
129
+ letter-spacing="1">DISCOVERY LAYER — MULTI-SIGNAL FUSION</text>
130
+
131
+ <!-- Discovery Orchestrator -->
132
+ <rect x="385" y="573" width="300" height="47" rx="8" fill="#E0F2F1" stroke="#00695C" stroke-width="1.5"/>
133
+ <text x="535" y="594" text-anchor="middle" font-size="13" font-weight="700" fill="#004D40">Discovery Orchestrator</text>
134
+ <text x="535" y="610" text-anchor="middle" font-size="10" fill="#00695C">Parallel Signal Processing</text>
135
+
136
+ <!-- Label: Parallel Signals -->
137
+ <text x="535" y="643" text-anchor="middle" font-size="10" font-weight="600" fill="#78909C" font-style="italic">─── Parallel Signals ───</text>
138
+
139
+ <!-- Arrows: Orchestrator → 3 signals -->
140
+ <line x1="420" y1="620" x2="215" y2="653" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
141
+ <line x1="535" y1="620" x2="535" y2="653" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
142
+ <line x1="650" y1="620" x2="855" y2="653" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
143
+
144
+ <!-- Keyword Signal -->
145
+ <rect x="60" y="655" width="310" height="95" rx="8" fill="#FFF8E1" stroke="#F9A825" stroke-width="1.5"/>
146
+ <text x="215" y="676" text-anchor="middle" font-size="12" font-weight="700" fill="#E65100">Keyword Signal</text>
147
+ <text x="215" y="694" text-anchor="middle" font-size="10" fill="#F57F17">Algorithm: TF-IDF + Token Match</text>
148
+ <text x="215" y="710" text-anchor="middle" font-size="10" fill="#F57F17">Model: None (rule-based)</text>
149
+ <text x="215" y="726" text-anchor="middle" font-size="10" fill="#F57F17">Weight: 0.35</text>
150
+ <text x="215" y="742" text-anchor="middle" font-size="10" fill="#F57F17">Output: Relevance Scores</text>
151
+
152
+ <!-- Semantic Signal -->
153
+ <rect x="400" y="655" width="310" height="95" rx="8" fill="#FFF8E1" stroke="#F9A825" stroke-width="1.5"/>
154
+ <text x="555" y="676" text-anchor="middle" font-size="12" font-weight="700" fill="#E65100">Semantic Signal</text>
155
+ <text x="555" y="694" text-anchor="middle" font-size="10" fill="#F57F17">Algorithm: Cosine Similarity</text>
156
+ <text x="555" y="710" text-anchor="middle" font-size="10" fill="#F57F17">Embeddings: text-embedding-3-small</text>
157
+ <text x="555" y="726" text-anchor="middle" font-size="10" fill="#F57F17">Weight: 0.45</text>
158
+ <text x="555" y="742" text-anchor="middle" font-size="10" fill="#F57F17">Output: Similarity Matrix</text>
159
+
160
+ <!-- FK Graph Signal -->
161
+ <rect x="740" y="655" width="310" height="95" rx="8" fill="#FFF8E1" stroke="#F9A825" stroke-width="1.5"/>
162
+ <text x="895" y="676" text-anchor="middle" font-size="12" font-weight="700" fill="#E65100">FK Graph Signal</text>
163
+ <text x="895" y="694" text-anchor="middle" font-size="10" fill="#F57F17">Algorithm: PageRank on DAG</text>
164
+ <text x="895" y="710" text-anchor="middle" font-size="10" fill="#F57F17">Graph: Foreign Key Relationships</text>
165
+ <text x="895" y="726" text-anchor="middle" font-size="10" fill="#F57F17">Weight: 0.20</text>
166
+ <text x="895" y="742" text-anchor="middle" font-size="10" fill="#F57F17">Output: Centrality Scores</text>
167
+
168
+ <!-- Arrows: 3 signals → Score Fusion -->
169
+ <line x1="215" y1="750" x2="430" y2="790" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
170
+ <line x1="555" y1="750" x2="555" y2="790" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
171
+ <line x1="895" y1="750" x2="690" y2="790" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
172
+
173
+ <!-- Score Fusion Engine -->
174
+ <polygon points="555,785 740,817 555,849 370,817" fill="#FCE4EC" stroke="#AD1457" stroke-width="1.5"/>
175
+ <text x="555" y="813" text-anchor="middle" font-size="12" font-weight="700" fill="#880E4F">Score Fusion Engine</text>
176
+ <text x="555" y="828" text-anchor="middle" font-size="9.5" fill="#AD1457">Weighted Sum · Descending Rank</text>
177
+
178
+ <!-- Arrow: Discovery → Context Optimization -->
179
+ <line x1="555" y1="849" x2="555" y2="860" stroke="#546E7A" stroke-width="0"/>
180
+ <line x1="555" y1="855" x2="555" y2="915" stroke="#546E7A" stroke-width="1.5" marker-end="url(#ah)"/>
181
+
182
+ <!-- ============================================================ -->
183
+ <!-- 5. CONTEXT OPTIMIZATION LAYER -->
184
+ <!-- ============================================================ -->
185
+ <rect x="170" y="910" width="860" height="175" rx="12" fill="#FAFBFC" stroke="#90A4AE" stroke-width="1.5" stroke-dasharray="8,4"/>
186
+ <text x="600" y="904" text-anchor="middle" font-size="12" font-weight="700" fill="#1A237E"
187
+ letter-spacing="1">CONTEXT OPTIMIZATION LAYER</text>
188
+
189
+ <!-- Gate Mechanism -->
190
+ <rect x="365" y="928" width="340" height="55" rx="8" fill="#E8EAF6" stroke="#3949AB" stroke-width="1.5"/>
191
+ <text x="535" y="950" text-anchor="middle" font-size="13" font-weight="700" fill="#1A237E">Gate Mechanism</text>
192
+ <text x="535" y="967" text-anchor="middle" font-size="10" fill="#3949AB">Top-K Selection · Token Budget Management</text>
193
+
194
+ <!-- Arrow: Gate → Schema Formatter -->
195
+ <line x1="535" y1="983" x2="535" y2="1005" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
196
+
197
+ <!-- Schema Formatter -->
198
+ <rect x="365" y="1008" width="340" height="55" rx="8" fill="#E8EAF6" stroke="#3949AB" stroke-width="1.5"/>
199
+ <text x="535" y="1030" text-anchor="middle" font-size="13" font-weight="700" fill="#1A237E">Schema Formatter</text>
200
+ <text x="535" y="1047" text-anchor="middle" font-size="10" fill="#3949AB">DDL Generation · Context Window Optimization</text>
201
+
202
+ <!-- Arrow: Context → LLM Generation -->
203
+ <line x1="535" y1="1085" x2="535" y2="1130" stroke="#546E7A" stroke-width="1.5" marker-end="url(#ah)"/>
204
+
205
+ <!-- ============================================================ -->
206
+ <!-- 6. LLM GENERATION LAYER -->
207
+ <!-- ============================================================ -->
208
+ <rect x="170" y="1125" width="860" height="220" rx="12" fill="#FAFBFC" stroke="#90A4AE" stroke-width="1.5" stroke-dasharray="8,4"/>
209
+ <text x="600" y="1119" text-anchor="middle" font-size="12" font-weight="700" fill="#1A237E"
210
+ letter-spacing="1">LLM GENERATION LAYER</text>
211
+
212
+ <!-- Query Generator -->
213
+ <rect x="340" y="1148" width="385" height="72" rx="8" fill="#E8EAF6" stroke="#3949AB" stroke-width="1.5"/>
214
+ <text x="533" y="1172" text-anchor="middle" font-size="13" font-weight="700" fill="#1A237E">Query Generator</text>
215
+ <text x="533" y="1190" text-anchor="middle" font-size="10" fill="#3949AB">Model: GPT-4o-mini · Temperature: [0.3, 0.5, 0.7]</text>
216
+ <text x="533" y="1206" text-anchor="middle" font-size="10" fill="#3949AB">Strategy: Few-Shot + CoT · N=3 Candidates</text>
217
+
218
+ <!-- Arrow: Generator → Retry decision -->
219
+ <line x1="533" y1="1220" x2="533" y2="1252" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
220
+
221
+ <!-- Retry Controller (diamond) -->
222
+ <polygon points="533,1248 635,1283 533,1318 431,1283" fill="#FFF3E0" stroke="#E65100" stroke-width="1.5"/>
223
+ <text x="533" y="1280" text-anchor="middle" font-size="11" font-weight="700" fill="#BF360C">Retry Controller</text>
224
+ <text x="533" y="1296" text-anchor="middle" font-size="9" fill="#E65100">Max: 2 · Error-Aware</text>
225
+
226
+ <!-- Retry loop arrow (left side): Retry → back to Generator -->
227
+ <path d="M 431,1283 L 310,1283 L 310,1184 L 340,1184" fill="none"
228
+ stroke="#C62828" stroke-width="1.3" stroke-dasharray="5,3" marker-end="url(#ah-warn)"/>
229
+ <text x="280" y="1235" text-anchor="middle" font-size="9" font-weight="600" fill="#C62828"
230
+ transform="rotate(-90,280,1235)">Failed &amp; Retry</text>
231
+
232
+ <!-- "Unsafe" label going right -->
233
+ <line x1="635" y1="1283" x2="1060" y2="1283" stroke="#C62828" stroke-width="1.3" stroke-dasharray="5,3" marker-end="url(#ah-warn)"/>
234
+ <text x="1080" y="1287" text-anchor="start" font-size="10" font-weight="600" fill="#C62828">Unsafe</text>
235
+
236
+ <!-- Arrow: Retry → Validation (Success) -->
237
+ <line x1="533" y1="1318" x2="533" y2="1345" stroke="#546E7A" stroke-width="0"/>
238
+ <line x1="533" y1="1328" x2="533" y2="1395" stroke="#2E7D32" stroke-width="1.5" marker-end="url(#ah-ok)"/>
239
+ <rect x="505" y="1350" width="65" height="16" rx="4" fill="#E8F5E9"/>
240
+ <text x="537" y="1362" text-anchor="middle" font-size="9" font-weight="600" fill="#2E7D32">Success</text>
241
+
242
+ <!-- ============================================================ -->
243
+ <!-- 7. VALIDATION LAYER — PARALLEL -->
244
+ <!-- ============================================================ -->
245
+ <rect x="45" y="1390" width="1110" height="290" rx="12" fill="#FAFBFC" stroke="#90A4AE" stroke-width="1.5" stroke-dasharray="8,4"/>
246
+ <text x="600" y="1384" text-anchor="middle" font-size="12" font-weight="700" fill="#1A237E"
247
+ letter-spacing="1">VALIDATION LAYER — PARALLEL</text>
248
+
249
+ <!-- Validator Orchestrator -->
250
+ <rect x="370" y="1410" width="320" height="47" rx="8" fill="#E0F2F1" stroke="#00695C" stroke-width="1.5"/>
251
+ <text x="530" y="1432" text-anchor="middle" font-size="13" font-weight="700" fill="#004D40">Validator Orchestrator</text>
252
+ <text x="530" y="1448" text-anchor="middle" font-size="10" fill="#00695C">Async Parallel Execution</text>
253
+
254
+ <!-- Label: Independent Validators -->
255
+ <text x="530" y="1478" text-anchor="middle" font-size="10" font-weight="600" fill="#78909C" font-style="italic">─── Independent Validators ───</text>
256
+
257
+ <!-- Arrows: Orchestrator → 4 validators -->
258
+ <line x1="420" y1="1457" x2="170" y2="1488" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
259
+ <line x1="480" y1="1457" x2="440" y2="1488" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
260
+ <line x1="580" y1="1457" x2="680" y2="1488" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
261
+ <line x1="640" y1="1457" x2="930" y2="1488" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
262
+
263
+ <!-- Syntax Validator -->
264
+ <rect x="60" y="1490" width="240" height="72" rx="8" fill="#FFF8E1" stroke="#F9A825" stroke-width="1.5"/>
265
+ <text x="180" y="1514" text-anchor="middle" font-size="12" font-weight="700" fill="#E65100">Syntax Validator</text>
266
+ <text x="180" y="1532" text-anchor="middle" font-size="10" fill="#F57F17">Parser Validation</text>
267
+ <text x="180" y="1548" text-anchor="middle" font-size="10" fill="#F57F17">AST Feature Analysis</text>
268
+
269
+ <!-- Logic Validator -->
270
+ <rect x="325" y="1490" width="240" height="72" rx="8" fill="#FFF8E1" stroke="#F9A825" stroke-width="1.5"/>
271
+ <text x="445" y="1514" text-anchor="middle" font-size="12" font-weight="700" fill="#E65100">Logic Validator</text>
272
+ <text x="445" y="1532" text-anchor="middle" font-size="10" fill="#F57F17">Schema Consistency</text>
273
+ <text x="445" y="1548" text-anchor="middle" font-size="10" fill="#F57F17">Join Correctness</text>
274
+
275
+ <!-- Security Validator -->
276
+ <rect x="590" y="1490" width="240" height="72" rx="8" fill="#FFF8E1" stroke="#F9A825" stroke-width="1.5"/>
277
+ <text x="710" y="1514" text-anchor="middle" font-size="12" font-weight="700" fill="#E65100">Security Validator</text>
278
+ <text x="710" y="1532" text-anchor="middle" font-size="10" fill="#F57F17">Injection Detection</text>
279
+ <text x="710" y="1548" text-anchor="middle" font-size="10" fill="#F57F17">Privilege Analysis</text>
280
+
281
+ <!-- Performance Validator -->
282
+ <rect x="855" y="1490" width="240" height="72" rx="8" fill="#FFF8E1" stroke="#F9A825" stroke-width="1.5"/>
283
+ <text x="975" y="1514" text-anchor="middle" font-size="12" font-weight="700" fill="#E65100">Performance Validator</text>
284
+ <text x="975" y="1532" text-anchor="middle" font-size="10" fill="#F57F17">Query Complexity Analysis</text>
285
+ <text x="975" y="1548" text-anchor="middle" font-size="10" fill="#F57F17">Index Recommendations</text>
286
+
287
+ <!-- Arrows: 4 validators → Result Aggregator -->
288
+ <line x1="180" y1="1562" x2="430" y2="1603" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
289
+ <line x1="445" y1="1562" x2="490" y2="1603" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
290
+ <line x1="710" y1="1562" x2="590" y2="1603" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
291
+ <line x1="975" y1="1562" x2="660" y2="1603" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
292
+
293
+ <!-- Result Aggregator -->
294
+ <rect x="385" y="1605" width="300" height="50" rx="8" fill="#FCE4EC" stroke="#AD1457" stroke-width="1.5"/>
295
+ <text x="535" y="1627" text-anchor="middle" font-size="12" font-weight="700" fill="#880E4F">Result Aggregator</text>
296
+ <text x="535" y="1643" text-anchor="middle" font-size="10" fill="#AD1457">AND Logic · Error Collection</text>
297
+
298
+ <!-- Retry arrow from Result Aggregator back to Generation Layer (right side) -->
299
+ <path d="M 685,1630 L 1100,1630 L 1100,1184 L 725,1184" fill="none"
300
+ stroke="#C62828" stroke-width="1.3" stroke-dasharray="5,3" marker-end="url(#ah-warn)"/>
301
+ <text x="1125" y="1410" text-anchor="start" font-size="9.5" font-weight="600" fill="#C62828"
302
+ transform="rotate(-90,1125,1410)">Failed &amp; First Retry</text>
303
+
304
+ <!-- Arrow: Validation → Explanation (Passed) -->
305
+ <line x1="535" y1="1680" x2="535" y2="1735" stroke="#2E7D32" stroke-width="1.5" marker-end="url(#ah-ok)"/>
306
+ <rect x="507" y="1695" width="58" height="16" rx="4" fill="#E8F5E9"/>
307
+ <text x="536" y="1707" text-anchor="middle" font-size="9" font-weight="600" fill="#2E7D32">Passed</text>
308
+
309
+ <!-- ============================================================ -->
310
+ <!-- 8. EXPLANATION LAYER -->
311
+ <!-- ============================================================ -->
312
+ <rect x="45" y="1730" width="1110" height="235" rx="12" fill="#FAFBFC" stroke="#90A4AE" stroke-width="1.5" stroke-dasharray="8,4"/>
313
+ <text x="600" y="1724" text-anchor="middle" font-size="12" font-weight="700" fill="#1A237E"
314
+ letter-spacing="1">EXPLANATION LAYER</text>
315
+
316
+ <!-- Explanation Orchestrator -->
317
+ <rect x="370" y="1750" width="320" height="47" rx="8" fill="#E0F2F1" stroke="#00695C" stroke-width="1.5"/>
318
+ <text x="530" y="1772" text-anchor="middle" font-size="13" font-weight="700" fill="#004D40">Explanation Orchestrator</text>
319
+ <text x="530" y="1788" text-anchor="middle" font-size="10" fill="#00695C">Async Parallel Execution</text>
320
+
321
+ <!-- Arrows: Orchestrator → 3 explanation agents -->
322
+ <line x1="420" y1="1797" x2="215" y2="1828" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
323
+ <line x1="530" y1="1797" x2="530" y2="1828" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
324
+ <line x1="640" y1="1797" x2="855" y2="1828" stroke="#546E7A" stroke-width="1.2" marker-end="url(#ah)"/>
325
+
326
+ <!-- Explanation Generator -->
327
+ <rect x="60" y="1830" width="310" height="82" rx="8" fill="#FFF8E1" stroke="#F9A825" stroke-width="1.5"/>
328
+ <text x="215" y="1854" text-anchor="middle" font-size="12" font-weight="700" fill="#E65100">Explanation Generator</text>
329
+ <text x="215" y="1872" text-anchor="middle" font-size="10" fill="#F57F17">Natural Language Description</text>
330
+ <text x="215" y="1888" text-anchor="middle" font-size="10" fill="#F57F17">Step-by-Step Decomposition</text>
331
+ <text x="215" y="1904" text-anchor="middle" font-size="10" fill="#F57F17">Human-Readable Summary</text>
332
+
333
+ <!-- Safety Assessor -->
334
+ <rect x="400" y="1830" width="310" height="82" rx="8" fill="#FFF8E1" stroke="#F9A825" stroke-width="1.5"/>
335
+ <text x="555" y="1854" text-anchor="middle" font-size="12" font-weight="700" fill="#E65100">Safety Assessor</text>
336
+ <text x="555" y="1872" text-anchor="middle" font-size="10" fill="#F57F17">4D Scoring Matrix</text>
337
+ <text x="555" y="1888" text-anchor="middle" font-size="10" fill="#F57F17">0–1 Scale per Dimension</text>
338
+ <text x="555" y="1904" text-anchor="middle" font-size="10" fill="#F57F17">Security · Syntax · Logic · Perf</text>
339
+
340
+ <!-- Optimization Advisor -->
341
+ <rect x="740" y="1830" width="310" height="82" rx="8" fill="#FFF8E1" stroke="#F9A825" stroke-width="1.5"/>
342
+ <text x="895" y="1854" text-anchor="middle" font-size="12" font-weight="700" fill="#E65100">Optimization Advisor</text>
343
+ <text x="895" y="1872" text-anchor="middle" font-size="10" fill="#F57F17">Performance Heuristics</text>
344
+ <text x="895" y="1888" text-anchor="middle" font-size="10" fill="#F57F17">Index Suggestions</text>
345
+ <text x="895" y="1904" text-anchor="middle" font-size="10" fill="#F57F17">Query Rewrite Hints</text>
346
+
347
+ <!-- ============================================================ -->
348
+ <!-- API CALL LABELS (dotted arrows to External Services) -->
349
+ <!-- ============================================================ -->
350
+ <line x1="215" y1="1912" x2="215" y2="1985" stroke="#78909C" stroke-width="1" stroke-dasharray="4,3" marker-end="url(#ah)"/>
351
+ <text x="215" y="1978" text-anchor="middle" font-size="8.5" fill="#78909C" font-style="italic">API Call</text>
352
+ <line x1="555" y1="1912" x2="555" y2="1985" stroke="#78909C" stroke-width="1" stroke-dasharray="4,3" marker-end="url(#ah)"/>
353
+ <text x="555" y="1978" text-anchor="middle" font-size="8.5" fill="#78909C" font-style="italic">API Call</text>
354
+ <line x1="895" y1="1912" x2="895" y2="1985" stroke="#78909C" stroke-width="1" stroke-dasharray="4,3" marker-end="url(#ah)"/>
355
+ <text x="895" y="1978" text-anchor="middle" font-size="8.5" fill="#78909C" font-style="italic">API Call</text>
356
+
357
+ <!-- ============================================================ -->
358
+ <!-- 9. EXTERNAL SERVICES & STRUCTURED OUTPUT -->
359
+ <!-- ============================================================ -->
360
+
361
+ <!-- External Services -->
362
+ <rect x="60" y="1990" width="310" height="70" rx="8" fill="#E1F5FE" stroke="#0277BD" stroke-width="1.5"/>
363
+ <text x="215" y="2014" text-anchor="middle" font-size="12" font-weight="700" fill="#01579B">External Services</text>
364
+ <text x="215" y="2032" text-anchor="middle" font-size="10" fill="#0277BD">LLM Provider · OpenRouter API</text>
365
+ <text x="215" y="2048" text-anchor="middle" font-size="10" fill="#0277BD">OpenAI Compatible Interface</text>
366
+
367
+ <!-- Arrow: External → Output -->
368
+ <line x1="370" y1="2025" x2="770" y2="2025" stroke="#546E7A" stroke-width="1.2" stroke-dasharray="6,3" marker-end="url(#ah)"/>
369
+
370
+ <!-- Structured Output -->
371
+ <rect x="790" y="1990" width="310" height="70" rx="10" fill="#E8F5E9" stroke="#2E7D32" stroke-width="2"/>
372
+ <text x="945" y="2014" text-anchor="middle" font-size="13" font-weight="700" fill="#1B5E20">Structured Output</text>
373
+ <text x="945" y="2032" text-anchor="middle" font-size="10" fill="#2E7D32">SQL · Explanation · Safety Report</text>
374
+ <text x="945" y="2048" text-anchor="middle" font-size="10" fill="#2E7D32">Optimization Hints · Candidate Scores</text>
375
+
376
+ <!-- ============================================================ -->
377
+ <!-- LEGEND -->
378
+ <!-- ============================================================ -->
379
+ <rect x="50" y="2095" width="1100" height="80" rx="10" fill="#FAFBFC" stroke="#CFD8DC" stroke-width="1"/>
380
+ <text x="600" y="2115" text-anchor="middle" font-size="11" font-weight="700" fill="#37474F">LEGEND</text>
381
+
382
+ <!-- Orchestrator -->
383
+ <rect x="80" y="2126" width="18" height="18" rx="4" fill="#E0F2F1" stroke="#00695C" stroke-width="1.2"/>
384
+ <text x="106" y="2140" font-size="10" fill="#37474F">Orchestrator</text>
385
+
386
+ <!-- Processing -->
387
+ <rect x="220" y="2126" width="18" height="18" rx="4" fill="#E8EAF6" stroke="#3949AB" stroke-width="1.2"/>
388
+ <text x="246" y="2140" font-size="10" fill="#37474F">Processing Node</text>
389
+
390
+ <!-- Agent / Signal -->
391
+ <rect x="380" y="2126" width="18" height="18" rx="4" fill="#FFF8E1" stroke="#F9A825" stroke-width="1.2"/>
392
+ <text x="406" y="2140" font-size="10" fill="#37474F">Agent / Signal</text>
393
+
394
+ <!-- Decision -->
395
+ <polygon points="545,2126 559,2135 545,2144 531,2135" fill="#FCE4EC" stroke="#AD1457" stroke-width="1.2"/>
396
+ <text x="570" y="2140" font-size="10" fill="#37474F">Decision / Fusion</text>
397
+
398
+ <!-- Data Store -->
399
+ <rect x="710" y="2126" width="18" height="18" rx="4" fill="#F3E5F5" stroke="#7B1FA2" stroke-width="1.2"/>
400
+ <text x="736" y="2140" font-size="10" fill="#37474F">Data Store</text>
401
+
402
+ <!-- I/O -->
403
+ <rect x="840" y="2126" width="18" height="18" rx="4" fill="#E1F5FE" stroke="#0277BD" stroke-width="1.2"/>
404
+ <text x="866" y="2140" font-size="10" fill="#37474F">Input / Output</text>
405
+
406
+ <!-- Retry -->
407
+ <line x1="965" y1="2135" x2="1000" y2="2135" stroke="#C62828" stroke-width="1.3" stroke-dasharray="5,3"/>
408
+ <text x="1010" y="2140" font-size="10" fill="#37474F">Retry / Error Path</text>
409
+
410
+ <!-- ============================================================ -->
411
+ <!-- FOOTER -->
412
+ <!-- ============================================================ -->
413
+ <text x="600" y="2210" text-anchor="middle" font-size="10" fill="#90A4AE">
414
+ NL2SQL Multi-Agent Architecture · Built with LangGraph + OpenRouter · 8 Specialized Agents · Async Pipeline</text>
415
+ <text x="600" y="2228" text-anchor="middle" font-size="9" fill="#B0BEC5">
416
+ © 2026 Toheed Asghar · github.com/toheedasghar</text>
417
+
418
+ <!-- ============================================================ -->
419
+ <!-- SIDE ANNOTATIONS (connecting to external API) -->
420
+ <!-- ============================================================ -->
421
+
422
+ <!-- Left annotation: API calls from Generation Layer -->
423
+ <text x="38" y="1200" font-size="9" fill="#78909C" font-style="italic"
424
+ transform="rotate(-90,38,1200)">API Call</text>
425
+ <line x1="45" y1="1184" x2="170" y2="1184" stroke="#78909C" stroke-width="1" stroke-dasharray="4,3"/>
426
+
427
+ <!-- Left annotation: API calls from Validation Layer -->
428
+ <text x="38" y="1530" font-size="9" fill="#78909C" font-style="italic"
429
+ transform="rotate(-90,38,1530)">API Call</text>
430
+ <line x1="45" y1="1526" x2="60" y2="1526" stroke="#78909C" stroke-width="1" stroke-dasharray="4,3"/>
431
+
432
+ </svg>