spl-llm 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 (36) hide show
  1. spl_llm-0.1.0/LICENSE +174 -0
  2. spl_llm-0.1.0/PKG-INFO +231 -0
  3. spl_llm-0.1.0/README.md +198 -0
  4. spl_llm-0.1.0/pyproject.toml +55 -0
  5. spl_llm-0.1.0/setup.cfg +4 -0
  6. spl_llm-0.1.0/spl/__init__.py +52 -0
  7. spl_llm-0.1.0/spl/adapters/__init__.py +36 -0
  8. spl_llm-0.1.0/spl/adapters/base.py +75 -0
  9. spl_llm-0.1.0/spl/adapters/claude_cli.py +94 -0
  10. spl_llm-0.1.0/spl/adapters/ollama.py +163 -0
  11. spl_llm-0.1.0/spl/adapters/openrouter.py +141 -0
  12. spl_llm-0.1.0/spl/analyzer.py +137 -0
  13. spl_llm-0.1.0/spl/ast_nodes.py +212 -0
  14. spl_llm-0.1.0/spl/cli.py +498 -0
  15. spl_llm-0.1.0/spl/executor.py +321 -0
  16. spl_llm-0.1.0/spl/explain.py +106 -0
  17. spl_llm-0.1.0/spl/functions.py +87 -0
  18. spl_llm-0.1.0/spl/lexer.py +218 -0
  19. spl_llm-0.1.0/spl/optimizer.py +243 -0
  20. spl_llm-0.1.0/spl/parser.py +725 -0
  21. spl_llm-0.1.0/spl/storage/__init__.py +34 -0
  22. spl_llm-0.1.0/spl/storage/chroma.py +151 -0
  23. spl_llm-0.1.0/spl/storage/memory.py +120 -0
  24. spl_llm-0.1.0/spl/storage/vector.py +192 -0
  25. spl_llm-0.1.0/spl/token_counter.py +89 -0
  26. spl_llm-0.1.0/spl/tokens.py +148 -0
  27. spl_llm-0.1.0/spl_llm.egg-info/PKG-INFO +231 -0
  28. spl_llm-0.1.0/spl_llm.egg-info/SOURCES.txt +34 -0
  29. spl_llm-0.1.0/spl_llm.egg-info/dependency_links.txt +1 -0
  30. spl_llm-0.1.0/spl_llm.egg-info/entry_points.txt +2 -0
  31. spl_llm-0.1.0/spl_llm.egg-info/requires.txt +13 -0
  32. spl_llm-0.1.0/spl_llm.egg-info/top_level.txt +1 -0
  33. spl_llm-0.1.0/tests/test_lexer.py +133 -0
  34. spl_llm-0.1.0/tests/test_optimizer.py +112 -0
  35. spl_llm-0.1.0/tests/test_parser.py +277 -0
  36. spl_llm-0.1.0/tests/test_storage.py +105 -0
