siof 1.0.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.
- siof-1.0.0/LICENSE +21 -0
- siof-1.0.0/PKG-INFO +316 -0
- siof-1.0.0/README.md +282 -0
- siof-1.0.0/pyproject.toml +73 -0
- siof-1.0.0/setup.cfg +4 -0
- siof-1.0.0/src/siof/__init__.py +7 -0
- siof-1.0.0/src/siof/__main__.py +3 -0
- siof-1.0.0/src/siof/cli.py +182 -0
- siof-1.0.0/src/siof/deslopper.py +306 -0
- siof-1.0.0/src/siof/green_guard.py +219 -0
- siof-1.0.0/src/siof/indexer.py +1221 -0
- siof-1.0.0/src/siof/mcp_server.py +455 -0
- siof-1.0.0/src/siof/memex.py +292 -0
- siof-1.0.0/src/siof/models.py +65 -0
- siof-1.0.0/src/siof/orchestrator.py +192 -0
- siof-1.0.0/src/siof/policy.py +131 -0
- siof-1.0.0/src/siof/repository.py +318 -0
- siof-1.0.0/src/siof/sarif_reporter.py +289 -0
- siof-1.0.0/src/siof/storage.py +227 -0
- siof-1.0.0/src/siof/verifier.py +307 -0
- siof-1.0.0/src/siof.egg-info/PKG-INFO +316 -0
- siof-1.0.0/src/siof.egg-info/SOURCES.txt +46 -0
- siof-1.0.0/src/siof.egg-info/dependency_links.txt +1 -0
- siof-1.0.0/src/siof.egg-info/entry_points.txt +2 -0
- siof-1.0.0/src/siof.egg-info/requires.txt +13 -0
- siof-1.0.0/src/siof.egg-info/top_level.txt +1 -0
- siof-1.0.0/tests/test_cli.py +173 -0
- siof-1.0.0/tests/test_deslopper.py +34 -0
- siof-1.0.0/tests/test_deslopper_comprehensive.py +228 -0
- siof-1.0.0/tests/test_dtg_builder_benchmark.py +252 -0
- siof-1.0.0/tests/test_e2e.py +144 -0
- siof-1.0.0/tests/test_green.py +11 -0
- siof-1.0.0/tests/test_green_comprehensive.py +149 -0
- siof-1.0.0/tests/test_indexer.py +366 -0
- siof-1.0.0/tests/test_indexer_benchmark.py +166 -0
- siof-1.0.0/tests/test_indexer_comprehensive.py +255 -0
- siof-1.0.0/tests/test_mcp.py +25 -0
- siof-1.0.0/tests/test_mcp_comprehensive.py +267 -0
- siof-1.0.0/tests/test_mcp_phase3.py +559 -0
- siof-1.0.0/tests/test_memex.py +19 -0
- siof-1.0.0/tests/test_memex_comprehensive.py +190 -0
- siof-1.0.0/tests/test_phase4_memex.py +313 -0
- siof-1.0.0/tests/test_phase5_green_guard.py +255 -0
- siof-1.0.0/tests/test_phase6_7_integration.py +451 -0
- siof-1.0.0/tests/test_repository.py +420 -0
- siof-1.0.0/tests/test_sarif_reporter.py +284 -0
- siof-1.0.0/tests/test_symbol_extraction_benchmark.py +291 -0
- siof-1.0.0/tests/test_verifier.py +418 -0
siof-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Keerthivasan S V
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
siof-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: siof
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Semantic Integrity and Orchestration Framework - AI-native Python toolkit for maintaining codebase integrity
|
|
5
|
+
Author-email: Keerthivasan S V <keerthivasansv2006@outlook.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Keerthivasan-Venkitajalam/SIOF
|
|
8
|
+
Project-URL: Documentation, https://github.com/Keerthivasan-Venkitajalam/SIOF#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/Keerthivasan-Venkitajalam/SIOF
|
|
10
|
+
Project-URL: Bug Tracker, https://github.com/Keerthivasan-Venkitajalam/SIOF/issues
|
|
11
|
+
Keywords: ai,code-analysis,graph,mcp,sustainability,semantic-integrity,autonomous-coding
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Topic :: Software Development :: Code Generators
|
|
15
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Provides-Extra: green
|
|
24
|
+
Requires-Dist: psutil>=5.9; extra == "green"
|
|
25
|
+
Provides-Extra: test
|
|
26
|
+
Requires-Dist: pytest>=8.0; extra == "test"
|
|
27
|
+
Requires-Dist: pytest-cov>=4.0; extra == "test"
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
30
|
+
Requires-Dist: black>=23.0; extra == "dev"
|
|
31
|
+
Requires-Dist: mypy>=1.0; extra == "dev"
|
|
32
|
+
Requires-Dist: types-psutil>=5.9; extra == "dev"
|
|
33
|
+
Dynamic: license-file
|
|
34
|
+
|
|
35
|
+
<h1 align="center"><img src="https://github.com/Keerthivasan-Venkitajalam/SIOF/blob/main/branding/sioflogo.png" width="300"></h1><br>
|
|
36
|
+
|
|
37
|
+
[](https://pypi.org/project/siof/)
|
|
38
|
+
[](https://pypi.org/project/siof/)
|
|
39
|
+
[](https://opensource.org/licenses/MIT)
|
|
40
|
+
[](https://github.com/Keerthivasan-Venkitajalam/SIOF)
|
|
41
|
+
[](https://github.com/psf/black)
|
|
42
|
+
[](https://github.com/Keerthivasan-Venkitajalam/SIOF)
|
|
43
|
+
|
|
44
|
+
SIOF (Semantic Integrity and Orchestration Framework) is the fundamental toolkit for AI-native Python development.
|
|
45
|
+
|
|
46
|
+
- **Source code:** https://github.com/Keerthivasan-Venkitajalam/SIOF
|
|
47
|
+
- **Bug reports:** https://github.com/Keerthivasan-Venkitajalam/SIOF/issues
|
|
48
|
+
- **PyPI:** https://pypi.org/project/siof/
|
|
49
|
+
|
|
50
|
+
It provides:
|
|
51
|
+
|
|
52
|
+
- **Data Transformation Graph (DTG) indexing** - Map your codebase as data lineage, not control flow
|
|
53
|
+
- **AI slop detection** - Deterministic pattern matching for machine-generated anti-patterns
|
|
54
|
+
- **MCP graph server** - Expose your codebase to LLM agents via Model Context Protocol
|
|
55
|
+
- **Developer intent extraction (Memex)** - Preserve architectural reasoning across AI-generated mutations
|
|
56
|
+
- **Sustainability tracking (Green Guard)** - Monitor energy consumption and enforce carbon thresholds
|
|
57
|
+
|
|
58
|
+
## Installation
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pip install siof
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Quick Start
|
|
65
|
+
|
|
66
|
+
### Index Your Repository
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
siof index build --repo /path/to/repo
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Detect AI-Generated Anti-Patterns
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
siof slop audit --repo /path/to/repo
|
|
76
|
+
siof slop fix --repo /path/to/repo
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Start MCP Server for AI Agents
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
siof mcp serve --db siof.db
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Python API
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from siof.orchestrator import SIOFOrchestrator
|
|
89
|
+
|
|
90
|
+
# Run complete pipeline
|
|
91
|
+
orch = SIOFOrchestrator(repo=".", db_path="siof.db")
|
|
92
|
+
result = orch.run_full_pipeline(
|
|
93
|
+
index_mode="build",
|
|
94
|
+
slop_mode="audit",
|
|
95
|
+
enable_memex=True,
|
|
96
|
+
enable_green_guard=True,
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
print(f"Success: {result.success}")
|
|
100
|
+
print(f"Duration: {result.total_duration_s:.2f}s")
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Core Features
|
|
104
|
+
|
|
105
|
+
### 1. DTG Indexer
|
|
106
|
+
|
|
107
|
+
Parses Python repositories into Data Transformation Graphs, mapping data lineage instead of control flow:
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
from siof.indexer import PythonIndexer
|
|
111
|
+
|
|
112
|
+
indexer = PythonIndexer(repo=".", db_path="siof.db")
|
|
113
|
+
indexer.init()
|
|
114
|
+
result = indexer.build()
|
|
115
|
+
print(f"Indexed {result['nodes']} nodes and {result['edges']} edges")
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### 2. De-Slopper Engine
|
|
119
|
+
|
|
120
|
+
Detects and fixes AI-generated code anti-patterns:
|
|
121
|
+
|
|
122
|
+
- **NakedExceptionPass** - Bare `except: pass` blocks that swallow errors
|
|
123
|
+
- **BroadExceptionPass** - Overly broad exception handlers
|
|
124
|
+
- **HedgeComment** - LLM-generated hedge words ("robust", "comprehensive")
|
|
125
|
+
- **EchoComment** - Comments that merely restate code mechanics
|
|
126
|
+
- **SuspiciousImport** - Hallucinated dependencies
|
|
127
|
+
- **UnusedImport** - Dead imports
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
from siof.deslopper import DeSlopper
|
|
131
|
+
|
|
132
|
+
deslopper = DeSlopper(repo=".", db_path="siof.db")
|
|
133
|
+
result = deslopper.run(mode="fix") # audit, fix, or strict
|
|
134
|
+
print(f"Found {len(result.findings)} issues")
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### 3. MCP Graph Server
|
|
138
|
+
|
|
139
|
+
Exposes your DTG to LLM agents via Model Context Protocol:
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
from siof.mcp_server import MCPGraphServer
|
|
143
|
+
|
|
144
|
+
server = MCPGraphServer("siof.db")
|
|
145
|
+
# Provides tools: find_data_lineage, impact_of_change, get_dead_paths, etc.
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Features:
|
|
149
|
+
- **RBAC** with role hierarchy (viewer/analyst/admin/service)
|
|
150
|
+
- **Rate limiting** per role and organization
|
|
151
|
+
- **Distributed tracing** with trace IDs
|
|
152
|
+
- **Schema validation** for all tool inputs
|
|
153
|
+
|
|
154
|
+
### 4. Memex Intent Layer
|
|
155
|
+
|
|
156
|
+
Extracts and preserves developer intent from commits, PRs, and prompts:
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
from siof.memex import Memex
|
|
160
|
+
|
|
161
|
+
memex = Memex(repo=".", db_path="siof.db")
|
|
162
|
+
result = memex.ingest() # Extracts from git commits, PRs, prompts
|
|
163
|
+
print(f"Ingested {result['ingested']} intent records")
|
|
164
|
+
|
|
165
|
+
# Query intent
|
|
166
|
+
records = memex.query_intent(symbol="authenticate")
|
|
167
|
+
scores = memex.score_relevance("authenticate", records)
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### 5. Green Guard
|
|
171
|
+
|
|
172
|
+
Tracks energy consumption and enforces sustainability thresholds:
|
|
173
|
+
|
|
174
|
+
```python
|
|
175
|
+
from siof.green_guard import GreenGuard
|
|
176
|
+
|
|
177
|
+
guard = GreenGuard("siof.db")
|
|
178
|
+
result = guard.run_command("pytest", hard_co2_kg=0.1)
|
|
179
|
+
print(f"Energy: {result.energy_wh:.4f} Wh, CO2: {result.co2_kg:.6f} kg")
|
|
180
|
+
|
|
181
|
+
# Sustainability report
|
|
182
|
+
report = guard.sustainability_report()
|
|
183
|
+
print(f"Total runs: {report['total_runs']}")
|
|
184
|
+
print(f"Total CO2: {report['total_co2_kg']:.6f} kg")
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
## Testing
|
|
188
|
+
|
|
189
|
+
SIOF requires `pytest`. Tests can be run after installation with:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
pytest tests/
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
All 242 tests pass in ~11 seconds.
|
|
196
|
+
|
|
197
|
+
## Architecture
|
|
198
|
+
|
|
199
|
+
```mermaid
|
|
200
|
+
graph TD
|
|
201
|
+
CLI[CLI Interface<br/>siof index/slop/mcp/memex/green]
|
|
202
|
+
API[Python API<br/>SIOFOrchestrator]
|
|
203
|
+
|
|
204
|
+
CLI --> ORCH
|
|
205
|
+
API --> ORCH
|
|
206
|
+
|
|
207
|
+
ORCH[Orchestrator<br/>Pipeline Manager]
|
|
208
|
+
|
|
209
|
+
ORCH --> IDX[DTG Indexer<br/>Graph Construction]
|
|
210
|
+
ORCH --> SLOP[De-Slopper<br/>Anti-Pattern Detection]
|
|
211
|
+
ORCH --> MCP[MCP Server<br/>Agent Interface]
|
|
212
|
+
ORCH --> MEM[Memex<br/>Intent Extraction]
|
|
213
|
+
ORCH --> GREEN[Green Guard<br/>Sustainability]
|
|
214
|
+
|
|
215
|
+
IDX --> REPO[Repository Layer<br/>File I/O + AST]
|
|
216
|
+
SLOP --> REPO
|
|
217
|
+
MCP --> REPO
|
|
218
|
+
MEM --> REPO
|
|
219
|
+
GREEN --> REPO
|
|
220
|
+
|
|
221
|
+
REPO --> DB[(SQLite<br/>DTG + Metadata)]
|
|
222
|
+
|
|
223
|
+
MCP --> POL[Policy Engine<br/>RBAC + Rate Limit]
|
|
224
|
+
MEM --> INTENT[Intent Extractor<br/>Git + Prompts]
|
|
225
|
+
GREEN --> ENERGY[Energy Calculator<br/>CO2 Tracking]
|
|
226
|
+
|
|
227
|
+
style CLI fill:#e1f5ff
|
|
228
|
+
style API fill:#e1f5ff
|
|
229
|
+
style ORCH fill:#fff4e1
|
|
230
|
+
style IDX fill:#e8f5e9
|
|
231
|
+
style SLOP fill:#e8f5e9
|
|
232
|
+
style MCP fill:#e8f5e9
|
|
233
|
+
style MEM fill:#e8f5e9
|
|
234
|
+
style GREEN fill:#e8f5e9
|
|
235
|
+
style REPO fill:#ffe4e1
|
|
236
|
+
style DB fill:#f3e5f5
|
|
237
|
+
style POL fill:#fff9e6
|
|
238
|
+
style INTENT fill:#fff9e6
|
|
239
|
+
style ENERGY fill:#fff9e6
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
## Why SIOF?
|
|
243
|
+
|
|
244
|
+
The AI-native development era (vibe coding) has introduced a new class of technical debt: **AI slop**. LLMs generate code probabilistically, leading to:
|
|
245
|
+
|
|
246
|
+
- Silent error swallowing via bare `except: pass`
|
|
247
|
+
- Hallucinated imports and dead code paths
|
|
248
|
+
- Verbose, meaningless documentation
|
|
249
|
+
- Loss of architectural intent over time
|
|
250
|
+
|
|
251
|
+
Traditional linters (Pylint, Flake8, Ruff) catch syntax errors but miss semantic anti-patterns. SIOF bridges this gap with:
|
|
252
|
+
|
|
253
|
+
1. **DTG-based analysis** - Understand data lineage, not just control flow
|
|
254
|
+
2. **Deterministic de-slopping** - Fix AI-specific anti-patterns automatically
|
|
255
|
+
3. **MCP integration** - Give AI agents proper context (120x token reduction)
|
|
256
|
+
4. **Intent preservation** - Maintain the "why" behind the code
|
|
257
|
+
5. **Sustainability** - Track and limit computational waste
|
|
258
|
+
|
|
259
|
+
## Roadmap
|
|
260
|
+
|
|
261
|
+
### v1.0 (Current) ✅
|
|
262
|
+
- DTG Indexer with incremental updates
|
|
263
|
+
- De-Slopper with audit/fix/strict modes
|
|
264
|
+
- MCP server with RBAC and rate limiting
|
|
265
|
+
- Memex intent extraction
|
|
266
|
+
- Green Guard sustainability tracking
|
|
267
|
+
|
|
268
|
+
### v2.0 (Planned)
|
|
269
|
+
- Free-threaded parsing (10x speedup on Python 3.14+)
|
|
270
|
+
- Distributed graph storage (Neo4j/FalkorDB)
|
|
271
|
+
- Enterprise MCP server (JWT, Redis, stateless)
|
|
272
|
+
- Vector-based semantic search (Milvus)
|
|
273
|
+
- Edge deployment (K3s, regional caching)
|
|
274
|
+
- Kubernetes orchestration (Helm charts)
|
|
275
|
+
- Full observability stack (OpenTelemetry, Prometheus, Grafana)
|
|
276
|
+
|
|
277
|
+
## Contributing
|
|
278
|
+
|
|
279
|
+
SIOF welcomes contributions! Whether you're fixing bugs, adding features, improving documentation, or reporting issues, your help is appreciated.
|
|
280
|
+
|
|
281
|
+
### Ways to Contribute
|
|
282
|
+
|
|
283
|
+
- Report bugs and request features via [GitHub Issues](https://github.com/Keerthivasan-Venkitajalam/SIOF/issues)
|
|
284
|
+
- Submit pull requests for bug fixes or new features
|
|
285
|
+
- Improve documentation and examples
|
|
286
|
+
- Share your use cases and feedback
|
|
287
|
+
|
|
288
|
+
### Development Setup
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
git clone https://github.com/Keerthivasan-Venkitajalam/SIOF.git
|
|
292
|
+
cd SIOF
|
|
293
|
+
pip install -e ".[dev,test]"
|
|
294
|
+
pytest tests/
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
## License
|
|
298
|
+
|
|
299
|
+
SIOF is released under the [MIT License](LICENSE).
|
|
300
|
+
|
|
301
|
+
## Author
|
|
302
|
+
|
|
303
|
+
Created by **Keerthivasan S V** - Built for the AI-native development era.
|
|
304
|
+
|
|
305
|
+
## Citation
|
|
306
|
+
|
|
307
|
+
If you use SIOF in your research or project, please cite:
|
|
308
|
+
|
|
309
|
+
```bibtex
|
|
310
|
+
@software{siof2026,
|
|
311
|
+
author = {Keerthivasan S V},
|
|
312
|
+
title = {SIOF: Semantic Integrity and Orchestration Framework},
|
|
313
|
+
year = {2026},
|
|
314
|
+
url = {https://github.com/Keerthivasan-Venkitajalam/SIOF}
|
|
315
|
+
}
|
|
316
|
+
```
|
siof-1.0.0/README.md
ADDED
|
@@ -0,0 +1,282 @@
|
|
|
1
|
+
<h1 align="center"><img src="https://github.com/Keerthivasan-Venkitajalam/SIOF/blob/main/branding/sioflogo.png" width="300"></h1><br>
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/siof/)
|
|
4
|
+
[](https://pypi.org/project/siof/)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
[](https://github.com/Keerthivasan-Venkitajalam/SIOF)
|
|
7
|
+
[](https://github.com/psf/black)
|
|
8
|
+
[](https://github.com/Keerthivasan-Venkitajalam/SIOF)
|
|
9
|
+
|
|
10
|
+
SIOF (Semantic Integrity and Orchestration Framework) is the fundamental toolkit for AI-native Python development.
|
|
11
|
+
|
|
12
|
+
- **Source code:** https://github.com/Keerthivasan-Venkitajalam/SIOF
|
|
13
|
+
- **Bug reports:** https://github.com/Keerthivasan-Venkitajalam/SIOF/issues
|
|
14
|
+
- **PyPI:** https://pypi.org/project/siof/
|
|
15
|
+
|
|
16
|
+
It provides:
|
|
17
|
+
|
|
18
|
+
- **Data Transformation Graph (DTG) indexing** - Map your codebase as data lineage, not control flow
|
|
19
|
+
- **AI slop detection** - Deterministic pattern matching for machine-generated anti-patterns
|
|
20
|
+
- **MCP graph server** - Expose your codebase to LLM agents via Model Context Protocol
|
|
21
|
+
- **Developer intent extraction (Memex)** - Preserve architectural reasoning across AI-generated mutations
|
|
22
|
+
- **Sustainability tracking (Green Guard)** - Monitor energy consumption and enforce carbon thresholds
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install siof
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Quick Start
|
|
31
|
+
|
|
32
|
+
### Index Your Repository
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
siof index build --repo /path/to/repo
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Detect AI-Generated Anti-Patterns
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
siof slop audit --repo /path/to/repo
|
|
42
|
+
siof slop fix --repo /path/to/repo
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Start MCP Server for AI Agents
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
siof mcp serve --db siof.db
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Python API
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
from siof.orchestrator import SIOFOrchestrator
|
|
55
|
+
|
|
56
|
+
# Run complete pipeline
|
|
57
|
+
orch = SIOFOrchestrator(repo=".", db_path="siof.db")
|
|
58
|
+
result = orch.run_full_pipeline(
|
|
59
|
+
index_mode="build",
|
|
60
|
+
slop_mode="audit",
|
|
61
|
+
enable_memex=True,
|
|
62
|
+
enable_green_guard=True,
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
print(f"Success: {result.success}")
|
|
66
|
+
print(f"Duration: {result.total_duration_s:.2f}s")
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Core Features
|
|
70
|
+
|
|
71
|
+
### 1. DTG Indexer
|
|
72
|
+
|
|
73
|
+
Parses Python repositories into Data Transformation Graphs, mapping data lineage instead of control flow:
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
from siof.indexer import PythonIndexer
|
|
77
|
+
|
|
78
|
+
indexer = PythonIndexer(repo=".", db_path="siof.db")
|
|
79
|
+
indexer.init()
|
|
80
|
+
result = indexer.build()
|
|
81
|
+
print(f"Indexed {result['nodes']} nodes and {result['edges']} edges")
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### 2. De-Slopper Engine
|
|
85
|
+
|
|
86
|
+
Detects and fixes AI-generated code anti-patterns:
|
|
87
|
+
|
|
88
|
+
- **NakedExceptionPass** - Bare `except: pass` blocks that swallow errors
|
|
89
|
+
- **BroadExceptionPass** - Overly broad exception handlers
|
|
90
|
+
- **HedgeComment** - LLM-generated hedge words ("robust", "comprehensive")
|
|
91
|
+
- **EchoComment** - Comments that merely restate code mechanics
|
|
92
|
+
- **SuspiciousImport** - Hallucinated dependencies
|
|
93
|
+
- **UnusedImport** - Dead imports
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
from siof.deslopper import DeSlopper
|
|
97
|
+
|
|
98
|
+
deslopper = DeSlopper(repo=".", db_path="siof.db")
|
|
99
|
+
result = deslopper.run(mode="fix") # audit, fix, or strict
|
|
100
|
+
print(f"Found {len(result.findings)} issues")
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### 3. MCP Graph Server
|
|
104
|
+
|
|
105
|
+
Exposes your DTG to LLM agents via Model Context Protocol:
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
from siof.mcp_server import MCPGraphServer
|
|
109
|
+
|
|
110
|
+
server = MCPGraphServer("siof.db")
|
|
111
|
+
# Provides tools: find_data_lineage, impact_of_change, get_dead_paths, etc.
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Features:
|
|
115
|
+
- **RBAC** with role hierarchy (viewer/analyst/admin/service)
|
|
116
|
+
- **Rate limiting** per role and organization
|
|
117
|
+
- **Distributed tracing** with trace IDs
|
|
118
|
+
- **Schema validation** for all tool inputs
|
|
119
|
+
|
|
120
|
+
### 4. Memex Intent Layer
|
|
121
|
+
|
|
122
|
+
Extracts and preserves developer intent from commits, PRs, and prompts:
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
from siof.memex import Memex
|
|
126
|
+
|
|
127
|
+
memex = Memex(repo=".", db_path="siof.db")
|
|
128
|
+
result = memex.ingest() # Extracts from git commits, PRs, prompts
|
|
129
|
+
print(f"Ingested {result['ingested']} intent records")
|
|
130
|
+
|
|
131
|
+
# Query intent
|
|
132
|
+
records = memex.query_intent(symbol="authenticate")
|
|
133
|
+
scores = memex.score_relevance("authenticate", records)
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### 5. Green Guard
|
|
137
|
+
|
|
138
|
+
Tracks energy consumption and enforces sustainability thresholds:
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
from siof.green_guard import GreenGuard
|
|
142
|
+
|
|
143
|
+
guard = GreenGuard("siof.db")
|
|
144
|
+
result = guard.run_command("pytest", hard_co2_kg=0.1)
|
|
145
|
+
print(f"Energy: {result.energy_wh:.4f} Wh, CO2: {result.co2_kg:.6f} kg")
|
|
146
|
+
|
|
147
|
+
# Sustainability report
|
|
148
|
+
report = guard.sustainability_report()
|
|
149
|
+
print(f"Total runs: {report['total_runs']}")
|
|
150
|
+
print(f"Total CO2: {report['total_co2_kg']:.6f} kg")
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Testing
|
|
154
|
+
|
|
155
|
+
SIOF requires `pytest`. Tests can be run after installation with:
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
pytest tests/
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
All 242 tests pass in ~11 seconds.
|
|
162
|
+
|
|
163
|
+
## Architecture
|
|
164
|
+
|
|
165
|
+
```mermaid
|
|
166
|
+
graph TD
|
|
167
|
+
CLI[CLI Interface<br/>siof index/slop/mcp/memex/green]
|
|
168
|
+
API[Python API<br/>SIOFOrchestrator]
|
|
169
|
+
|
|
170
|
+
CLI --> ORCH
|
|
171
|
+
API --> ORCH
|
|
172
|
+
|
|
173
|
+
ORCH[Orchestrator<br/>Pipeline Manager]
|
|
174
|
+
|
|
175
|
+
ORCH --> IDX[DTG Indexer<br/>Graph Construction]
|
|
176
|
+
ORCH --> SLOP[De-Slopper<br/>Anti-Pattern Detection]
|
|
177
|
+
ORCH --> MCP[MCP Server<br/>Agent Interface]
|
|
178
|
+
ORCH --> MEM[Memex<br/>Intent Extraction]
|
|
179
|
+
ORCH --> GREEN[Green Guard<br/>Sustainability]
|
|
180
|
+
|
|
181
|
+
IDX --> REPO[Repository Layer<br/>File I/O + AST]
|
|
182
|
+
SLOP --> REPO
|
|
183
|
+
MCP --> REPO
|
|
184
|
+
MEM --> REPO
|
|
185
|
+
GREEN --> REPO
|
|
186
|
+
|
|
187
|
+
REPO --> DB[(SQLite<br/>DTG + Metadata)]
|
|
188
|
+
|
|
189
|
+
MCP --> POL[Policy Engine<br/>RBAC + Rate Limit]
|
|
190
|
+
MEM --> INTENT[Intent Extractor<br/>Git + Prompts]
|
|
191
|
+
GREEN --> ENERGY[Energy Calculator<br/>CO2 Tracking]
|
|
192
|
+
|
|
193
|
+
style CLI fill:#e1f5ff
|
|
194
|
+
style API fill:#e1f5ff
|
|
195
|
+
style ORCH fill:#fff4e1
|
|
196
|
+
style IDX fill:#e8f5e9
|
|
197
|
+
style SLOP fill:#e8f5e9
|
|
198
|
+
style MCP fill:#e8f5e9
|
|
199
|
+
style MEM fill:#e8f5e9
|
|
200
|
+
style GREEN fill:#e8f5e9
|
|
201
|
+
style REPO fill:#ffe4e1
|
|
202
|
+
style DB fill:#f3e5f5
|
|
203
|
+
style POL fill:#fff9e6
|
|
204
|
+
style INTENT fill:#fff9e6
|
|
205
|
+
style ENERGY fill:#fff9e6
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
## Why SIOF?
|
|
209
|
+
|
|
210
|
+
The AI-native development era (vibe coding) has introduced a new class of technical debt: **AI slop**. LLMs generate code probabilistically, leading to:
|
|
211
|
+
|
|
212
|
+
- Silent error swallowing via bare `except: pass`
|
|
213
|
+
- Hallucinated imports and dead code paths
|
|
214
|
+
- Verbose, meaningless documentation
|
|
215
|
+
- Loss of architectural intent over time
|
|
216
|
+
|
|
217
|
+
Traditional linters (Pylint, Flake8, Ruff) catch syntax errors but miss semantic anti-patterns. SIOF bridges this gap with:
|
|
218
|
+
|
|
219
|
+
1. **DTG-based analysis** - Understand data lineage, not just control flow
|
|
220
|
+
2. **Deterministic de-slopping** - Fix AI-specific anti-patterns automatically
|
|
221
|
+
3. **MCP integration** - Give AI agents proper context (120x token reduction)
|
|
222
|
+
4. **Intent preservation** - Maintain the "why" behind the code
|
|
223
|
+
5. **Sustainability** - Track and limit computational waste
|
|
224
|
+
|
|
225
|
+
## Roadmap
|
|
226
|
+
|
|
227
|
+
### v1.0 (Current) ✅
|
|
228
|
+
- DTG Indexer with incremental updates
|
|
229
|
+
- De-Slopper with audit/fix/strict modes
|
|
230
|
+
- MCP server with RBAC and rate limiting
|
|
231
|
+
- Memex intent extraction
|
|
232
|
+
- Green Guard sustainability tracking
|
|
233
|
+
|
|
234
|
+
### v2.0 (Planned)
|
|
235
|
+
- Free-threaded parsing (10x speedup on Python 3.14+)
|
|
236
|
+
- Distributed graph storage (Neo4j/FalkorDB)
|
|
237
|
+
- Enterprise MCP server (JWT, Redis, stateless)
|
|
238
|
+
- Vector-based semantic search (Milvus)
|
|
239
|
+
- Edge deployment (K3s, regional caching)
|
|
240
|
+
- Kubernetes orchestration (Helm charts)
|
|
241
|
+
- Full observability stack (OpenTelemetry, Prometheus, Grafana)
|
|
242
|
+
|
|
243
|
+
## Contributing
|
|
244
|
+
|
|
245
|
+
SIOF welcomes contributions! Whether you're fixing bugs, adding features, improving documentation, or reporting issues, your help is appreciated.
|
|
246
|
+
|
|
247
|
+
### Ways to Contribute
|
|
248
|
+
|
|
249
|
+
- Report bugs and request features via [GitHub Issues](https://github.com/Keerthivasan-Venkitajalam/SIOF/issues)
|
|
250
|
+
- Submit pull requests for bug fixes or new features
|
|
251
|
+
- Improve documentation and examples
|
|
252
|
+
- Share your use cases and feedback
|
|
253
|
+
|
|
254
|
+
### Development Setup
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
git clone https://github.com/Keerthivasan-Venkitajalam/SIOF.git
|
|
258
|
+
cd SIOF
|
|
259
|
+
pip install -e ".[dev,test]"
|
|
260
|
+
pytest tests/
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
## License
|
|
264
|
+
|
|
265
|
+
SIOF is released under the [MIT License](LICENSE).
|
|
266
|
+
|
|
267
|
+
## Author
|
|
268
|
+
|
|
269
|
+
Created by **Keerthivasan S V** - Built for the AI-native development era.
|
|
270
|
+
|
|
271
|
+
## Citation
|
|
272
|
+
|
|
273
|
+
If you use SIOF in your research or project, please cite:
|
|
274
|
+
|
|
275
|
+
```bibtex
|
|
276
|
+
@software{siof2026,
|
|
277
|
+
author = {Keerthivasan S V},
|
|
278
|
+
title = {SIOF: Semantic Integrity and Orchestration Framework},
|
|
279
|
+
year = {2026},
|
|
280
|
+
url = {https://github.com/Keerthivasan-Venkitajalam/SIOF}
|
|
281
|
+
}
|
|
282
|
+
```
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "siof"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Semantic Integrity and Orchestration Framework - AI-native Python toolkit for maintaining codebase integrity"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
authors = [{name = "Keerthivasan S V", email = "keerthivasansv2006@outlook.com"}]
|
|
12
|
+
license = {text = "MIT"}
|
|
13
|
+
keywords = ["ai", "code-analysis", "graph", "mcp", "sustainability", "semantic-integrity", "autonomous-coding"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 4 - Beta",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"Topic :: Software Development :: Code Generators",
|
|
18
|
+
"Topic :: Software Development :: Quality Assurance",
|
|
19
|
+
"License :: OSI Approved :: MIT License",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
]
|
|
24
|
+
dependencies = []
|
|
25
|
+
|
|
26
|
+
[project.urls]
|
|
27
|
+
Homepage = "https://github.com/Keerthivasan-Venkitajalam/SIOF"
|
|
28
|
+
Documentation = "https://github.com/Keerthivasan-Venkitajalam/SIOF#readme"
|
|
29
|
+
Repository = "https://github.com/Keerthivasan-Venkitajalam/SIOF"
|
|
30
|
+
"Bug Tracker" = "https://github.com/Keerthivasan-Venkitajalam/SIOF/issues"
|
|
31
|
+
|
|
32
|
+
[project.optional-dependencies]
|
|
33
|
+
green = ["psutil>=5.9"]
|
|
34
|
+
test = ["pytest>=8.0", "pytest-cov>=4.0"]
|
|
35
|
+
dev = ["ruff>=0.1.0", "black>=23.0", "mypy>=1.0", "types-psutil>=5.9"]
|
|
36
|
+
|
|
37
|
+
[project.scripts]
|
|
38
|
+
siof = "siof.cli:main"
|
|
39
|
+
|
|
40
|
+
[tool.setuptools]
|
|
41
|
+
package-dir = {"" = "src"}
|
|
42
|
+
|
|
43
|
+
[tool.setuptools.packages.find]
|
|
44
|
+
where = ["src"]
|
|
45
|
+
|
|
46
|
+
[tool.pytest.ini_options]
|
|
47
|
+
testpaths = ["tests"]
|
|
48
|
+
|
|
49
|
+
[tool.ruff]
|
|
50
|
+
line-length = 100
|
|
51
|
+
target-version = "py311"
|
|
52
|
+
select = ["E", "F", "W", "I", "N", "UP", "B", "A", "C4", "PIE", "PT", "RUF"]
|
|
53
|
+
ignore = ["E501"] # line-length handled by black
|
|
54
|
+
|
|
55
|
+
[tool.ruff.isort]
|
|
56
|
+
known-first-party = ["siof"]
|
|
57
|
+
|
|
58
|
+
[tool.black]
|
|
59
|
+
line-length = 100
|
|
60
|
+
target-version = ["py311"]
|
|
61
|
+
|
|
62
|
+
[tool.mypy]
|
|
63
|
+
python_version = "3.11"
|
|
64
|
+
warn_return_any = true
|
|
65
|
+
warn_unused_configs = true
|
|
66
|
+
disallow_untyped_defs = false
|
|
67
|
+
disallow_incomplete_defs = false
|
|
68
|
+
check_untyped_defs = true
|
|
69
|
+
no_implicit_optional = true
|
|
70
|
+
warn_redundant_casts = true
|
|
71
|
+
warn_unused_ignores = true
|
|
72
|
+
warn_no_return = true
|
|
73
|
+
strict_optional = true
|
siof-1.0.0/setup.cfg
ADDED