ai-rag-common-framework 0.19.1__py3-none-any.whl
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.
- ai_rag_common_framework-0.19.1.dist-info/METADATA +428 -0
- ai_rag_common_framework-0.19.1.dist-info/RECORD +60 -0
- ai_rag_common_framework-0.19.1.dist-info/WHEEL +4 -0
- ai_rag_common_framework-0.19.1.dist-info/entry_points.txt +3 -0
- ai_rag_common_framework-0.19.1.dist-info/licenses/LICENSE +21 -0
- common_framework/__init__.py +315 -0
- common_framework/_version.py +3 -0
- common_framework/agents/__init__.py +59 -0
- common_framework/agents/hitl.py +143 -0
- common_framework/agents/memory.py +138 -0
- common_framework/agents/react.py +317 -0
- common_framework/agents/supervisor.py +205 -0
- common_framework/agents/workflow.py +188 -0
- common_framework/api/__init__.py +33 -0
- common_framework/api/app.py +253 -0
- common_framework/api/mcp.py +126 -0
- common_framework/api/routes/__init__.py +27 -0
- common_framework/api/routes/rag.py +298 -0
- common_framework/cli/__init__.py +16 -0
- common_framework/cli/__main__.py +7 -0
- common_framework/cli/doctor.py +313 -0
- common_framework/cli/main.py +161 -0
- common_framework/cli/repl.py +197 -0
- common_framework/cli/scaffold.py +125 -0
- common_framework/core/__init__.py +48 -0
- common_framework/core/cache.py +386 -0
- common_framework/core/config.py +129 -0
- common_framework/core/deprecation.py +86 -0
- common_framework/core/exceptions.py +123 -0
- common_framework/core/llm.py +1157 -0
- common_framework/core/security.py +67 -0
- common_framework/eval/__init__.py +19 -0
- common_framework/eval/hallucination.py +220 -0
- common_framework/eval/triad.py +173 -0
- common_framework/guardrails/__init__.py +27 -0
- common_framework/guardrails/moderation.py +166 -0
- common_framework/guardrails/sanitizer.py +298 -0
- common_framework/mcp/__init__.py +17 -0
- common_framework/mcp/client.py +420 -0
- common_framework/mcp/server.py +223 -0
- common_framework/observability/__init__.py +39 -0
- common_framework/observability/cost.py +201 -0
- common_framework/observability/metrics.py +120 -0
- common_framework/observability/tracing.py +180 -0
- common_framework/rag/__init__.py +62 -0
- common_framework/rag/bm25.py +201 -0
- common_framework/rag/embeddings.py +230 -0
- common_framework/rag/engine.py +434 -0
- common_framework/rag/models.py +43 -0
- common_framework/rag/rerankers.py +255 -0
- common_framework/rag/splitters.py +254 -0
- common_framework/rag/sqlite_store.py +5 -0
- common_framework/rag/storage/__init__.py +5 -0
- common_framework/rag/storage/sqlite.py +496 -0
- common_framework/rag/strategies.py +353 -0
- common_framework/rag/vectorstore.py +541 -0
- common_framework/tools/__init__.py +27 -0
- common_framework/tools/base.py +158 -0
- common_framework/tools/interpreter.py +229 -0
- common_framework/tools/registry.py +65 -0
|
@@ -0,0 +1,428 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: ai-rag-common-framework
|
|
3
|
+
Version: 0.19.1
|
|
4
|
+
Summary: A lightweight, modular, zero-bloat foundation framework for RAG, MCP servers, and modern AI workflows.
|
|
5
|
+
Author: BuhoZurdo Team
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Keywords: ai-framework,fastapi,llm,mcp,rag,tools
|
|
8
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
15
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
16
|
+
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
|
|
17
|
+
Requires-Python: >=3.11
|
|
18
|
+
Requires-Dist: httpx>=0.28.0
|
|
19
|
+
Requires-Dist: pydantic-settings>=2.7.0
|
|
20
|
+
Requires-Dist: pydantic>=2.10.0
|
|
21
|
+
Requires-Dist: typing-extensions>=4.12.0
|
|
22
|
+
Provides-Extra: all
|
|
23
|
+
Requires-Dist: fastapi>=0.115.0; extra == 'all'
|
|
24
|
+
Requires-Dist: mcp>=1.0.0; extra == 'all'
|
|
25
|
+
Requires-Dist: numpy>=1.26.0; extra == 'all'
|
|
26
|
+
Requires-Dist: pgvector>=0.3.0; extra == 'all'
|
|
27
|
+
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'all'
|
|
28
|
+
Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
|
|
29
|
+
Requires-Dist: pytest>=8.0.0; extra == 'all'
|
|
30
|
+
Requires-Dist: uvicorn>=0.30.0; extra == 'all'
|
|
31
|
+
Provides-Extra: api
|
|
32
|
+
Requires-Dist: fastapi>=0.115.0; extra == 'api'
|
|
33
|
+
Requires-Dist: uvicorn>=0.30.0; extra == 'api'
|
|
34
|
+
Provides-Extra: dev
|
|
35
|
+
Requires-Dist: fastapi>=0.115.0; extra == 'dev'
|
|
36
|
+
Requires-Dist: mcp>=1.0.0; extra == 'dev'
|
|
37
|
+
Requires-Dist: numpy>=1.26.0; extra == 'dev'
|
|
38
|
+
Requires-Dist: pgvector>=0.3.0; extra == 'dev'
|
|
39
|
+
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
|
|
40
|
+
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
|
|
41
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
42
|
+
Requires-Dist: uvicorn>=0.30.0; extra == 'dev'
|
|
43
|
+
Provides-Extra: mcp
|
|
44
|
+
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
|
|
45
|
+
Provides-Extra: rag
|
|
46
|
+
Requires-Dist: numpy>=1.26.0; extra == 'rag'
|
|
47
|
+
Requires-Dist: pgvector>=0.3.0; extra == 'rag'
|
|
48
|
+
Provides-Extra: test
|
|
49
|
+
Requires-Dist: numpy>=1.26.0; extra == 'test'
|
|
50
|
+
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
|
|
51
|
+
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
|
|
52
|
+
Requires-Dist: pytest>=8.0.0; extra == 'test'
|
|
53
|
+
Description-Content-Type: text/markdown
|
|
54
|
+
|
|
55
|
+
# AI RAG Common Framework
|
|
56
|
+
|
|
57
|
+
> A lightweight, modular, zero-bloat foundation framework for building RAG systems, Model Context Protocol (MCP) servers, autonomous multi-agent workflows, and production AI microservices.
|
|
58
|
+
|
|
59
|
+
[](https://www.python.org/)
|
|
60
|
+
[-brightgreen.svg)](CHANGELOG.md)
|
|
61
|
+
[-success.svg)](tests/)
|
|
62
|
+
[](tests/)
|
|
63
|
+
[](LICENSE)
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## ๐ Overview & Current Status: `v0.19.0` (Production Hardening & API Freeze)
|
|
68
|
+
|
|
69
|
+
**AI RAG Common Framework** is engineered as a clean, idiomatic, and dependency-light standard library for modern AI engineering. It replaces sprawling, over-engineered stacks with composable, typed primitives that work seamlessly across asynchronous coroutines and synchronous pipelines.
|
|
70
|
+
|
|
71
|
+
### ๐ Core Architectural Pillars
|
|
72
|
+
|
|
73
|
+
1. **Agnostic LLM Engine & Enterprise Resilience:**
|
|
74
|
+
* Unified asynchronous LLM client supporting Google Gemini, OpenAI, Anthropic, Ollama, DeepSeek, Groq, and vLLM.
|
|
75
|
+
* `FallbackLLMClient`: Automatic circuit-breaking failover across prioritized provider chains.
|
|
76
|
+
* Real-time Server-Sent Events (SSE) token streaming (`complete_stream()`).
|
|
77
|
+
* `SemanticCache`: Sub-millisecond similarity caching with LRU eviction and TTL invalidation.
|
|
78
|
+
* Native Pydantic Structured Outputs with schema validation.
|
|
79
|
+
|
|
80
|
+
2. **Advanced RAG & Embedded Vector Persistence:**
|
|
81
|
+
* `RAGEngine`: End-to-end orchestration of chunking, vectorization, hybrid retrieval, and generation.
|
|
82
|
+
* `SQLiteVectorStore`: ACID-compliant, single-file embedded vector store using Python's standard library `sqlite3` and FTS5 full-text indexing (no external database daemon required).
|
|
83
|
+
* `InMemoryVectorStore`: High-performance pure-Python vector store with BLAS GEMV acceleration.
|
|
84
|
+
* Hybrid Search: Native Okapi BM25 sparse matching fused with dense vector similarity via Reciprocal Rank Fusion (RRF).
|
|
85
|
+
* Algorithmic Retrieval Strategies: Parallel `MultiQueryStrategy` expansion and Hypothetical Document Embeddings (`HyDEStrategy`).
|
|
86
|
+
* Two-Stage Reranking: `LocalCrossEncoderReranker` and `CohereReranker` pipeline stages.
|
|
87
|
+
|
|
88
|
+
3. **Autonomous Agents & Stateful Workflow Orchestration:**
|
|
89
|
+
* `ReActAgent`: Autonomous thought-action-observation reasoning loop with iteration limits.
|
|
90
|
+
* `AgentSupervisor`: Orchestrator-Workers hierarchy routing subtasks to specialized agents with a shared `AgentBus` state bus.
|
|
91
|
+
* `StateGraph`: Stateful directed graph execution engine supporting cyclic and acyclic workflow topologies, conditional branching, execution history, and state checkpointing.
|
|
92
|
+
* `ConversationBufferMemory` and `VectorMemory` for contextual recall.
|
|
93
|
+
* Human-in-the-Loop (HITL) approval hooks for sensitive tool execution.
|
|
94
|
+
|
|
95
|
+
4. **Universal Tooling & Model Context Protocol (MCP 2.x):**
|
|
96
|
+
* Universal `@tool` decorator generating standard JSON schemas via Pydantic introspection.
|
|
97
|
+
* `FrameworkMCPServer`: Full MCP 2.x server adapter supporting Tools, Resources, and Prompts over **stdio** and **SSE** transports.
|
|
98
|
+
* `FrameworkMCPClient`: Bidirectional MCP client dynamically discovering and mounting remote tools into local agent registries.
|
|
99
|
+
* Single-line export: Any RAG pipeline or interpreter can be converted into an MCP tool via `as_tool()`.
|
|
100
|
+
|
|
101
|
+
5. **Security, Guardrails & Ephemeral Sandboxing:**
|
|
102
|
+
* `CodeInterpreter`: Secure Python code sandbox running in isolated subprocesses with ephemeral directories, secret scrubbing, and execution timeouts.
|
|
103
|
+
* `PromptGuardrail`: Fast regex and heuristic detection of prompt injections, jailbreaks, and system prompt override attempts.
|
|
104
|
+
* `PIISanitizer`: High-throughput redacting and masking of sensitive personal data (emails, credit cards, SSNs, API keys).
|
|
105
|
+
* Strict SSRF validation and path traversal guards across all filesystem persistence.
|
|
106
|
+
|
|
107
|
+
6. **Observability, Telemetry & Quality Evaluation:**
|
|
108
|
+
* `TokenCostTracker`: Granular dollar accounting tracking prompt and completion tokens across providers.
|
|
109
|
+
* `PrometheusRegistry`: Zero-dependency metrics router exposing `/metrics` in standard Prometheus text format.
|
|
110
|
+
* Distributed OpenTelemetry Tracing: W3C `traceparent` context propagation and `trace_span` context managers.
|
|
111
|
+
* `RAGTriadEvaluator`: In-process evaluation of Context Relevance, Groundedness (Faithfulness), and Answer Relevance.
|
|
112
|
+
* `HallucinationDetector`: Sentence-level grounding confidence scoring without third-party LLM evaluation dependencies.
|
|
113
|
+
|
|
114
|
+
7. **Developer CLI & Interactive Playground:**
|
|
115
|
+
* Unified CLI console command: `ai-rag` and `rag-mcp`.
|
|
116
|
+
* `ai-rag doctor`: Comprehensive diagnostic utility checking Python version, API keys, Ollama reachability, and directory permissions.
|
|
117
|
+
* `ai-rag repl`: Interactive terminal playground for testing prompts, running tools, ingesting documents, and executing RAG queries live.
|
|
118
|
+
* `ai-rag init`: Production microservice scaffolding generator.
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## ๐ฆ Installation
|
|
123
|
+
|
|
124
|
+
Install the package in editable mode locally:
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
pip install -e .
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Or install with optional dependencies:
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
# With MCP protocol support and full test suite
|
|
134
|
+
pip install -e ".[test,mcp]"
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## ๐ ๏ธ Quick Configuration
|
|
140
|
+
|
|
141
|
+
Create a `.env` file in your project root (refer to `.env.example`):
|
|
142
|
+
|
|
143
|
+
```env
|
|
144
|
+
FRAMEWORK_ENV=development
|
|
145
|
+
LOG_LEVEL=INFO
|
|
146
|
+
|
|
147
|
+
# Default LLM Provider (gemini, openai, anthropic, ollama)
|
|
148
|
+
DEFAULT_LLM_PROVIDER=gemini
|
|
149
|
+
DEFAULT_LLM_MODEL=gemini-2.5-flash
|
|
150
|
+
|
|
151
|
+
# API Keys
|
|
152
|
+
GEMINI_API_KEY=your_gemini_api_key
|
|
153
|
+
OPENAI_API_KEY=your_openai_api_key
|
|
154
|
+
ANTHROPIC_API_KEY=your_anthropic_api_key
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## ๐ป Usage Examples
|
|
160
|
+
|
|
161
|
+
### 1. Unified LLM with Structured Outputs & Model Fallbacks
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
import asyncio
|
|
165
|
+
from pydantic import BaseModel, Field
|
|
166
|
+
from common_framework import (
|
|
167
|
+
LLMFactory,
|
|
168
|
+
FallbackLLMClient,
|
|
169
|
+
ChatMessage,
|
|
170
|
+
Role,
|
|
171
|
+
)
|
|
172
|
+
|
|
173
|
+
class ArticleSummary(BaseModel):
|
|
174
|
+
title: str
|
|
175
|
+
key_points: list[str] = Field(description="3-5 bullet points")
|
|
176
|
+
sentiment: str = Field(description="positive, neutral, or negative")
|
|
177
|
+
|
|
178
|
+
async def main():
|
|
179
|
+
# Primary client (OpenAI) with automatic fallback to Gemini
|
|
180
|
+
primary = LLMFactory.create("openai", model="gpt-4o-mini")
|
|
181
|
+
backup = LLMFactory.create("gemini", model="gemini-2.5-flash")
|
|
182
|
+
client = FallbackLLMClient(candidates=[primary, backup])
|
|
183
|
+
|
|
184
|
+
messages = [
|
|
185
|
+
ChatMessage(
|
|
186
|
+
role=Role.USER,
|
|
187
|
+
content="Summarize: AI RAG Common Framework delivers modular RAG, MCP tools, and multi-agent workflows."
|
|
188
|
+
)
|
|
189
|
+
]
|
|
190
|
+
|
|
191
|
+
result: ArticleSummary = await client.structured_complete(
|
|
192
|
+
messages=messages,
|
|
193
|
+
response_model=ArticleSummary,
|
|
194
|
+
)
|
|
195
|
+
print(f"Title: {result.title}")
|
|
196
|
+
print(f"Points: {result.key_points}")
|
|
197
|
+
print(f"Sentiment: {result.sentiment}")
|
|
198
|
+
|
|
199
|
+
if __name__ == "__main__":
|
|
200
|
+
asyncio.run(main())
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
### 2. Embedded SQLite Vector Store with FTS5 Hybrid Search
|
|
206
|
+
|
|
207
|
+
```python
|
|
208
|
+
import asyncio
|
|
209
|
+
from common_framework import RAGEngine, SQLiteVectorStore
|
|
210
|
+
|
|
211
|
+
async def main():
|
|
212
|
+
# Single-file ACID vector store with FTS5 BM25 keyword index
|
|
213
|
+
vector_store = SQLiteVectorStore(database_path="knowledge.db")
|
|
214
|
+
|
|
215
|
+
engine = RAGEngine(vector_store=vector_store)
|
|
216
|
+
|
|
217
|
+
# Ingest knowledge documents
|
|
218
|
+
await engine.ingest_texts([
|
|
219
|
+
"Authentication is handled via Bearer JWT tokens in the HTTP Authorization header.",
|
|
220
|
+
"Rate limits are enforced using an in-memory token bucket algorithm with 60 req/min.",
|
|
221
|
+
"Database backups execute nightly at 03:00 UTC to an isolated S3 bucket."
|
|
222
|
+
])
|
|
223
|
+
|
|
224
|
+
# Hybrid query combining vector similarity with BM25 full-text rank fusion
|
|
225
|
+
response = await engine.query(
|
|
226
|
+
"How is user authentication implemented?",
|
|
227
|
+
mode="hybrid",
|
|
228
|
+
top_k=2,
|
|
229
|
+
)
|
|
230
|
+
print("Answer:\n", response.answer)
|
|
231
|
+
|
|
232
|
+
if __name__ == "__main__":
|
|
233
|
+
asyncio.run(main())
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
### 3. Multi-Agent Supervisor & Delegation Pattern
|
|
239
|
+
|
|
240
|
+
```python
|
|
241
|
+
import asyncio
|
|
242
|
+
from common_framework import AgentSupervisor, LLMFactory
|
|
243
|
+
|
|
244
|
+
async def researcher(task: str) -> str:
|
|
245
|
+
return f"Research findings: Found 3 relevant CVEs regarding SSL renegotiation."
|
|
246
|
+
|
|
247
|
+
def coder(task: str) -> str:
|
|
248
|
+
return "Patch generated: SSL_OP_NO_RENEGOTIATION flag enabled in context."
|
|
249
|
+
|
|
250
|
+
async def main():
|
|
251
|
+
supervisor = AgentSupervisor(
|
|
252
|
+
agents={
|
|
253
|
+
"researcher": ("Security researcher finding vulnerabilities", researcher),
|
|
254
|
+
"coder": ("Senior systems engineer writing security patches", coder),
|
|
255
|
+
},
|
|
256
|
+
llm_client=LLMFactory.create(),
|
|
257
|
+
max_steps=4,
|
|
258
|
+
)
|
|
259
|
+
|
|
260
|
+
response = await supervisor.run("Investigate and patch SSL renegotiation vulnerability.")
|
|
261
|
+
print("Final Resolution:\n", response.final_answer)
|
|
262
|
+
for step in response.delegations:
|
|
263
|
+
print(f"Step {step.step}: [{step.agent_name}] -> {step.result[:60]}...")
|
|
264
|
+
|
|
265
|
+
if __name__ == "__main__":
|
|
266
|
+
asyncio.run(main())
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
### 4. Stateful Directed Graph Workflow (`StateGraph`)
|
|
272
|
+
|
|
273
|
+
```python
|
|
274
|
+
import asyncio
|
|
275
|
+
from common_framework import StateGraph, START, END
|
|
276
|
+
|
|
277
|
+
def fetch_data(state: dict) -> dict:
|
|
278
|
+
return {"query": state.get("query"), "raw_text": "Sample financial report data."}
|
|
279
|
+
|
|
280
|
+
def analyze_risk(state: dict) -> dict:
|
|
281
|
+
risk_score = 75 if "financial" in state["raw_text"] else 20
|
|
282
|
+
return {"risk_score": risk_score}
|
|
283
|
+
|
|
284
|
+
def router(state: dict) -> str:
|
|
285
|
+
return "high_risk" if state["risk_score"] > 50 else "low_risk"
|
|
286
|
+
|
|
287
|
+
def flag_review(state: dict) -> dict:
|
|
288
|
+
return {"status": "Escalated for manual compliance review"}
|
|
289
|
+
|
|
290
|
+
def auto_approve(state: dict) -> dict:
|
|
291
|
+
return {"status": "Auto-approved"}
|
|
292
|
+
|
|
293
|
+
async def main():
|
|
294
|
+
graph = (
|
|
295
|
+
StateGraph()
|
|
296
|
+
.add_node("fetch", fetch_data)
|
|
297
|
+
.add_node("analyze", analyze_risk)
|
|
298
|
+
.add_node("flag_review", flag_review)
|
|
299
|
+
.add_node("auto_approve", auto_approve)
|
|
300
|
+
.add_edge(START, "fetch")
|
|
301
|
+
.add_edge("fetch", "analyze")
|
|
302
|
+
.add_conditional_edges("analyze", router, {
|
|
303
|
+
"high_risk": "flag_review",
|
|
304
|
+
"low_risk": "auto_approve",
|
|
305
|
+
})
|
|
306
|
+
.add_edge("flag_review", END)
|
|
307
|
+
.add_edge("auto_approve", END)
|
|
308
|
+
)
|
|
309
|
+
|
|
310
|
+
result = await graph.run({"query": "Audit Q3 numbers"})
|
|
311
|
+
print("Workflow Completed:", result.completed)
|
|
312
|
+
print("Final State:", result.state)
|
|
313
|
+
|
|
314
|
+
if __name__ == "__main__":
|
|
315
|
+
asyncio.run(main())
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
### 5. Sandboxed Python Code Interpreter
|
|
321
|
+
|
|
322
|
+
```python
|
|
323
|
+
import asyncio
|
|
324
|
+
from common_framework import CodeInterpreter, code_interpreter_tool
|
|
325
|
+
|
|
326
|
+
async def main():
|
|
327
|
+
# Ephemeral sandbox stripping parent secrets and enforcing 5s timeout
|
|
328
|
+
interpreter = CodeInterpreter(timeout=5.0)
|
|
329
|
+
|
|
330
|
+
code = """
|
|
331
|
+
import statistics
|
|
332
|
+
data = [10.2, 14.5, 18.9, 22.1, 35.6]
|
|
333
|
+
mean = statistics.mean(data)
|
|
334
|
+
stdev = statistics.stdev(data)
|
|
335
|
+
print(f"Mean: {mean:.2f}, Stdev: {stdev:.2f}")
|
|
336
|
+
"""
|
|
337
|
+
result = await interpreter.run(code)
|
|
338
|
+
print("Execution Success:", result.success)
|
|
339
|
+
print("Output:\n", result.stdout)
|
|
340
|
+
|
|
341
|
+
if __name__ == "__main__":
|
|
342
|
+
asyncio.run(main())
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
### 6. Production FastAPI Microservice with RAG & Authenticated MCP
|
|
348
|
+
|
|
349
|
+
```python
|
|
350
|
+
from common_framework import RAGEngine, create_app, create_mcp_server, tool
|
|
351
|
+
|
|
352
|
+
# 1. Initialize RAG Engine and MCP Server
|
|
353
|
+
rag = RAGEngine()
|
|
354
|
+
mcp = create_mcp_server(name="gateway-mcp")
|
|
355
|
+
|
|
356
|
+
@mcp.tool(name="status", description="Get cluster health status")
|
|
357
|
+
def get_status() -> dict[str, str]:
|
|
358
|
+
return {"cluster": "us-east-1", "health": "green"}
|
|
359
|
+
|
|
360
|
+
# 2. Create production FastAPI service with unified endpoints
|
|
361
|
+
app = create_app(
|
|
362
|
+
title="AI Knowledge Gateway",
|
|
363
|
+
enable_rag_routes=True, # Exposes /rag/query, /rag/retrieve, /rag/ingest, /rag/collections
|
|
364
|
+
rag_engine=rag,
|
|
365
|
+
mcp_server=mcp, # Mounts MCP server over SSE (/mcp/sse, /mcp/messages/)
|
|
366
|
+
mcp_prefix="/mcp",
|
|
367
|
+
mcp_api_key="secret-token", # Enforces Bearer / X-API-Key / ?api_key= auth
|
|
368
|
+
)
|
|
369
|
+
|
|
370
|
+
# Run with: uvicorn main:app --host 0.0.0.0 --port 8000
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
### 7. Unified Framework CLI
|
|
376
|
+
|
|
377
|
+
The package provides the `ai-rag` command-line interface out of the box:
|
|
378
|
+
|
|
379
|
+
```bash
|
|
380
|
+
# Run environment diagnostics and health checks
|
|
381
|
+
ai-rag doctor
|
|
382
|
+
|
|
383
|
+
# Output diagnostics in JSON format for CI/CD pipelines
|
|
384
|
+
ai-rag doctor --json
|
|
385
|
+
|
|
386
|
+
# Launch the interactive terminal REPL playground
|
|
387
|
+
ai-rag repl
|
|
388
|
+
|
|
389
|
+
# Scaffold a new starter microservice project
|
|
390
|
+
ai-rag init --dir ./my_ai_service
|
|
391
|
+
|
|
392
|
+
# Run a standalone MCP server over stdio or SSE
|
|
393
|
+
ai-rag run-mcp --transport stdio
|
|
394
|
+
ai-rag run-mcp --transport sse --port 8080
|
|
395
|
+
|
|
396
|
+
# Check installed framework version
|
|
397
|
+
ai-rag version
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
---
|
|
401
|
+
|
|
402
|
+
## ๐งช Running Tests & Quality Verification
|
|
403
|
+
|
|
404
|
+
The test harness executes **331 tests (100% passing)** with **91% global line coverage**:
|
|
405
|
+
* **312 unit and regression tests** across 29 focused test modules in `tests/`
|
|
406
|
+
* **19 enterprise end-to-end integration tests** across 5 test suites in `examples/enterprise/`
|
|
407
|
+
|
|
408
|
+
```bash
|
|
409
|
+
# Run all unit tests
|
|
410
|
+
python -m pytest tests/ -v
|
|
411
|
+
|
|
412
|
+
# Run full test suite with enterprise integration suites and coverage
|
|
413
|
+
python -m pytest tests/ examples/ --cov=common_framework
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
|
|
418
|
+
## ๐ Documentation & Roadmap
|
|
419
|
+
|
|
420
|
+
* [CHANGELOG.md](CHANGELOG.md): Complete release history, Pull Request notes, and breaking changes.
|
|
421
|
+
* [RELEASE.md](RELEASE.md): Gitflow release process, tagging schemes, and tag-by-tag release notes.
|
|
422
|
+
* [ROADMAP.md](ROADMAP.md): Release train progression and future architectural milestones.
|
|
423
|
+
|
|
424
|
+
---
|
|
425
|
+
|
|
426
|
+
## ๐ License
|
|
427
|
+
|
|
428
|
+
This project is licensed under the [MIT License](LICENSE).
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
common_framework/__init__.py,sha256=7SXLq6pXblvXB15PllP4UKqmPx0um_PbzC2zbwgd2m8,7621
|
|
2
|
+
common_framework/_version.py,sha256=N_KvSyVrMEkD5qx1VVe1_EOmfGkTNrCgZaQOQkyyfwA,58
|
|
3
|
+
common_framework/agents/__init__.py,sha256=uNWiIc79Aydr3ycIXl4hl9zaeC0tJHgFWDHSkIjWwws,1201
|
|
4
|
+
common_framework/agents/hitl.py,sha256=ygn8Qiiqbd8yJiHQ3e3GnJka5Q-jZ9T9l8W6NTaL78k,5037
|
|
5
|
+
common_framework/agents/memory.py,sha256=78otDMJiBs1QbK_3Hjak8a9-bupmYsl6xmnq51Yke3U,5174
|
|
6
|
+
common_framework/agents/react.py,sha256=UeEhLjK4a8o-2c0s_trT9XddeklZDwsm7YkcFQy_qLc,13282
|
|
7
|
+
common_framework/agents/supervisor.py,sha256=ZCY0dqfL9fNlba4sbDMSGWjx2QvcGjGqd-heCyVZPz0,7865
|
|
8
|
+
common_framework/agents/workflow.py,sha256=UjZZyFWdrQWCQpt9TZZP6b5L1YbQIlEKCkccOfjdPnA,7264
|
|
9
|
+
common_framework/api/__init__.py,sha256=Hr918V6o2vfV7cno6uchKp1tJ7QvH0C-0mgQsPpxkyY,908
|
|
10
|
+
common_framework/api/app.py,sha256=4URW2FDvIB_iI18AjC3j8IlIwQUACMoaV41FddMpBPs,9700
|
|
11
|
+
common_framework/api/mcp.py,sha256=gfFMgq_F88Tltvnd2RGscZcFNzMTpfxig1gHdz1JDss,4569
|
|
12
|
+
common_framework/api/routes/__init__.py,sha256=Bm69-Mo01JWM17FTjCI9JvGMDNM2fYGkWyhydldMKPI,623
|
|
13
|
+
common_framework/api/routes/rag.py,sha256=WdNOFcodgyR7IZRH_apbCM3L92QtbXsR-tcBWdsm6WA,10893
|
|
14
|
+
common_framework/cli/__init__.py,sha256=ze3B2g6JSPf7tiRi9MEMEfyoeZ6xjRd2vkPfMZRdCk4,468
|
|
15
|
+
common_framework/cli/__main__.py,sha256=91hSbuMoMWlwsZVzcXccls-717_qhWGawGsgKXZqJWs,172
|
|
16
|
+
common_framework/cli/doctor.py,sha256=MjylhNgBGIUr_kWmeNfjSHo14SpR6_rWGGRQCRpj1P8,11082
|
|
17
|
+
common_framework/cli/main.py,sha256=sNREhhgddI7XAUod7OjRFDdpvSWOoyPH7v5HBb_PDTw,6169
|
|
18
|
+
common_framework/cli/repl.py,sha256=TaTizfuS2jVpkQZodA_myKNNxXEynNcZizN39ddB3fU,8226
|
|
19
|
+
common_framework/cli/scaffold.py,sha256=yrni56xv4MpulDZB3tQb62r4RgAJ8qkir8Kqrk9jZ6I,3187
|
|
20
|
+
common_framework/core/__init__.py,sha256=AckoS839Bpn2W3ogFQfdggYarzM-OnjYOn5jqoK2F_Q,1074
|
|
21
|
+
common_framework/core/cache.py,sha256=sPbDHtNfCL2sNqtZGqCzJ8hey4EuD27NEnLA0OY-z6c,14163
|
|
22
|
+
common_framework/core/config.py,sha256=5ZGijkUq8CQFwghpkUNl_V0FRsxldWJR7wmouZJZbPs,4442
|
|
23
|
+
common_framework/core/deprecation.py,sha256=ZKQojNVyLbLVnzg-bHQGHBJfdX7_HMj7jo_6eVMTl3E,3186
|
|
24
|
+
common_framework/core/exceptions.py,sha256=LIu7Q0MmhYanWVR36hFbwbyGcJZPWT2Vby-1eoM-FKA,3610
|
|
25
|
+
common_framework/core/llm.py,sha256=fk1r1wArq9n_rNUFGrw6GCZMWflC3WW6e_T0DlbkylM,45447
|
|
26
|
+
common_framework/core/security.py,sha256=osgmRdAlIaXXMhQudZU1rbenN1JygK-oaSKluAbUdnY,2347
|
|
27
|
+
common_framework/eval/__init__.py,sha256=6MPwkLSV96-ExWG8kYRCKM8NYQTTsM8UqjCXDAk1aAo,429
|
|
28
|
+
common_framework/eval/hallucination.py,sha256=ttcFZre12dlbXPeFAWODv9X0h_qO9Rj07khYTKrPbzM,8437
|
|
29
|
+
common_framework/eval/triad.py,sha256=5GgOdmOom4yMnNpfPd6kE6WEDJdktlv8TbHP9fNus6U,6810
|
|
30
|
+
common_framework/guardrails/__init__.py,sha256=OhI2ZfQ9LgbS1PcIDUa1KKq27fyiI_vPpjotD0dUXno,587
|
|
31
|
+
common_framework/guardrails/moderation.py,sha256=DbSFrc2T7SgjC-kCmNI4OYMiMz3knDiLcpB2h6t83kQ,5796
|
|
32
|
+
common_framework/guardrails/sanitizer.py,sha256=dZIO6jAMQNyntXpR4hA3p2ZCbw5UukfSiTE5gXY0kZ8,10658
|
|
33
|
+
common_framework/mcp/__init__.py,sha256=F5T8F9NDfJxmBeu01YGBAuPDoRwuYZD4JCb_9OS_k34,385
|
|
34
|
+
common_framework/mcp/client.py,sha256=gYWdalaUN5s2VPig2ON9UoRH0-kj0wSVEyrkRf2Jk5A,16034
|
|
35
|
+
common_framework/mcp/server.py,sha256=Z7oFJV6YBdiR30N1tOLmQhOyPX8UDsFJVNGUAbQJJyc,8285
|
|
36
|
+
common_framework/observability/__init__.py,sha256=e_aI_2gd_bXkAK3TteGvntbEFMlXWg32jCtEb1qTXY8,912
|
|
37
|
+
common_framework/observability/cost.py,sha256=AstND2bS8ssZ_C7B0aXWz47ctdnhImkpb3EB60rX4o4,8636
|
|
38
|
+
common_framework/observability/metrics.py,sha256=kSKVtThF7q28Y5cm4gHKplGd6z4uaRG2G90wmLx6u6U,4756
|
|
39
|
+
common_framework/observability/tracing.py,sha256=mIAPG5qaDnKykfnPTA6U0VJ4fH07Ni58xpYDW2iA4rs,6068
|
|
40
|
+
common_framework/rag/__init__.py,sha256=c0A7CAdGFbEqKxzn6EG7UFe-VJhajA6hlyNJHE-92yE,1603
|
|
41
|
+
common_framework/rag/bm25.py,sha256=o5GfTZ92DxRf9SW4P59IPoWmhx480_H4ZyD8pt5X4so,7834
|
|
42
|
+
common_framework/rag/embeddings.py,sha256=RnnWdEoMrR4lztyXNS5UKQYp2LrrhPZqpxnWRQBEtoM,8763
|
|
43
|
+
common_framework/rag/engine.py,sha256=phzztQtrf8QbaE3af1qwsPJTMykljOljHo_bDCRK5T4,16157
|
|
44
|
+
common_framework/rag/models.py,sha256=Hbytza2_FLJC9lQFfQBtyVzqUq31pjDQBFrfz1L7VMg,1364
|
|
45
|
+
common_framework/rag/rerankers.py,sha256=B4RvZKa3A5Qnaqj2lEkJQGRYbmQJBcKQZu-q6JRlnuQ,8836
|
|
46
|
+
common_framework/rag/splitters.py,sha256=inf71Ufy6bPwk9S2HI3HK-GsLTeCHmRJ9bimFNsQVrU,10166
|
|
47
|
+
common_framework/rag/sqlite_store.py,sha256=8nLQ5rnntKjBejKP6XVkwHEmyuaZ0uedgSmdqFpaiCs,185
|
|
48
|
+
common_framework/rag/strategies.py,sha256=fyk_AbrKoVWiSngtFrz92QCsiOWAgAX9lgYATQGeWBE,13221
|
|
49
|
+
common_framework/rag/vectorstore.py,sha256=9YCPgUoYQuBZS0QNPA5QLqSeuow7kYe1xKDseYTruOA,21742
|
|
50
|
+
common_framework/rag/storage/__init__.py,sha256=vHVtNxDWaGqMLtFSgsRJXzRhjn9EdluAPm-O-n3uU_Y,171
|
|
51
|
+
common_framework/rag/storage/sqlite.py,sha256=BJCt3jG8AJ2Thxfko3lSBiVx_LLYbxMwSsXoSkkhcfo,18987
|
|
52
|
+
common_framework/tools/__init__.py,sha256=mFASKU3Orh4BuGfzrjVeKwU5Sx_qnYnyD9fqM6tSUdM,668
|
|
53
|
+
common_framework/tools/base.py,sha256=ER46ZJZ9mooQRu2ashmZChynHQe1oSGCTlkJDkrzBtg,5759
|
|
54
|
+
common_framework/tools/interpreter.py,sha256=OJ-RE_DUXDYuQdLmRVb0BXOkSKTJPUIvjOTHgF3Eilc,7975
|
|
55
|
+
common_framework/tools/registry.py,sha256=DDRcCgAsbycUoS50Am-MZ-ObErCmYyIxdoBlLaybm-4,2220
|
|
56
|
+
ai_rag_common_framework-0.19.1.dist-info/METADATA,sha256=JGXC2yn5qb_mlZntmB2lqr3wQsroQOlROS-wnKiN7Mc,15806
|
|
57
|
+
ai_rag_common_framework-0.19.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
58
|
+
ai_rag_common_framework-0.19.1.dist-info/entry_points.txt,sha256=p8sSdXW8uNnro3fNZWFDUxVUHCX0XLRpc81652g2VhI,99
|
|
59
|
+
ai_rag_common_framework-0.19.1.dist-info/licenses/LICENSE,sha256=_n3c_RIYHVenzhT-97VzDQNOlxogogxaI5flpFAD5wY,1066
|
|
60
|
+
ai_rag_common_framework-0.19.1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BuhoZurdo
|
|
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.
|