vectorwave 0.2.8__tar.gz → 0.2.9__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.
- vectorwave-0.2.9/PKG-INFO +255 -0
- vectorwave-0.2.9/Readme.md +226 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/pyproject.toml +4 -2
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/core/decorator.py +16 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/database/db.py +1 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/models/db_config.py +18 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/monitoring/tracer.py +14 -2
- vectorwave-0.2.9/src/vectorwave/utils/github_pr.py +87 -0
- vectorwave-0.2.9/src/vectorwave/utils/healer.py +330 -0
- vectorwave-0.2.9/src/vectorwave/utils/path_utils.py +32 -0
- vectorwave-0.2.9/src/vectorwave/utils/scheduler.py +127 -0
- vectorwave-0.2.8/PKG-INFO +0 -60
- vectorwave-0.2.8/Readme.md +0 -33
- vectorwave-0.2.8/src/vectorwave/utils/healer.py +0 -155
- {vectorwave-0.2.8 → vectorwave-0.2.9}/crates/Cargo.lock +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/crates/Cargo.toml +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/crates/src/lib.rs +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/batch/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/batch/batch.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/core/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/core/auto_injector.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/core/core.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/core/generator.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/core/llm/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/core/llm/base.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/core/llm/factory.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/core/llm/openai_client.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/database/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/database/archiver.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/database/dataset.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/database/db_search.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/exception/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/exception/exceptions.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/models/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/monitoring/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/monitoring/alert/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/monitoring/alert/base.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/monitoring/alert/factory.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/monitoring/alert/null_alerter.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/monitoring/alert/webhook_alerter.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/monitoring/monitoring.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/prediction/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/prediction/predictor.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/search/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/search/execution_search.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/search/extended_search.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/search/rag_search.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/utils/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/utils/context.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/utils/function_cache.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/utils/replayer.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/utils/replayer_semantic.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/utils/return_caching_utils.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/utils/status.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/vectorizer/__init__.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/vectorizer/base.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/vectorizer/factory.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/vectorizer/huggingface_vectorizer.py +0 -0
- {vectorwave-0.2.8 → vectorwave-0.2.9}/src/vectorwave/vectorizer/openai_vectorizer.py +0 -0
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: vectorwave
|
|
3
|
+
Version: 0.2.9
|
|
4
|
+
Classifier: Programming Language :: Python :: 3
|
|
5
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
6
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
7
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
8
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
9
|
+
Classifier: Programming Language :: Rust
|
|
10
|
+
Classifier: Operating System :: OS Independent
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Requires-Dist: weaviate-client>=4.0.0
|
|
14
|
+
Requires-Dist: pydantic-settings>=2.0.0
|
|
15
|
+
Requires-Dist: sentence-transformers
|
|
16
|
+
Requires-Dist: requests
|
|
17
|
+
Requires-Dist: openai
|
|
18
|
+
Requires-Dist: pygithub
|
|
19
|
+
Requires-Dist: schedule
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
License-File: NOTICE
|
|
22
|
+
Summary: VectorWave: Seamless Auto-Vectorization Framework
|
|
23
|
+
Author-email: junyeonggim <junyeonggim5@gmail.com>
|
|
24
|
+
License-Expression: MIT
|
|
25
|
+
Requires-Python: >=3.10
|
|
26
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
27
|
+
Project-URL: Repository, https://github.com/cozymori/vectorwave
|
|
28
|
+
|
|
29
|
+
Need more information? Visit [here](https://cozymori.github.io/vectorwave-docs/)
|
|
30
|
+
|
|
31
|
+
# VectorWave
|
|
32
|
+

|
|
33
|
+

|
|
34
|
+

|
|
35
|
+

|
|
36
|
+

|
|
37
|
+

|
|
38
|
+

|
|
39
|
+

|
|
40
|
+

|
|
41
|
+
<br>**Seamless Auto-Vectorization Framework**
|
|
42
|
+
|
|
43
|
+
We transform volatile data that disappears the moment code is executed into a Searchable and Reusable permanent knowledge asset.
|
|
44
|
+
|
|
45
|
+
### Requirements
|
|
46
|
+
|
|
47
|
+
* **Python**: 3.10 ~ 3.13
|
|
48
|
+
* **Docker**: Required to run the Weaviate database.
|
|
49
|
+
* (Optional) **OpenAI API Key**: Required for AI auto-documentation and high-performance embedding.
|
|
50
|
+
|
|
51
|
+
### How to reach us
|
|
52
|
+
|
|
53
|
+
Have questions or found a bug? Please join our community.
|
|
54
|
+
|
|
55
|
+
* **GitHub Issues**: [https://github.com/cozymori/vectorwave/issues](https://github.com/cozymori/vectorwave/issues)
|
|
56
|
+
|
|
57
|
+
### Contributors
|
|
58
|
+
[See the contributors of vectorwave](https://github.com/Cozymori/VectorWave/graphs/contributors)<br>
|
|
59
|
+
VectorWave is an open-source project and we welcome your contributions.
|
|
60
|
+
Please refer to [CONTRIBUTING.md](https://www.google.com/search?q=https://github.com/cozymori/vectorwave/blob/main/CONTRIBUTING.md) in the GitHub repository.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## 🚀 What is VectorWave?
|
|
65
|
+
|
|
66
|
+
**VectorWave** is a unified framework designed to solve the "Efficiency vs. Reliability" dilemma in LLM-integrated applications. It introduces a new paradigm of **Execution-Level Semantic Optimization** combined with **Autonomous Self-Healing**.
|
|
67
|
+
|
|
68
|
+
Unlike conventional semantic caching tools that primarily focus on text similarity, **VectorWave** captures the entire **Function Execution Context**. It creates a permanent "Golden Dataset" from your successful executions and uses it to:
|
|
69
|
+
|
|
70
|
+
1. **Slash Costs**: Serve cached results for semantically similar inputs, bypassing expensive computations.
|
|
71
|
+
2. **Fix Bugs**: Automatically diagnose runtime errors and generate GitHub PRs using LLM.
|
|
72
|
+
3. **Monitor Quality**: Detect when user inputs start drifting away from known patterns (Semantic Drift).
|
|
73
|
+
|
|
74
|
+
## Architecture
|
|
75
|
+
|
|
76
|
+
VectorWave operates as a transparent layer between your application and the LLM/Infrastructure, handling everything from vectorization to GitOps automation.
|
|
77
|
+
|
|
78
|
+

|
|
79
|
+
|
|
80
|
+
### Core Components
|
|
81
|
+
* **Optimization Engine**: Intercepts function calls to check for semantic cache hits using HNSW indexes.
|
|
82
|
+
* **Trace Context Manager**: Collects execution logs, inputs, and outputs without modifying your code structure.
|
|
83
|
+
* **Self-Healing Pipeline**: An autonomous agent that wakes up on errors, diagnoses the root cause, and submits patches.
|
|
84
|
+
|
|
85
|
+
## 😊 Quick Start
|
|
86
|
+
|
|
87
|
+
You can attach VectorWave to any Python function using a simple decorator.
|
|
88
|
+
|
|
89
|
+
### 1. Prerequisites (Start Vector DB)
|
|
90
|
+
|
|
91
|
+
VectorWave requires a Vector Database (Weaviate) to store execution contexts.
|
|
92
|
+
Create a `docker-compose.yml` file and start the service:
|
|
93
|
+
|
|
94
|
+
```yaml
|
|
95
|
+
# docker-compose.yml
|
|
96
|
+
version: '3.4'
|
|
97
|
+
services:
|
|
98
|
+
weaviate:
|
|
99
|
+
command:
|
|
100
|
+
- --host
|
|
101
|
+
- 0.0.0.0
|
|
102
|
+
- --port
|
|
103
|
+
- '8080'
|
|
104
|
+
- --scheme
|
|
105
|
+
- http
|
|
106
|
+
image: semitechnologies/weaviate:1.26.1
|
|
107
|
+
ports:
|
|
108
|
+
- 8080:8080
|
|
109
|
+
- 50051:50051
|
|
110
|
+
restart: on-failure:0
|
|
111
|
+
environment:
|
|
112
|
+
QUERY_DEFAULTS_LIMIT: 25
|
|
113
|
+
AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
|
|
114
|
+
PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
|
|
115
|
+
DEFAULT_VECTORIZER_MODULE: 'none'
|
|
116
|
+
ENABLE_MODULES: 'text2vec-openai,generative-openai'
|
|
117
|
+
CLUSTER_HOSTNAME: 'node1'
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Run the container:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
docker-compose up -d
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### 2. Install VectorWave
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
pip install vectorwave
|
|
132
|
+
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### 3. Basic Usage (Semantic Caching)
|
|
136
|
+
|
|
137
|
+
Now, apply the `@vectorize` decorator to your functions.
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
import time
|
|
141
|
+
from vectorwave import vectorize, initialize_database
|
|
142
|
+
|
|
143
|
+
# 1. (Optional) Set up your OpenAI Key for vectorization
|
|
144
|
+
# os.environ["OPENAI_API_KEY"] = "sk-..."
|
|
145
|
+
|
|
146
|
+
initialize_database()
|
|
147
|
+
|
|
148
|
+
# 2. Just add the @vectorize decorator!
|
|
149
|
+
@vectorize(semantic_cache=True, cache_threshold=0.95, auto=True)
|
|
150
|
+
def expensive_llm_task(query: str):
|
|
151
|
+
# Simulate a slow and expensive API call
|
|
152
|
+
time.sleep(2)
|
|
153
|
+
return f"Processed result for: {query}"
|
|
154
|
+
|
|
155
|
+
# First call: Runs the function (Cache Miss) -> Took 2.0s
|
|
156
|
+
print(expensive_llm_task("How do I fix a Python bug?"))
|
|
157
|
+
|
|
158
|
+
# Second call: Returns from Weaviate DB (Cache Hit) -> Took 0.02s!
|
|
159
|
+
# Even if the query is slightly different but semantically same.
|
|
160
|
+
print(expensive_llm_task("Tell me how to debug Python code."))
|
|
161
|
+
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### 4. Self-Healing in Action
|
|
165
|
+
|
|
166
|
+
When your code breaks, VectorWave actively fixes it.
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
# Suppose this function has a bug (ZeroDivisionError)
|
|
170
|
+
@vectorize(auto=True)
|
|
171
|
+
def risky_calculation(a, b):
|
|
172
|
+
return a / b
|
|
173
|
+
|
|
174
|
+
# Triggering an error
|
|
175
|
+
risky_calculation(10, 0)
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
**What happens next?**
|
|
180
|
+
|
|
181
|
+
1. **Detection**: The `AutoHealerBot` detects the `ZeroDivisionError`.
|
|
182
|
+
2. **Diagnosis**: It retrieves the source code and error stack trace.
|
|
183
|
+
3. **Fix**: It uses an LLM to generate a patch (adding `try-except` or input validation).
|
|
184
|
+
4. **Action**: A **Pull Request** is automatically created in your GitHub repository.
|
|
185
|
+
|
|
186
|
+

|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
## Key Features
|
|
190
|
+
|
|
191
|
+
### ⚡ Optimization Engine (Semantic Caching)
|
|
192
|
+
|
|
193
|
+
Don't pay for the same computation twice. VectorWave uses **Weaviate** vector database to store and retrieve function results based on meaning, not just exact string matching.
|
|
194
|
+
|
|
195
|
+
* **Latency**: Reduced from seconds to milliseconds.
|
|
196
|
+
* **Cost**: Up to 90% reduction in LLM token usage.
|
|
197
|
+
|
|
198
|
+

|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
### Self-Healing & GitOps
|
|
202
|
+
|
|
203
|
+
VectorWave doesn't just log errors; it acts on them.
|
|
204
|
+
|
|
205
|
+
* **Automated Root Cause Analysis (RCA)** using RAG.
|
|
206
|
+
* **GitOps Integration**: Generates actual code fixes and pushes them to a new branch.
|
|
207
|
+
* **Cooldown Mechanism**: Prevents spamming PRs for the same error.
|
|
208
|
+
|
|
209
|
+
### Semantic Drift Radar
|
|
210
|
+
|
|
211
|
+
Detect when your users are asking things your model wasn't designed for.
|
|
212
|
+
|
|
213
|
+
* **Anomaly Detection**: Calculates the distance between new queries and your "Golden Dataset".
|
|
214
|
+
* **Alerting**: Sends notifications (e.g., Discord) when drift exceeds the threshold (default 0.25).
|
|
215
|
+
|
|
216
|
+

|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
## How does it work?
|
|
220
|
+
|
|
221
|
+
Unlike traditional Key-Value caching (e.g., Redis), VectorWave understands **Context**.
|
|
222
|
+
|
|
223
|
+
1. **Vectorization**: It converts function arguments into high-dimensional vectors using OpenAI or HuggingFace models.
|
|
224
|
+
2. **Search**: It performs an Approximate Nearest Neighbor (ANN) search in the vector store.
|
|
225
|
+
3. **Decision**:
|
|
226
|
+
* If a neighbor is found within the `threshold` -> **Return Cached Result**.
|
|
227
|
+
* If not -> **Execute Function** -> **Async Log to DB**.
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
|
|
231
|
+
## Performance Benchmark
|
|
232
|
+
|
|
233
|
+
| Metric | Direct Execution | With VectorWave | Improvement |
|
|
234
|
+
| --- | --- | --- | --- |
|
|
235
|
+
| **Latency (Hit)** | ~2.5s (LLM API) | **~0.02s** | **125x Faster** |
|
|
236
|
+
| **Cost (Hit)** | $0.03 / call | **$0.00** | **100% Savings** |
|
|
237
|
+
| **Reliability** | Manual Fix Required | **Auto-PR Created** | **Autonomous** |
|
|
238
|
+
|
|
239
|
+
## Feature Comparison
|
|
240
|
+
|
|
241
|
+
Why choose VectorWave over traditional semantic caches?
|
|
242
|
+
|
|
243
|
+
| Feature | Traditional Tools (e.g., GPTCache) | **VectorWave** |
|
|
244
|
+
| :--- | :---: | :---: |
|
|
245
|
+
| **Semantic Caching** | O (Text-based) | **O (Execution Context)** |
|
|
246
|
+
| **Self-Healing (Auto-Fix)** | X | **O (Autonomous)** |
|
|
247
|
+
| **GitOps (Auto-PR)** | X | **O (Seamless)** |
|
|
248
|
+
| **Semantic Drift Detection** | X | **O (Drift Radar)** |
|
|
249
|
+
| **Zero-Config Setup** | △ (Setup Required) | **O (Decorator)** |
|
|
250
|
+
|
|
251
|
+
## 😍 Contributing
|
|
252
|
+
|
|
253
|
+
We are extremely open to contributions! Whether it's a new vectorizer, a better healing prompt, or just a typo fix.
|
|
254
|
+
Please check our [Contribution Guide](./Contributing.md).
|
|
255
|
+
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
Need more information? Visit [here](https://cozymori.github.io/vectorwave-docs/)
|
|
2
|
+
|
|
3
|
+
# VectorWave
|
|
4
|
+

|
|
5
|
+

|
|
6
|
+

|
|
7
|
+

|
|
8
|
+

|
|
9
|
+

|
|
10
|
+

|
|
11
|
+

|
|
12
|
+

|
|
13
|
+
<br>**Seamless Auto-Vectorization Framework**
|
|
14
|
+
|
|
15
|
+
We transform volatile data that disappears the moment code is executed into a Searchable and Reusable permanent knowledge asset.
|
|
16
|
+
|
|
17
|
+
### Requirements
|
|
18
|
+
|
|
19
|
+
* **Python**: 3.10 ~ 3.13
|
|
20
|
+
* **Docker**: Required to run the Weaviate database.
|
|
21
|
+
* (Optional) **OpenAI API Key**: Required for AI auto-documentation and high-performance embedding.
|
|
22
|
+
|
|
23
|
+
### How to reach us
|
|
24
|
+
|
|
25
|
+
Have questions or found a bug? Please join our community.
|
|
26
|
+
|
|
27
|
+
* **GitHub Issues**: [https://github.com/cozymori/vectorwave/issues](https://github.com/cozymori/vectorwave/issues)
|
|
28
|
+
|
|
29
|
+
### Contributors
|
|
30
|
+
[See the contributors of vectorwave](https://github.com/Cozymori/VectorWave/graphs/contributors)<br>
|
|
31
|
+
VectorWave is an open-source project and we welcome your contributions.
|
|
32
|
+
Please refer to [CONTRIBUTING.md](https://www.google.com/search?q=https://github.com/cozymori/vectorwave/blob/main/CONTRIBUTING.md) in the GitHub repository.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 🚀 What is VectorWave?
|
|
37
|
+
|
|
38
|
+
**VectorWave** is a unified framework designed to solve the "Efficiency vs. Reliability" dilemma in LLM-integrated applications. It introduces a new paradigm of **Execution-Level Semantic Optimization** combined with **Autonomous Self-Healing**.
|
|
39
|
+
|
|
40
|
+
Unlike conventional semantic caching tools that primarily focus on text similarity, **VectorWave** captures the entire **Function Execution Context**. It creates a permanent "Golden Dataset" from your successful executions and uses it to:
|
|
41
|
+
|
|
42
|
+
1. **Slash Costs**: Serve cached results for semantically similar inputs, bypassing expensive computations.
|
|
43
|
+
2. **Fix Bugs**: Automatically diagnose runtime errors and generate GitHub PRs using LLM.
|
|
44
|
+
3. **Monitor Quality**: Detect when user inputs start drifting away from known patterns (Semantic Drift).
|
|
45
|
+
|
|
46
|
+
## Architecture
|
|
47
|
+
|
|
48
|
+
VectorWave operates as a transparent layer between your application and the LLM/Infrastructure, handling everything from vectorization to GitOps automation.
|
|
49
|
+
|
|
50
|
+

|
|
51
|
+
|
|
52
|
+
### Core Components
|
|
53
|
+
* **Optimization Engine**: Intercepts function calls to check for semantic cache hits using HNSW indexes.
|
|
54
|
+
* **Trace Context Manager**: Collects execution logs, inputs, and outputs without modifying your code structure.
|
|
55
|
+
* **Self-Healing Pipeline**: An autonomous agent that wakes up on errors, diagnoses the root cause, and submits patches.
|
|
56
|
+
|
|
57
|
+
## 😊 Quick Start
|
|
58
|
+
|
|
59
|
+
You can attach VectorWave to any Python function using a simple decorator.
|
|
60
|
+
|
|
61
|
+
### 1. Prerequisites (Start Vector DB)
|
|
62
|
+
|
|
63
|
+
VectorWave requires a Vector Database (Weaviate) to store execution contexts.
|
|
64
|
+
Create a `docker-compose.yml` file and start the service:
|
|
65
|
+
|
|
66
|
+
```yaml
|
|
67
|
+
# docker-compose.yml
|
|
68
|
+
version: '3.4'
|
|
69
|
+
services:
|
|
70
|
+
weaviate:
|
|
71
|
+
command:
|
|
72
|
+
- --host
|
|
73
|
+
- 0.0.0.0
|
|
74
|
+
- --port
|
|
75
|
+
- '8080'
|
|
76
|
+
- --scheme
|
|
77
|
+
- http
|
|
78
|
+
image: semitechnologies/weaviate:1.26.1
|
|
79
|
+
ports:
|
|
80
|
+
- 8080:8080
|
|
81
|
+
- 50051:50051
|
|
82
|
+
restart: on-failure:0
|
|
83
|
+
environment:
|
|
84
|
+
QUERY_DEFAULTS_LIMIT: 25
|
|
85
|
+
AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
|
|
86
|
+
PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
|
|
87
|
+
DEFAULT_VECTORIZER_MODULE: 'none'
|
|
88
|
+
ENABLE_MODULES: 'text2vec-openai,generative-openai'
|
|
89
|
+
CLUSTER_HOSTNAME: 'node1'
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Run the container:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
docker-compose up -d
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### 2. Install VectorWave
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
pip install vectorwave
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### 3. Basic Usage (Semantic Caching)
|
|
108
|
+
|
|
109
|
+
Now, apply the `@vectorize` decorator to your functions.
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
import time
|
|
113
|
+
from vectorwave import vectorize, initialize_database
|
|
114
|
+
|
|
115
|
+
# 1. (Optional) Set up your OpenAI Key for vectorization
|
|
116
|
+
# os.environ["OPENAI_API_KEY"] = "sk-..."
|
|
117
|
+
|
|
118
|
+
initialize_database()
|
|
119
|
+
|
|
120
|
+
# 2. Just add the @vectorize decorator!
|
|
121
|
+
@vectorize(semantic_cache=True, cache_threshold=0.95, auto=True)
|
|
122
|
+
def expensive_llm_task(query: str):
|
|
123
|
+
# Simulate a slow and expensive API call
|
|
124
|
+
time.sleep(2)
|
|
125
|
+
return f"Processed result for: {query}"
|
|
126
|
+
|
|
127
|
+
# First call: Runs the function (Cache Miss) -> Took 2.0s
|
|
128
|
+
print(expensive_llm_task("How do I fix a Python bug?"))
|
|
129
|
+
|
|
130
|
+
# Second call: Returns from Weaviate DB (Cache Hit) -> Took 0.02s!
|
|
131
|
+
# Even if the query is slightly different but semantically same.
|
|
132
|
+
print(expensive_llm_task("Tell me how to debug Python code."))
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### 4. Self-Healing in Action
|
|
137
|
+
|
|
138
|
+
When your code breaks, VectorWave actively fixes it.
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
# Suppose this function has a bug (ZeroDivisionError)
|
|
142
|
+
@vectorize(auto=True)
|
|
143
|
+
def risky_calculation(a, b):
|
|
144
|
+
return a / b
|
|
145
|
+
|
|
146
|
+
# Triggering an error
|
|
147
|
+
risky_calculation(10, 0)
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
**What happens next?**
|
|
152
|
+
|
|
153
|
+
1. **Detection**: The `AutoHealerBot` detects the `ZeroDivisionError`.
|
|
154
|
+
2. **Diagnosis**: It retrieves the source code and error stack trace.
|
|
155
|
+
3. **Fix**: It uses an LLM to generate a patch (adding `try-except` or input validation).
|
|
156
|
+
4. **Action**: A **Pull Request** is automatically created in your GitHub repository.
|
|
157
|
+
|
|
158
|
+

|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
## Key Features
|
|
162
|
+
|
|
163
|
+
### ⚡ Optimization Engine (Semantic Caching)
|
|
164
|
+
|
|
165
|
+
Don't pay for the same computation twice. VectorWave uses **Weaviate** vector database to store and retrieve function results based on meaning, not just exact string matching.
|
|
166
|
+
|
|
167
|
+
* **Latency**: Reduced from seconds to milliseconds.
|
|
168
|
+
* **Cost**: Up to 90% reduction in LLM token usage.
|
|
169
|
+
|
|
170
|
+

|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
### Self-Healing & GitOps
|
|
174
|
+
|
|
175
|
+
VectorWave doesn't just log errors; it acts on them.
|
|
176
|
+
|
|
177
|
+
* **Automated Root Cause Analysis (RCA)** using RAG.
|
|
178
|
+
* **GitOps Integration**: Generates actual code fixes and pushes them to a new branch.
|
|
179
|
+
* **Cooldown Mechanism**: Prevents spamming PRs for the same error.
|
|
180
|
+
|
|
181
|
+
### Semantic Drift Radar
|
|
182
|
+
|
|
183
|
+
Detect when your users are asking things your model wasn't designed for.
|
|
184
|
+
|
|
185
|
+
* **Anomaly Detection**: Calculates the distance between new queries and your "Golden Dataset".
|
|
186
|
+
* **Alerting**: Sends notifications (e.g., Discord) when drift exceeds the threshold (default 0.25).
|
|
187
|
+
|
|
188
|
+

|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
## How does it work?
|
|
192
|
+
|
|
193
|
+
Unlike traditional Key-Value caching (e.g., Redis), VectorWave understands **Context**.
|
|
194
|
+
|
|
195
|
+
1. **Vectorization**: It converts function arguments into high-dimensional vectors using OpenAI or HuggingFace models.
|
|
196
|
+
2. **Search**: It performs an Approximate Nearest Neighbor (ANN) search in the vector store.
|
|
197
|
+
3. **Decision**:
|
|
198
|
+
* If a neighbor is found within the `threshold` -> **Return Cached Result**.
|
|
199
|
+
* If not -> **Execute Function** -> **Async Log to DB**.
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
## Performance Benchmark
|
|
204
|
+
|
|
205
|
+
| Metric | Direct Execution | With VectorWave | Improvement |
|
|
206
|
+
| --- | --- | --- | --- |
|
|
207
|
+
| **Latency (Hit)** | ~2.5s (LLM API) | **~0.02s** | **125x Faster** |
|
|
208
|
+
| **Cost (Hit)** | $0.03 / call | **$0.00** | **100% Savings** |
|
|
209
|
+
| **Reliability** | Manual Fix Required | **Auto-PR Created** | **Autonomous** |
|
|
210
|
+
|
|
211
|
+
## Feature Comparison
|
|
212
|
+
|
|
213
|
+
Why choose VectorWave over traditional semantic caches?
|
|
214
|
+
|
|
215
|
+
| Feature | Traditional Tools (e.g., GPTCache) | **VectorWave** |
|
|
216
|
+
| :--- | :---: | :---: |
|
|
217
|
+
| **Semantic Caching** | O (Text-based) | **O (Execution Context)** |
|
|
218
|
+
| **Self-Healing (Auto-Fix)** | X | **O (Autonomous)** |
|
|
219
|
+
| **GitOps (Auto-PR)** | X | **O (Seamless)** |
|
|
220
|
+
| **Semantic Drift Detection** | X | **O (Drift Radar)** |
|
|
221
|
+
| **Zero-Config Setup** | △ (Setup Required) | **O (Decorator)** |
|
|
222
|
+
|
|
223
|
+
## 😍 Contributing
|
|
224
|
+
|
|
225
|
+
We are extremely open to contributions! Whether it's a new vectorizer, a better healing prompt, or just a typo fix.
|
|
226
|
+
Please check our [Contribution Guide](./Contributing.md).
|
|
@@ -5,7 +5,7 @@ build-backend = "maturin"
|
|
|
5
5
|
|
|
6
6
|
[project]
|
|
7
7
|
name = "vectorwave"
|
|
8
|
-
version = "0.2.
|
|
8
|
+
version = "0.2.09"
|
|
9
9
|
authors = [
|
|
10
10
|
{ name = "junyeonggim", email = "junyeonggim5@gmail.com" },
|
|
11
11
|
]
|
|
@@ -30,7 +30,9 @@ dependencies = [
|
|
|
30
30
|
"pydantic-settings>=2.0.0",
|
|
31
31
|
"sentence-transformers",
|
|
32
32
|
"requests",
|
|
33
|
-
"openai"
|
|
33
|
+
"openai",
|
|
34
|
+
"PyGithub",
|
|
35
|
+
"schedule"
|
|
34
36
|
]
|
|
35
37
|
|
|
36
38
|
[project.urls]
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import inspect
|
|
2
2
|
import logging
|
|
3
|
+
import os
|
|
3
4
|
from functools import wraps
|
|
4
5
|
from typing import List, Optional, Dict, Any
|
|
5
6
|
|
|
@@ -12,6 +13,7 @@ from ..utils.function_cache import function_cache_manager
|
|
|
12
13
|
from ..utils.return_caching_utils import _check_and_return_cached_result
|
|
13
14
|
from ..vectorizer.factory import get_vectorizer
|
|
14
15
|
from ..utils.context import execution_source_context
|
|
16
|
+
from ..utils.path_utils import get_repo_root_and_relative_path # New import
|
|
15
17
|
|
|
16
18
|
logger = logging.getLogger(__name__)
|
|
17
19
|
|
|
@@ -102,8 +104,22 @@ def vectorize(search_description: Optional[str] = None,
|
|
|
102
104
|
docstring = inspect.getdoc(func) or ""
|
|
103
105
|
source_code = inspect.getsource(func)
|
|
104
106
|
|
|
107
|
+
try:
|
|
108
|
+
abs_file_path = os.path.abspath(inspect.getsourcefile(func))
|
|
109
|
+
repo_root, relative_file_path = get_repo_root_and_relative_path(abs_file_path)
|
|
110
|
+
if relative_file_path:
|
|
111
|
+
file_path = relative_file_path
|
|
112
|
+
else:
|
|
113
|
+
file_path = abs_file_path # Fallback to absolute path if not in a git repo
|
|
114
|
+
logger.warning(f"Function '{function_name}' is not in a Git repository. "
|
|
115
|
+
f"PR creation might fail for absolute path: {file_path}")
|
|
116
|
+
except Exception as e:
|
|
117
|
+
file_path = ""
|
|
118
|
+
logger.error(f"Failed to determine file path for '{function_name}': {e}")
|
|
119
|
+
|
|
105
120
|
static_properties = {
|
|
106
121
|
"function_name": function_name,
|
|
122
|
+
"file_path": file_path,
|
|
107
123
|
"module_name": module_name,
|
|
108
124
|
"docstring": docstring,
|
|
109
125
|
"source_code": source_code,
|
|
@@ -100,6 +100,7 @@ def create_vectorwave_schema(client: weaviate.WeaviateClient, settings: Weaviate
|
|
|
100
100
|
wvc.Property(name="source_code", data_type=wvc.DataType.TEXT),
|
|
101
101
|
wvc.Property(name="search_description", data_type=wvc.DataType.TEXT),
|
|
102
102
|
wvc.Property(name="sequence_narrative", data_type=wvc.DataType.TEXT),
|
|
103
|
+
wvc.Property(name="file_path",data_type=wvc.DataType.TEXT),
|
|
103
104
|
]
|
|
104
105
|
|
|
105
106
|
custom_properties = []
|
|
@@ -41,11 +41,18 @@ class WeaviateSettings(BaseSettings):
|
|
|
41
41
|
|
|
42
42
|
CUSTOM_PROPERTIES_FILE_PATH: str = ".weaviate_properties"
|
|
43
43
|
FAILURE_MAPPING_FILE_PATH: str = ".vectorwave_errors.json"
|
|
44
|
+
IGNORE_ERROR_FILE_PATH: str = ".vtwignore"
|
|
45
|
+
|
|
46
|
+
GITHUB_TOKEN: Optional[str] = None
|
|
47
|
+
GITHUB_REPO_NAME: Optional[str] = None
|
|
48
|
+
GITHUB_BASE_BRANCH: str = "main"
|
|
44
49
|
|
|
45
50
|
custom_properties: Optional[Dict[str, Dict[str, Any]]] = None
|
|
46
51
|
global_custom_values: Optional[Dict[str, Any]] = None
|
|
47
52
|
failure_mapping: Optional[Dict[str, str]] = None
|
|
48
53
|
|
|
54
|
+
ignored_error_codes: Set[str] = set()
|
|
55
|
+
|
|
49
56
|
ALERTER_STRATEGY: str = "none"
|
|
50
57
|
ALERTER_WEBHOOK_URL: Optional[str] = None
|
|
51
58
|
ALERTER_MIN_LEVEL: str = "ERROR"
|
|
@@ -128,6 +135,17 @@ def get_weaviate_settings() -> WeaviateSettings:
|
|
|
128
135
|
elif error_file_path:
|
|
129
136
|
logger.info(f"Note: Failure mapping file not found at '{error_file_path}'. Skipping.")
|
|
130
137
|
|
|
138
|
+
ignore_file_path = settings.IGNORE_ERROR_FILE_PATH
|
|
139
|
+
if ignore_file_path and os.path.exists(ignore_file_path):
|
|
140
|
+
logger.info(f"Loading ignore error codes from '{ignore_file_path}'...")
|
|
141
|
+
try:
|
|
142
|
+
with open(ignore_file_path, 'r', encoding='utf-8') as f:
|
|
143
|
+
codes = {line.strip() for line in f if line.strip() and not line.startswith('#')}
|
|
144
|
+
settings.ignored_error_codes = codes
|
|
145
|
+
logger.info(f"Loaded {len(codes)} ignored error codes.")
|
|
146
|
+
except Exception as e:
|
|
147
|
+
logger.warning(f"Could not read '{ignore_file_path}': {e}")
|
|
148
|
+
|
|
131
149
|
try:
|
|
132
150
|
settings.sensitive_keys = {
|
|
133
151
|
key.strip().lower()
|
|
@@ -289,9 +289,15 @@ def trace_span(
|
|
|
289
289
|
return_value_log = str(processed_result)
|
|
290
290
|
|
|
291
291
|
except Exception as e:
|
|
292
|
-
status = "ERROR"
|
|
293
292
|
error_msg = traceback.format_exc()
|
|
294
293
|
error_code = _determine_error_code(tracer, e)
|
|
294
|
+
|
|
295
|
+
if error_code in tracer.settings.ignored_error_codes:
|
|
296
|
+
status = "FAILURE"
|
|
297
|
+
tracer.alert_sent = True
|
|
298
|
+
else:
|
|
299
|
+
status = "ERROR"
|
|
300
|
+
|
|
295
301
|
span_properties = _create_span_properties(
|
|
296
302
|
tracer, func, start_time, status, error_msg, error_code, captured_attributes,
|
|
297
303
|
my_span_id=my_span_id, parent_span_id=parent_span_id,
|
|
@@ -401,9 +407,15 @@ def trace_span(
|
|
|
401
407
|
return_value_log = str(processed_result)
|
|
402
408
|
|
|
403
409
|
except Exception as e:
|
|
404
|
-
status = "ERROR"
|
|
405
410
|
error_msg = traceback.format_exc()
|
|
406
411
|
error_code = _determine_error_code(tracer, e)
|
|
412
|
+
|
|
413
|
+
if error_code in tracer.settings.ignored_error_codes:
|
|
414
|
+
status = "FAILURE"
|
|
415
|
+
tracer.alert_sent = True
|
|
416
|
+
else:
|
|
417
|
+
status = "ERROR"
|
|
418
|
+
|
|
407
419
|
span_properties = _create_span_properties(
|
|
408
420
|
tracer, func, start_time, status, error_msg, error_code, captured_attributes,
|
|
409
421
|
my_span_id=my_span_id, parent_span_id=parent_span_id,
|