spl_llm-0.1.0/LICENSE ADDED
@@ -0,0 +1,174 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship made available under
36
+ the License, as indicated by a copyright notice that is included in
37
+ or attached to the work (an example is provided in the Appendix below).
38
+
39
+ "Derivative Works" shall mean any work, whether in Source or Object
40
+ form, that is based on (or derived from) the Work and for which the
41
+ editorial revisions, annotations, elaborations, or other transformations
42
+ represent, as a whole, an original work of authorship. For the purposes
43
+ of this License, Derivative Works shall not include works that remain
44
+ separable from, or merely link (or bind by name) to the interfaces of,
45
+ the Work and Derivative Works thereof.
46
+
47
+ "Contribution" shall mean, as submitted to the Licensor for inclusion
48
+ in the Work by the copyright owner or by an individual or Legal Entity
49
+ authorized to submit on behalf of the copyright owner. For the purposes
50
+ of this definition, "submitted" means any form of electronic, verbal,
51
+ or written communication sent to the Licensor or its representatives,
52
+ including but not limited to communication on electronic mailing lists,
53
+ source code control systems, and issue tracking systems that are managed
54
+ by, or on behalf of, the Licensor for the purpose of recording and
55
+ discussing the Work, but excluding communication that is conspicuously
56
+ marked or designated in writing by the copyright owner as "Not a
57
+ Contribution."
58
+
59
+ "Contributor" shall mean Licensor and any Legal Entity on behalf of
60
+ whom a Contribution has been received by the Licensor and included
61
+ within the Work.
62
+
63
+ 2. Grant of Copyright License. Subject to the terms and conditions of
64
+ this License, each Contributor hereby grants to You a perpetual,
65
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
66
+ copyright license to reproduce, prepare Derivative Works of,
67
+ publicly display, publicly perform, sublicense, and distribute the
68
+ Work and such Derivative Works in Source or Object form.
69
+
70
+ 3. Grant of Patent License. Subject to the terms and conditions of
71
+ this License, each Contributor hereby grants to You a perpetual,
72
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
73
+ (except as stated in this section) patent license to make, have made,
74
+ use, offer to sell, sell, import, and otherwise transfer the Work,
75
+ where such license applies only to those patent claims licensable
76
+ by such Contributor that are necessarily infringed by their
77
+ Contribution(s) alone or by combination of their Contribution(s)
78
+ with the Work to which such Contribution(s) was submitted. If You
79
+ institute patent litigation against any entity (including a cross-claim
80
+ or counterclaim in a lawsuit) alleging that the Work or any
81
+ Contribution embodied within the Work constitutes direct or
82
+ contributory patent infringement, then any patent licenses granted to
83
+ You under this License for that Work shall terminate as of the date
84
+ such litigation is filed.
85
+
86
+ 4. Redistribution. You may reproduce and distribute copies of the
87
+ Work or Derivative Works thereof in any medium, with or without
88
+ modifications, and in Source or Object form, provided that You
89
+ meet the following conditions:
90
+
91
+ (a) You must give any other recipients of the Work or Derivative
92
+ Works a copy of this License; and
93
+
94
+ (b) You must cause any modified files to carry prominent notices
95
+ stating that You changed the files; and
96
+
97
+ (c) You must retain, in the Source form of any Derivative Works
98
+ that You distribute, all copyright, patent, trademark, and
99
+ attribution notices from the Source form of the Work,
100
+ excluding those notices that do not pertain to any part of
101
+ the Derivative Works; and
102
+
103
+ (d) If the Work includes a "NOTICE" file as part of its distribution,
104
+ You must include a readable copy of the attribution notices
105
+ contained within such NOTICE file, in all copies or Derivative
106
+ Works that You distribute, alongside or as an addendum to the
107
+ NOTICE text from the Work, provided that such additional attribution
108
+ notices cannot be construed as modifying the License.
109
+
110
+ You may add Your own attribution statements alongside the
111
+ distribution, and You may provide additional grant of rights, pursuant
112
+ to the terms of the Apache License Version 2.0.
113
+
114
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
115
+ any Contribution intentionally submitted for inclusion in the Work
116
+ by You to the Licensor shall be under the terms and conditions of
117
+ this License, without any additional terms or conditions.
118
+ Notwithstanding the above, nothing herein shall supersede or modify
119
+ the terms of any separate license agreement you may have executed
120
+ with Licensor regarding such Contributions.
121
+
122
+ 6. Trademarks. This License does not grant permission to use the trade
123
+ names, trademarks, service marks, or product names of the Licensor,
124
+ except as required for reasonable and customary use in describing the
125
+ origin of the Work and reproducing the content of the NOTICE file.
126
+
127
+ 7. Disclaimer of Warranty. Unless required by applicable law or
128
+ agreed to in writing, Licensor provides the Work (and each
129
+ Contributor provides its Contributions) on an "AS IS" BASIS,
130
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
131
+ implied, including, without limitation, any warranties or conditions
132
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
133
+ PARTICULAR PURPOSE. You are solely responsible for determining the
134
+ appropriateness of using or reproducing the Work and assume any
135
+ risks associated with Your exercise of permissions under this License.
136
+
137
+ 8. Limitation of Liability. In no event and under no legal theory,
138
+ whether in tort (including negligence), contract, or otherwise,
139
+ unless required by applicable law (such as deliberate and grossly
140
+ negligent acts) or agreed to in writing, shall any Contributor be
141
+ liable to You for damages, including any direct, indirect, special,
142
+ incidental, or exemplary damages of any character arising as a
143
+ result of this License or out of the use or inability to use the
144
+ Work (including but not limited to damages for loss of goodwill,
145
+ work stoppage, computer failure or malfunction, or all other
146
+ commercial damages or losses), even if such Contributor has been
147
+ advised of the possibility of such damages.
148
+
149
+ 9. Accepting Warranty or Liability. While redistributing the Work or
150
+ Derivative Works thereof, You may choose to offer, and charge a fee
151
+ for, acceptance of support, warranty, indemnity, or other liability
152
+ obligations and/or rights consistent with this License. However, in
153
+ accepting such obligations, You may offer such obligations only on
154
+ Your own behalf and on Your sole responsibility, not on behalf of
155
+ any other Contributor, and only if You agree to indemnify, defend,
156
+ and hold each Contributor harmless for any liability incurred by,
157
+ or claims asserted against, such Contributor by reason of your
158
+ accepting any such warranty or additional liability.
159
+
160
+ END OF TERMS AND CONDITIONS
161
+
162
+ Copyright 2026 Wen Gong
163
+
164
+ Licensed under the Apache License, Version 2.0 (the "License");
165
+ you may not use this file except in compliance with the License.
166
+ You may obtain a copy of the License at
167
+
168
+ http://www.apache.org/licenses/LICENSE-2.0
169
+
170
+ Unless required by applicable law or agreed to in writing, software
171
+ distributed under the License is distributed on an "AS IS" BASIS,
172
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
173
+ See the License for the specific language governing permissions and
174
+ limitations under the License.
spl_llm-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,231 @@
1
+ Metadata-Version: 2.4
2
+ Name: spl-llm
3
+ Version: 0.1.0
4
+ Summary: Structured Prompt Language - SQL for LLM Context Management
5
+ Author-email: Wen Gong <wen.gong.research@gmail.com>
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/digital-duck/SPL
8
+ Project-URL: Repository, https://github.com/digital-duck/SPL
9
+ Keywords: llm,prompt-engineering,sql,declarative,context-management
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
17
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: faiss-cpu>=1.7.4
22
+ Requires-Dist: numpy>=1.24
23
+ Requires-Dist: httpx>=0.25
24
+ Requires-Dist: tiktoken>=0.5
25
+ Requires-Dist: pyyaml>=6.0
26
+ Requires-Dist: dd-logging>=0.1.0
27
+ Provides-Extra: dev
28
+ Requires-Dist: pytest>=7.0; extra == "dev"
29
+ Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
30
+ Provides-Extra: chroma
31
+ Requires-Dist: chromadb>=0.4; extra == "chroma"
32
+ Dynamic: license-file
33
+
34
+ # SPL - Structured Prompt Language
35
+
36
+ **SQL for LLM Context Management**
37
+
38
+ SPL is a declarative, SQL-inspired language that treats LLMs as **generative knowledge bases**. Just as SQL (1970) standardized database access, SPL standardizes LLM prompt engineering with automatic token budget optimization, built-in RAG, and persistent memory.
39
+
40
+ ```sql
41
+ PROMPT answer_question
42
+ WITH BUDGET 8000 tokens
43
+ USING MODEL claude-sonnet-4-5
44
+
45
+ SELECT
46
+ system_role("You are a knowledgeable assistant"),
47
+ context.question AS question LIMIT 200 tokens,
48
+ rag.query("relevant docs", top_k=5) AS docs LIMIT 3000 tokens,
49
+ memory.get("history") AS history LIMIT 500 tokens
50
+
51
+ GENERATE
52
+ detailed_answer(question, docs, history)
53
+ WITH OUTPUT BUDGET 2000 tokens, TEMPERATURE 0.3;
54
+ ```
55
+
56
+ ## Why SPL?
57
+
58
+ | Before (Imperative) | After (SPL) |
59
+ |-----|-----|
60
+ | Manual token counting | `WITH BUDGET 8000 tokens` |
61
+ | Trial-and-error truncation | `LIMIT 500 tokens` (auto-compressed) |
62
+ | No visibility into allocation | `EXPLAIN PROMPT` shows full plan |
63
+ | Copy-paste prompt templates | CTEs, functions, composition |
64
+ | Tied to one LLM provider | Provider-agnostic (Ollama, OpenRouter, Claude CLI) |
65
+
66
+ ## Install
67
+
68
+ ```bash
69
+ # Core install
70
+ pip install spl-llm
71
+
72
+ # With ChromaDB vector store support
73
+ pip install "spl-llm[chroma]"
74
+ ```
75
+
76
+ ### Zero-cost quick start with Ollama
77
+
78
+ Run SPL queries entirely locally — no API key, no cost:
79
+
80
+ ```bash
81
+ # 1. Install Ollama: https://ollama.ai/download
82
+ # 2. Pull a model
83
+ ollama pull llama3.2 # 2 GB, great for most tasks
84
+ ollama pull qwen2.5 # strong reasoning and code
85
+
86
+ # 3. Install SPL and run
87
+ pip install spl-llm
88
+ spl init # creates .spl/config.yaml — set adapter: ollama
89
+ spl execute examples/hello_world.spl
90
+ ```
91
+
92
+ ## Quick Start
93
+
94
+ ```bash
95
+ # Initialize workspace
96
+ spl init
97
+
98
+ # Validate syntax
99
+ spl validate examples/hello_world.spl
100
+
101
+ # Show execution plan (like SQL EXPLAIN)
102
+ spl explain examples/hello_world.spl
103
+
104
+ # Execute query
105
+ spl execute examples/hello_world.spl --param question="What is Python?"
106
+
107
+ # Built-in RAG (FAISS by default, or use --backend chroma)
108
+ spl rag add my_docs.txt
109
+ spl rag add my_docs.txt --backend chroma
110
+ spl rag query "search text" --top-k 5
111
+
112
+ # Persistent memory
113
+ spl memory set user_pref "prefers Python"
114
+ spl memory get user_pref
115
+ spl memory list
116
+ ```
117
+
118
+ ## EXPLAIN Output
119
+
120
+ ```
121
+ Execution Plan for: answer_question
122
+ ============================================================
123
+ Budget: 8,000 tokens | Model: claude-sonnet-4-5
124
+
125
+ Token Allocation:
126
+ +-- __system_role__ 20 tokens ( 0.2%)
127
+ +-- history 500 tokens ( 6.2%) [from memory]
128
+ +-- docs 3,000 tokens ( 37.5%) [cache MISS]
129
+ +-- question 200 tokens ( 2.5%)
130
+ +-- Output Budget 2,000 tokens ( 25.0%)
131
+ \-- Buffer 2,280 tokens ( 28.5%)
132
+ ----------
133
+ Total 5,720 / 8,000 tokens (71.5%)
134
+
135
+ Estimated Cost: $0.0412
136
+ ```
137
+
138
+ ## Architecture
139
+
140
+ ```
141
+ SPL Source (.spl)
142
+ |
143
+ [Lexer] -> [Parser] -> [Analyzer] -> [Optimizer] -> [Executor]
144
+ / | \
145
+ [LLM] [SQLite] [FAISS or ChromaDB]
146
+ | |
147
+ Ollama (local) Memory
148
+ OpenRouter RAG
149
+ Claude CLI
150
+ ```
151
+
152
+ **Key design decisions:**
153
+ - **Parser**: Hand-written recursive descent (zero external parser deps)
154
+ - **LLM**: Ollama (local, free) + OpenRouter.ai (production, 100+ models) + Claude CLI (dev)
155
+ - **Memory**: SQLite (file-based, portable, zero-config)
156
+ - **Vector Store**: FAISS (default) or ChromaDB (`--backend chroma`)
157
+ - **Storage**: `.spl/` directory per project
158
+
159
+ ## Python API
160
+
161
+ ```python
162
+ import spl
163
+
164
+ # Parse
165
+ ast = spl.parse(open("query.spl").read())
166
+
167
+ # Validate
168
+ result = spl.validate(open("query.spl").read())
169
+
170
+ # Explain
171
+ print(spl.explain(open("query.spl").read()))
172
+
173
+ # Execute
174
+ import asyncio
175
+ result = asyncio.run(spl.execute(
176
+ open("query.spl").read(),
177
+ params={"question": "What is Python?"}
178
+ ))
179
+ print(result.content)
180
+ ```
181
+
182
+ ## SPL Syntax
183
+
184
+ See [docs/dev/design-v1.md](docs/dev/design-v1.md) for full syntax specification and [docs/grammar.ebnf](docs/grammar.ebnf) for formal grammar.
185
+
186
+ ## Benchmark Results
187
+
188
+ SPL was evaluated across 5 experiments (all runnable without API keys):
189
+
190
+ | Metric | Result |
191
+ |--------|--------|
192
+ | Code reduction vs imperative Python | **65% average** (15 vs 44 lines of code) |
193
+ | Manual token-counting ops eliminated | **35 ops across 5 tasks** (SPL: 0) |
194
+ | Cross-model cost visibility | **68x cost difference** visible before execution |
195
+ | Feature claims verified | **20/20** automated checks pass |
196
+ | Parser test suite | **58/58** tests pass (incl. FAISS + ChromaDB storage) |
197
+
198
+ ```bash
199
+ # Run benchmarks yourself
200
+ python -m tests.benchmarks.bench_developer_experience
201
+ python -m tests.benchmarks.bench_token_optimization
202
+ python -m tests.benchmarks.bench_cost_estimation
203
+ python -m tests.benchmarks.bench_explain_showcase
204
+ python -m tests.benchmarks.bench_feature_verification
205
+ ```
206
+
207
+ ## Session 1 Summary (Feb 12, 2026)
208
+
209
+ The entire SPL engine --- from idea to working prototype with arxiv paper --- was built in a single Human+AI co-creation session:
210
+
211
+ **What was built:**
212
+ - Complete language specification (EBNF grammar, 30+ keywords, 50+ token types)
213
+ - Full engine pipeline: Lexer, Parser (hand-written recursive descent), Semantic Analyzer, Token Budget Optimizer, Executor
214
+ - Three LLM adapters: Ollama (local, free) + OpenRouter.ai (100+ models) + Claude Code CLI (subscription billing)
215
+ - Storage layer: SQLite persistent memory + FAISS vector store + ChromaDB (native RAG)
216
+ - CLI tool with 10 commands (`spl init/validate/explain/execute/memory/rag`)
217
+ - 4 example `.spl` programs covering basic QA, RAG, CTEs, and functions
218
+ - 40 unit tests + 5 benchmark experiments + 4 paper figures
219
+ - arxiv paper draft (~12 pages) with formal grammar, evaluation data, and competitive analysis
220
+ - pip-installable package (`spl-llm v0.1.0`)
221
+
222
+ **The core insight:** The LLM context window is a constrained resource --- just like disk I/O was for databases. Constrained resources deserve declarative query languages with optimizers. This is Codd's 1970 insight applied to 2026's problem.
223
+
224
+ ## Project
225
+
226
+ - **Author**: Wen Gong (20+ years Oracle/SQL experience)
227
+ - **Vision**: [SPL Design Thinking](docs/dev/design-v1.md)
228
+ - **Paper**: [arxiv draft](docs/paper/spl-paper.tex) | [figures](docs/paper/figures/) | [benchmark data](docs/paper/data/)
229
+ - **Co-creation**: Built via Human+AI collaboration ([log](docs/dev/co-creation-log.md))
230
+ - **History**: [Why SPL required interdisciplinary thinking](docs/history-lessons.md)
231
+ - **License**: Apache 2.0
@@ -0,0 +1,198 @@
1
+ # SPL - Structured Prompt Language
2
+
3
+ **SQL for LLM Context Management**
4
+
5
+ SPL is a declarative, SQL-inspired language that treats LLMs as **generative knowledge bases**. Just as SQL (1970) standardized database access, SPL standardizes LLM prompt engineering with automatic token budget optimization, built-in RAG, and persistent memory.
6
+
7
+ ```sql
8
+ PROMPT answer_question
9
+ WITH BUDGET 8000 tokens
10
+ USING MODEL claude-sonnet-4-5
11
+
12
+ SELECT
13
+ system_role("You are a knowledgeable assistant"),
14
+ context.question AS question LIMIT 200 tokens,
15
+ rag.query("relevant docs", top_k=5) AS docs LIMIT 3000 tokens,
16
+ memory.get("history") AS history LIMIT 500 tokens
17
+
18
+ GENERATE
19
+ detailed_answer(question, docs, history)
20
+ WITH OUTPUT BUDGET 2000 tokens, TEMPERATURE 0.3;
21
+ ```
22
+
23
+ ## Why SPL?
24
+
25
+ | Before (Imperative) | After (SPL) |
26
+ |-----|-----|
27
+ | Manual token counting | `WITH BUDGET 8000 tokens` |
28
+ | Trial-and-error truncation | `LIMIT 500 tokens` (auto-compressed) |
29
+ | No visibility into allocation | `EXPLAIN PROMPT` shows full plan |
30
+ | Copy-paste prompt templates | CTEs, functions, composition |
31
+ | Tied to one LLM provider | Provider-agnostic (Ollama, OpenRouter, Claude CLI) |
32
+
33
+ ## Install
34
+
35
+ ```bash
36
+ # Core install
37
+ pip install spl-llm
38
+
39
+ # With ChromaDB vector store support
40
+ pip install "spl-llm[chroma]"
41
+ ```
42
+
43
+ ### Zero-cost quick start with Ollama
44
+
45
+ Run SPL queries entirely locally — no API key, no cost:
46
+
47
+ ```bash
48
+ # 1. Install Ollama: https://ollama.ai/download
49
+ # 2. Pull a model
50
+ ollama pull llama3.2 # 2 GB, great for most tasks
51
+ ollama pull qwen2.5 # strong reasoning and code
52
+
53
+ # 3. Install SPL and run
54
+ pip install spl-llm
55
+ spl init # creates .spl/config.yaml — set adapter: ollama
56
+ spl execute examples/hello_world.spl
57
+ ```
58
+
59
+ ## Quick Start
60
+
61
+ ```bash
62
+ # Initialize workspace
63
+ spl init
64
+
65
+ # Validate syntax
66
+ spl validate examples/hello_world.spl
67
+
68
+ # Show execution plan (like SQL EXPLAIN)
69
+ spl explain examples/hello_world.spl
70
+
71
+ # Execute query
72
+ spl execute examples/hello_world.spl --param question="What is Python?"
73
+
74
+ # Built-in RAG (FAISS by default, or use --backend chroma)
75
+ spl rag add my_docs.txt
76
+ spl rag add my_docs.txt --backend chroma
77
+ spl rag query "search text" --top-k 5
78
+
79
+ # Persistent memory
80
+ spl memory set user_pref "prefers Python"
81
+ spl memory get user_pref
82
+ spl memory list
83
+ ```
84
+
85
+ ## EXPLAIN Output
86
+
87
+ ```
88
+ Execution Plan for: answer_question
89
+ ============================================================
90
+ Budget: 8,000 tokens | Model: claude-sonnet-4-5
91
+
92
+ Token Allocation:
93
+ +-- __system_role__ 20 tokens ( 0.2%)
94
+ +-- history 500 tokens ( 6.2%) [from memory]
95
+ +-- docs 3,000 tokens ( 37.5%) [cache MISS]
96
+ +-- question 200 tokens ( 2.5%)
97
+ +-- Output Budget 2,000 tokens ( 25.0%)
98
+ \-- Buffer 2,280 tokens ( 28.5%)
99
+ ----------
100
+ Total 5,720 / 8,000 tokens (71.5%)
101
+
102
+ Estimated Cost: $0.0412
103
+ ```
104
+
105
+ ## Architecture
106
+
107
+ ```
108
+ SPL Source (.spl)
109
+ |
110
+ [Lexer] -> [Parser] -> [Analyzer] -> [Optimizer] -> [Executor]
111
+ / | \
112
+ [LLM] [SQLite] [FAISS or ChromaDB]
113
+ | |
114
+ Ollama (local) Memory
115
+ OpenRouter RAG
116
+ Claude CLI
117
+ ```
118
+
119
+ **Key design decisions:**
120
+ - **Parser**: Hand-written recursive descent (zero external parser deps)
121
+ - **LLM**: Ollama (local, free) + OpenRouter.ai (production, 100+ models) + Claude CLI (dev)
122
+ - **Memory**: SQLite (file-based, portable, zero-config)
123
+ - **Vector Store**: FAISS (default) or ChromaDB (`--backend chroma`)
124
+ - **Storage**: `.spl/` directory per project
125
+
126
+ ## Python API
127
+
128
+ ```python
129
+ import spl
130
+
131
+ # Parse
132
+ ast = spl.parse(open("query.spl").read())
133
+
134
+ # Validate
135
+ result = spl.validate(open("query.spl").read())
136
+
137
+ # Explain
138
+ print(spl.explain(open("query.spl").read()))
139
+
140
+ # Execute
141
+ import asyncio
142
+ result = asyncio.run(spl.execute(
143
+ open("query.spl").read(),
144
+ params={"question": "What is Python?"}
145
+ ))
146
+ print(result.content)
147
+ ```
148
+
149
+ ## SPL Syntax
150
+
151
+ See [docs/dev/design-v1.md](docs/dev/design-v1.md) for full syntax specification and [docs/grammar.ebnf](docs/grammar.ebnf) for formal grammar.
152
+
153
+ ## Benchmark Results
154
+
155
+ SPL was evaluated across 5 experiments (all runnable without API keys):
156
+
157
+ | Metric | Result |
158
+ |--------|--------|
159
+ | Code reduction vs imperative Python | **65% average** (15 vs 44 lines of code) |
160
+ | Manual token-counting ops eliminated | **35 ops across 5 tasks** (SPL: 0) |
161
+ | Cross-model cost visibility | **68x cost difference** visible before execution |
162
+ | Feature claims verified | **20/20** automated checks pass |
163
+ | Parser test suite | **58/58** tests pass (incl. FAISS + ChromaDB storage) |
164
+
165
+ ```bash
166
+ # Run benchmarks yourself
167
+ python -m tests.benchmarks.bench_developer_experience
168
+ python -m tests.benchmarks.bench_token_optimization
169
+ python -m tests.benchmarks.bench_cost_estimation
170
+ python -m tests.benchmarks.bench_explain_showcase
171
+ python -m tests.benchmarks.bench_feature_verification
172
+ ```
173
+
174
+ ## Session 1 Summary (Feb 12, 2026)
175
+
176
+ The entire SPL engine --- from idea to working prototype with arxiv paper --- was built in a single Human+AI co-creation session:
177
+
178
+ **What was built:**
179
+ - Complete language specification (EBNF grammar, 30+ keywords, 50+ token types)
180
+ - Full engine pipeline: Lexer, Parser (hand-written recursive descent), Semantic Analyzer, Token Budget Optimizer, Executor
181
+ - Three LLM adapters: Ollama (local, free) + OpenRouter.ai (100+ models) + Claude Code CLI (subscription billing)
182
+ - Storage layer: SQLite persistent memory + FAISS vector store + ChromaDB (native RAG)
183
+ - CLI tool with 10 commands (`spl init/validate/explain/execute/memory/rag`)
184
+ - 4 example `.spl` programs covering basic QA, RAG, CTEs, and functions
185
+ - 40 unit tests + 5 benchmark experiments + 4 paper figures
186
+ - arxiv paper draft (~12 pages) with formal grammar, evaluation data, and competitive analysis
187
+ - pip-installable package (`spl-llm v0.1.0`)
188
+
189
+ **The core insight:** The LLM context window is a constrained resource --- just like disk I/O was for databases. Constrained resources deserve declarative query languages with optimizers. This is Codd's 1970 insight applied to 2026's problem.
190
+
191
+ ## Project
192
+
193
+ - **Author**: Wen Gong (20+ years Oracle/SQL experience)
194
+ - **Vision**: [SPL Design Thinking](docs/dev/design-v1.md)
195
+ - **Paper**: [arxiv draft](docs/paper/spl-paper.tex) | [figures](docs/paper/figures/) | [benchmark data](docs/paper/data/)
196
+ - **Co-creation**: Built via Human+AI collaboration ([log](docs/dev/co-creation-log.md))
197
+ - **History**: [Why SPL required interdisciplinary thinking](docs/history-lessons.md)
198
+ - **License**: Apache 2.0
@@ -0,0 +1,55 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "spl-llm"
7
+ version = "0.1.0"
8
+ description = "Structured Prompt Language - SQL for LLM Context Management"
9
+ readme = "README.md"
10
+ license = "Apache-2.0"
11
+ requires-python = ">=3.10"
12
+ authors = [
13
+ {name = "Wen Gong", email = "wen.gong.research@gmail.com"},
14
+ ]
15
+ keywords = ["llm", "prompt-engineering", "sql", "declarative", "context-management"]
16
+ classifiers = [
17
+ "Development Status :: 3 - Alpha",
18
+ "Intended Audience :: Developers",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.10",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Topic :: Software Development :: Libraries :: Python Modules",
24
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
25
+ ]
26
+ dependencies = [
27
+ "faiss-cpu>=1.7.4",
28
+ "numpy>=1.24",
29
+ "httpx>=0.25",
30
+ "tiktoken>=0.5",
31
+ "pyyaml>=6.0",
32
+ "dd-logging>=0.1.0",
33
+ ]
34
+
35
+ [project.optional-dependencies]
36
+ dev = [
37
+ "pytest>=7.0",
38
+ "pytest-asyncio>=0.21",
39
+ ]
40
+ chroma = [
41
+ "chromadb>=0.4",
42
+ ]
43
+
44
+ [project.scripts]
45
+ spl = "spl.cli:main"
46
+
47
+ [project.urls]
48
+ Homepage = "https://github.com/digital-duck/SPL"
49
+ Repository = "https://github.com/digital-duck/SPL"
50
+
51
+ [tool.setuptools.packages.find]
52
+ include = ["spl*"]
53
+
54
+ [tool.pytest.ini_options]
55
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+