waveflowdb-client 0.0.1__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.
- waveflowdb_client-0.0.1/LICENSE +21 -0
- waveflowdb_client-0.0.1/PKG-INFO +201 -0
- waveflowdb_client-0.0.1/pyproject.toml +27 -0
- waveflowdb_client-0.0.1/readme.md +163 -0
- waveflowdb_client-0.0.1/setup.cfg +4 -0
- waveflowdb_client-0.0.1/starter.py +195 -0
- waveflowdb_client-0.0.1/waveflowdb_client.egg-info/PKG-INFO +201 -0
- waveflowdb_client-0.0.1/waveflowdb_client.egg-info/SOURCES.txt +9 -0
- waveflowdb_client-0.0.1/waveflowdb_client.egg-info/dependency_links.txt +1 -0
- waveflowdb_client-0.0.1/waveflowdb_client.egg-info/requires.txt +3 -0
- waveflowdb_client-0.0.1/waveflowdb_client.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 agentanalytics.ai
|
|
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.
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: waveflowdb-client
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: VectorLake SDK โ Deterministic backend engine powering agent workflows
|
|
5
|
+
Author-email: "agentanalytics.ai" <nitin@agentanalytics.ai>
|
|
6
|
+
License: MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2025 agentanalytics.ai
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
27
|
+
|
|
28
|
+
Project-URL: Homepage, https://agentanalytics.ai
|
|
29
|
+
Project-URL: Documentation, https://www.agentanalytics.ai/docs/waveflow-db
|
|
30
|
+
Keywords: vector db,VECTOR QUERY LANGUAGE,waveflow,agentanalytics,VQL
|
|
31
|
+
Requires-Python: >=3.8
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
License-File: LICENSE
|
|
34
|
+
Requires-Dist: requests
|
|
35
|
+
Requires-Dist: numpy
|
|
36
|
+
Requires-Dist: tqdm
|
|
37
|
+
Dynamic: license-file
|
|
38
|
+
|
|
39
|
+
# WaveflowDB SDK Starter
|
|
40
|
+
|
|
41
|
+
A lightweight launcher script for interacting with **WaveflowDB** and
|
|
42
|
+
performing **WaveQL (VQL) brace-based semantic retrieval**.
|
|
43
|
+
|
|
44
|
+
This starter project demonstrates how to:
|
|
45
|
+
|
|
46
|
+
- Configure and initialize a Vector Lake client\
|
|
47
|
+
- Ingest documents (direct or path-based)\
|
|
48
|
+
- Refresh documents\
|
|
49
|
+
- Run semantic chat (static + dynamic)\
|
|
50
|
+
- Retrieve matching documents\
|
|
51
|
+
- Query namespaces\
|
|
52
|
+
- Use WaveQL-style logical filtering for agentic retrieval
|
|
53
|
+
|
|
54
|
+
------------------------------------------------------------------------
|
|
55
|
+
|
|
56
|
+
## ๐ Overview
|
|
57
|
+
|
|
58
|
+
Vector Lake is an unstructured semantic data platform enabling:
|
|
59
|
+
|
|
60
|
+
- Natural-language structured filtering through **WaveQL (VQL)**
|
|
61
|
+
- Hybrid ranking (Filter + Semantic)
|
|
62
|
+
- Zero-schema ingestion (no JSON schemas required)
|
|
63
|
+
- SQL-like logical joins on raw text
|
|
64
|
+
- Automatic semantic fallback when filters fail
|
|
65
|
+
|
|
66
|
+
The included `starter.py` file provides ready-to-run function wrappers
|
|
67
|
+
to interact with the Vector Lake API.
|
|
68
|
+
|
|
69
|
+
------------------------------------------------------------------------
|
|
70
|
+
|
|
71
|
+
## ๐ Getting Started
|
|
72
|
+
|
|
73
|
+
### 1. Install Dependencies
|
|
74
|
+
|
|
75
|
+
``` bash
|
|
76
|
+
pip install waveflowdb-client
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### 2. Configure API Credentials
|
|
80
|
+
|
|
81
|
+
Edit the top section of `starter.py`:
|
|
82
|
+
|
|
83
|
+
``` python
|
|
84
|
+
API_KEY = "<<>>"
|
|
85
|
+
HOST = "https://waveflow-analytics.com"
|
|
86
|
+
VECTOR_LAKE_PATH = "<<>>"
|
|
87
|
+
USER_ID = ""
|
|
88
|
+
NAMESPACE = ""
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
------------------------------------------------------------------------
|
|
92
|
+
|
|
93
|
+
## ๐ง Using WaveQL (VQL) Queries
|
|
94
|
+
|
|
95
|
+
WaveQL enables natural language filtering using **brace-based logical
|
|
96
|
+
groups**:
|
|
97
|
+
|
|
98
|
+
{clinical trials or observational studies} {type 2 diabetes} {India}
|
|
99
|
+
|
|
100
|
+
### Key Rules
|
|
101
|
+
|
|
102
|
+
โ Each `{}` is a logical filter group\
|
|
103
|
+
โ Groups combine with implicit AND\
|
|
104
|
+
โ Use `AND`, `OR`, `()` inside braces\
|
|
105
|
+
โ Multi-word phrases **must** use parentheses when operators are used
|
|
106
|
+
|
|
107
|
+
Examples:
|
|
108
|
+
|
|
109
|
+
-------------------------------------------------------------------------------------
|
|
110
|
+
Correct Incorrect
|
|
111
|
+
------------------------------------------- -----------------------------------------
|
|
112
|
+
`{(machine learning) or (deep learning)}` `{machine learning or deep learning}`
|
|
113
|
+
|
|
114
|
+
`{(product manager) or (data scientist)}` `{product manager or Delhi}`
|
|
115
|
+
-------------------------------------------------------------------------------------
|
|
116
|
+
|
|
117
|
+
WaveQL supports **three-tier hybrid ranking**:
|
|
118
|
+
|
|
119
|
+
1. Tier 1 -- Filter + Semantic match (best)\
|
|
120
|
+
2. Tier 2 -- Filter-only match\
|
|
121
|
+
3. Tier 3 -- Semantic-only fallback
|
|
122
|
+
|
|
123
|
+
------------------------------------------------------------------------
|
|
124
|
+
|
|
125
|
+
## ๐งช Using the Starter Script
|
|
126
|
+
|
|
127
|
+
The script exposes multiple ready-to-run functions.
|
|
128
|
+
|
|
129
|
+
### Run Health Check
|
|
130
|
+
|
|
131
|
+
``` python
|
|
132
|
+
run_health()
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Add Documents
|
|
136
|
+
|
|
137
|
+
``` python
|
|
138
|
+
run_add_direct()
|
|
139
|
+
run_add_path()
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Refresh Documents
|
|
143
|
+
|
|
144
|
+
``` python
|
|
145
|
+
run_refresh_direct()
|
|
146
|
+
run_refresh_path()
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Chat With Documents
|
|
150
|
+
|
|
151
|
+
``` python
|
|
152
|
+
run_chat_static("your question")
|
|
153
|
+
run_chat_dynamic("summarize this")
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Retrieve Matching Documents
|
|
157
|
+
|
|
158
|
+
``` python
|
|
159
|
+
run_match_static("your query")
|
|
160
|
+
run_match_dynamic("your query")
|
|
161
|
+
run_match_with_data("your query")
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Namespace & Document Inspection
|
|
165
|
+
|
|
166
|
+
``` python
|
|
167
|
+
run_namespace_details()
|
|
168
|
+
run_docs_info()
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
------------------------------------------------------------------------
|
|
172
|
+
|
|
173
|
+
## ๐งฉ Example WaveQL Queries
|
|
174
|
+
|
|
175
|
+
- `{diabetes} {(clinical trial)} {India}`
|
|
176
|
+
- `{(product manager)} {Python} {Delhi}`
|
|
177
|
+
- `{genomics} {cancer}`
|
|
178
|
+
- `{(supply chain)} {pharma}`
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
## ๐ Tips & Best Practices
|
|
182
|
+
|
|
183
|
+
### Do:
|
|
184
|
+
|
|
185
|
+
- Use 1--2 keywords per brace\
|
|
186
|
+
- Wrap multi-word phrases in `()` when using OR/AND\
|
|
187
|
+
- Keep groups domain-consistent
|
|
188
|
+
|
|
189
|
+
### Don't:
|
|
190
|
+
|
|
191
|
+
- Use long multi-word phrases\
|
|
192
|
+
- Mix unrelated domains\
|
|
193
|
+
- Forget parentheses for multi-word logic
|
|
194
|
+
|
|
195
|
+
------------------------------------------------------------------------
|
|
196
|
+
|
|
197
|
+
## ๐ง Support
|
|
198
|
+
|
|
199
|
+
For API or platform support, visit:
|
|
200
|
+
|
|
201
|
+
**https://db.agentanalytics.ai**
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "waveflowdb-client" # pip install name
|
|
7
|
+
version = "0.0.1"
|
|
8
|
+
description = "VectorLake SDK โ Deterministic backend engine powering agent workflows"
|
|
9
|
+
readme = "readme.md"
|
|
10
|
+
requires-python = ">=3.8"
|
|
11
|
+
license = {file = "LICENSE"}
|
|
12
|
+
|
|
13
|
+
authors = [
|
|
14
|
+
{ name = "agentanalytics.ai", email = "nitin@agentanalytics.ai" }
|
|
15
|
+
]
|
|
16
|
+
|
|
17
|
+
keywords = ["vector db", "VECTOR QUERY LANGUAGE", "waveflow", "agentanalytics", "VQL"]
|
|
18
|
+
|
|
19
|
+
dependencies = [
|
|
20
|
+
"requests",
|
|
21
|
+
"numpy",
|
|
22
|
+
"tqdm",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
[project.urls]
|
|
26
|
+
Homepage = "https://agentanalytics.ai"
|
|
27
|
+
Documentation = "https://www.agentanalytics.ai/docs/waveflow-db"
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# WaveflowDB SDK Starter
|
|
2
|
+
|
|
3
|
+
A lightweight launcher script for interacting with **WaveflowDB** and
|
|
4
|
+
performing **WaveQL (VQL) brace-based semantic retrieval**.
|
|
5
|
+
|
|
6
|
+
This starter project demonstrates how to:
|
|
7
|
+
|
|
8
|
+
- Configure and initialize a Vector Lake client\
|
|
9
|
+
- Ingest documents (direct or path-based)\
|
|
10
|
+
- Refresh documents\
|
|
11
|
+
- Run semantic chat (static + dynamic)\
|
|
12
|
+
- Retrieve matching documents\
|
|
13
|
+
- Query namespaces\
|
|
14
|
+
- Use WaveQL-style logical filtering for agentic retrieval
|
|
15
|
+
|
|
16
|
+
------------------------------------------------------------------------
|
|
17
|
+
|
|
18
|
+
## ๐ Overview
|
|
19
|
+
|
|
20
|
+
Vector Lake is an unstructured semantic data platform enabling:
|
|
21
|
+
|
|
22
|
+
- Natural-language structured filtering through **WaveQL (VQL)**
|
|
23
|
+
- Hybrid ranking (Filter + Semantic)
|
|
24
|
+
- Zero-schema ingestion (no JSON schemas required)
|
|
25
|
+
- SQL-like logical joins on raw text
|
|
26
|
+
- Automatic semantic fallback when filters fail
|
|
27
|
+
|
|
28
|
+
The included `starter.py` file provides ready-to-run function wrappers
|
|
29
|
+
to interact with the Vector Lake API.
|
|
30
|
+
|
|
31
|
+
------------------------------------------------------------------------
|
|
32
|
+
|
|
33
|
+
## ๐ Getting Started
|
|
34
|
+
|
|
35
|
+
### 1. Install Dependencies
|
|
36
|
+
|
|
37
|
+
``` bash
|
|
38
|
+
pip install waveflowdb-client
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### 2. Configure API Credentials
|
|
42
|
+
|
|
43
|
+
Edit the top section of `starter.py`:
|
|
44
|
+
|
|
45
|
+
``` python
|
|
46
|
+
API_KEY = "<<>>"
|
|
47
|
+
HOST = "https://waveflow-analytics.com"
|
|
48
|
+
VECTOR_LAKE_PATH = "<<>>"
|
|
49
|
+
USER_ID = ""
|
|
50
|
+
NAMESPACE = ""
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
------------------------------------------------------------------------
|
|
54
|
+
|
|
55
|
+
## ๐ง Using WaveQL (VQL) Queries
|
|
56
|
+
|
|
57
|
+
WaveQL enables natural language filtering using **brace-based logical
|
|
58
|
+
groups**:
|
|
59
|
+
|
|
60
|
+
{clinical trials or observational studies} {type 2 diabetes} {India}
|
|
61
|
+
|
|
62
|
+
### Key Rules
|
|
63
|
+
|
|
64
|
+
โ Each `{}` is a logical filter group\
|
|
65
|
+
โ Groups combine with implicit AND\
|
|
66
|
+
โ Use `AND`, `OR`, `()` inside braces\
|
|
67
|
+
โ Multi-word phrases **must** use parentheses when operators are used
|
|
68
|
+
|
|
69
|
+
Examples:
|
|
70
|
+
|
|
71
|
+
-------------------------------------------------------------------------------------
|
|
72
|
+
Correct Incorrect
|
|
73
|
+
------------------------------------------- -----------------------------------------
|
|
74
|
+
`{(machine learning) or (deep learning)}` `{machine learning or deep learning}`
|
|
75
|
+
|
|
76
|
+
`{(product manager) or (data scientist)}` `{product manager or Delhi}`
|
|
77
|
+
-------------------------------------------------------------------------------------
|
|
78
|
+
|
|
79
|
+
WaveQL supports **three-tier hybrid ranking**:
|
|
80
|
+
|
|
81
|
+
1. Tier 1 -- Filter + Semantic match (best)\
|
|
82
|
+
2. Tier 2 -- Filter-only match\
|
|
83
|
+
3. Tier 3 -- Semantic-only fallback
|
|
84
|
+
|
|
85
|
+
------------------------------------------------------------------------
|
|
86
|
+
|
|
87
|
+
## ๐งช Using the Starter Script
|
|
88
|
+
|
|
89
|
+
The script exposes multiple ready-to-run functions.
|
|
90
|
+
|
|
91
|
+
### Run Health Check
|
|
92
|
+
|
|
93
|
+
``` python
|
|
94
|
+
run_health()
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Add Documents
|
|
98
|
+
|
|
99
|
+
``` python
|
|
100
|
+
run_add_direct()
|
|
101
|
+
run_add_path()
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### Refresh Documents
|
|
105
|
+
|
|
106
|
+
``` python
|
|
107
|
+
run_refresh_direct()
|
|
108
|
+
run_refresh_path()
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Chat With Documents
|
|
112
|
+
|
|
113
|
+
``` python
|
|
114
|
+
run_chat_static("your question")
|
|
115
|
+
run_chat_dynamic("summarize this")
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Retrieve Matching Documents
|
|
119
|
+
|
|
120
|
+
``` python
|
|
121
|
+
run_match_static("your query")
|
|
122
|
+
run_match_dynamic("your query")
|
|
123
|
+
run_match_with_data("your query")
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Namespace & Document Inspection
|
|
127
|
+
|
|
128
|
+
``` python
|
|
129
|
+
run_namespace_details()
|
|
130
|
+
run_docs_info()
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
------------------------------------------------------------------------
|
|
134
|
+
|
|
135
|
+
## ๐งฉ Example WaveQL Queries
|
|
136
|
+
|
|
137
|
+
- `{diabetes} {(clinical trial)} {India}`
|
|
138
|
+
- `{(product manager)} {Python} {Delhi}`
|
|
139
|
+
- `{genomics} {cancer}`
|
|
140
|
+
- `{(supply chain)} {pharma}`
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
## ๐ Tips & Best Practices
|
|
144
|
+
|
|
145
|
+
### Do:
|
|
146
|
+
|
|
147
|
+
- Use 1--2 keywords per brace\
|
|
148
|
+
- Wrap multi-word phrases in `()` when using OR/AND\
|
|
149
|
+
- Keep groups domain-consistent
|
|
150
|
+
|
|
151
|
+
### Don't:
|
|
152
|
+
|
|
153
|
+
- Use long multi-word phrases\
|
|
154
|
+
- Mix unrelated domains\
|
|
155
|
+
- Forget parentheses for multi-word logic
|
|
156
|
+
|
|
157
|
+
------------------------------------------------------------------------
|
|
158
|
+
|
|
159
|
+
## ๐ง Support
|
|
160
|
+
|
|
161
|
+
For API or platform support, visit:
|
|
162
|
+
|
|
163
|
+
**https://db.agentanalytics.ai**
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
"""
|
|
2
|
+
run.py
|
|
3
|
+
Simple launcher for Vector Lake SDK (v1.0.0)
|
|
4
|
+
|
|
5
|
+
Allows you to:
|
|
6
|
+
- configure client (host, port, key)
|
|
7
|
+
- call ANY API: add, refresh, chat, match, health, namespace info, etc.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from waveflowdb-client import Config, VectorLakeClient
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
# -------------------------------------------------------
|
|
14
|
+
# CONFIGURATION (EDIT THIS ONCE)
|
|
15
|
+
# -------------------------------------------------------
|
|
16
|
+
API_KEY = "<<>>" # visit https://db.agentanalytics.ai/signup
|
|
17
|
+
HOST = "https://waveflow-analytics.com" # OR "http://localhost"
|
|
18
|
+
VECTOR_LAKE_PATH = "<<>>" # folder for path-based ingestion
|
|
19
|
+
USER_ID = "" ## your email id used for registratoin
|
|
20
|
+
NAMESPACE = "" ## database created via UI
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
# -------------------------------------------------------
|
|
24
|
+
# INITIALIZE CLIENT
|
|
25
|
+
# -------------------------------------------------------
|
|
26
|
+
def get_client():
|
|
27
|
+
cfg = Config(
|
|
28
|
+
api_key=API_KEY,
|
|
29
|
+
host=HOST,
|
|
30
|
+
vector_lake_path=VECTOR_LAKE_PATH
|
|
31
|
+
)
|
|
32
|
+
return VectorLakeClient(cfg)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
client = get_client()
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
# -------------------------------------------------------
|
|
39
|
+
# READY-TO-USE ACTION FUNCTIONS
|
|
40
|
+
# -------------------------------------------------------
|
|
41
|
+
|
|
42
|
+
def run_health():
|
|
43
|
+
"""Health check"""
|
|
44
|
+
print("\n--- HEALTH CHECK ---")
|
|
45
|
+
res = client.health_check(USER_ID, NAMESPACE)
|
|
46
|
+
print(res)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def run_add_direct():
|
|
50
|
+
"""Add docs using files_name + files_data"""
|
|
51
|
+
print("\n--- ADD DOCUMENTS (Direct Payload Mode) ---")
|
|
52
|
+
res = client.add_documents(
|
|
53
|
+
user_id=USER_ID,
|
|
54
|
+
vector_lake_description=NAMESPACE,
|
|
55
|
+
files_name=["test1.txt", "test2.txt"],
|
|
56
|
+
files_data=["hello world", "this is test doc 2"]
|
|
57
|
+
)
|
|
58
|
+
print(res)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def run_add_path():
|
|
62
|
+
"""Add docs by reading actual files from disk"""
|
|
63
|
+
print("\n--- ADD DOCUMENTS (Disk Path Mode) ---")
|
|
64
|
+
res = client.add_documents(
|
|
65
|
+
user_id=USER_ID,
|
|
66
|
+
vector_lake_description=NAMESPACE
|
|
67
|
+
# files=[""] # must exist inside VECTOR_LAKE_PATH
|
|
68
|
+
)
|
|
69
|
+
print(res)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def run_refresh_direct():
|
|
73
|
+
"""Refresh docs using direct data (no disk read)"""
|
|
74
|
+
print("\n--- REFRESH DOCUMENTS (Direct Data Mode) ---")
|
|
75
|
+
res = client.refresh_documents(
|
|
76
|
+
user_id=USER_ID,
|
|
77
|
+
vector_lake_description=NAMESPACE,
|
|
78
|
+
files_name=["test1.txt"],
|
|
79
|
+
files_data=["UPDATED CONTENT FOR TEST1"]
|
|
80
|
+
)
|
|
81
|
+
print(res)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def run_refresh_path():
|
|
85
|
+
"""Refresh docs by reading actual files"""
|
|
86
|
+
print("\n--- REFRESH DOCUMENTS (Path Mode) ---")
|
|
87
|
+
res = client.refresh_documents(
|
|
88
|
+
user_id=USER_ID,
|
|
89
|
+
vector_lake_description=NAMESPACE
|
|
90
|
+
# files=["file1.pdf"] # must exist
|
|
91
|
+
)
|
|
92
|
+
print(res)
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def run_chat_static(query):
|
|
96
|
+
"""Chat with stored index"""
|
|
97
|
+
print("\n--- CHAT (STATIC MODE) ---")
|
|
98
|
+
res = client.chat_with_docs(
|
|
99
|
+
query=query,
|
|
100
|
+
user_id=USER_ID,
|
|
101
|
+
vector_lake_description=NAMESPACE,
|
|
102
|
+
pattern="static"
|
|
103
|
+
)
|
|
104
|
+
print(res)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def run_chat_dynamic(query):
|
|
108
|
+
"""Chat using temporary files (dynamic mode)"""
|
|
109
|
+
print("\n--- CHAT (DYNAMIC MODE) ---")
|
|
110
|
+
res = client.chat_with_docs(
|
|
111
|
+
query=query,
|
|
112
|
+
user_id=USER_ID,
|
|
113
|
+
vector_lake_description=NAMESPACE,
|
|
114
|
+
pattern="dynamic",
|
|
115
|
+
files_name=["dyn1.txt"],
|
|
116
|
+
files_data=["This is dynamic content to summarize."]
|
|
117
|
+
)
|
|
118
|
+
print(res)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def run_match_static(query):
|
|
122
|
+
"""Top matching docs (static mode)"""
|
|
123
|
+
print("\n--- TOP MATCHING DOCS (STATIC) ---")
|
|
124
|
+
res = client.get_matching_docs(
|
|
125
|
+
query=query,
|
|
126
|
+
user_id=USER_ID,
|
|
127
|
+
vector_lake_description=NAMESPACE,
|
|
128
|
+
pattern="static",
|
|
129
|
+
top_docs=5,
|
|
130
|
+
threshold=0.1
|
|
131
|
+
)
|
|
132
|
+
print(res)
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def run_match_dynamic(query):
|
|
136
|
+
"""Top matching docs (dynamic mode)"""
|
|
137
|
+
print("\n--- TOP MATCHING DOCS (DYNAMIC) ---")
|
|
138
|
+
res = client.get_matching_docs(
|
|
139
|
+
query=query,
|
|
140
|
+
user_id=USER_ID,
|
|
141
|
+
vector_lake_description=NAMESPACE,
|
|
142
|
+
pattern="dynamic",
|
|
143
|
+
files_name=["temp.txt"],
|
|
144
|
+
files_data=["Sample dynamic content"]
|
|
145
|
+
)
|
|
146
|
+
print(res)
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def run_match_with_data(query):
|
|
150
|
+
"""Top matching docs including chunk data"""
|
|
151
|
+
print("\n--- TOP MATCHING DOCS (WITH DATA) ---")
|
|
152
|
+
res = client.get_matching_docs(
|
|
153
|
+
query=query,
|
|
154
|
+
user_id=USER_ID,
|
|
155
|
+
vector_lake_description=NAMESPACE,
|
|
156
|
+
pattern="static",
|
|
157
|
+
top_docs=5,
|
|
158
|
+
with_data=True
|
|
159
|
+
)
|
|
160
|
+
print(res)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def run_namespace_details():
|
|
164
|
+
"""Get namespace information"""
|
|
165
|
+
print("\n--- GET NAMESPACE DETAILS ---")
|
|
166
|
+
res = client.get_namespace_details(USER_ID, vector_lake_description=NAMESPACE)
|
|
167
|
+
print(res)
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def run_docs_info():
|
|
171
|
+
"""List all stored docs + info"""
|
|
172
|
+
print("\n--- GET DOCS INFORMATION ---")
|
|
173
|
+
res = client.get_docs_information(USER_ID, NAMESPACE)
|
|
174
|
+
print(res)
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
# -------------------------------------------------------
|
|
178
|
+
# MAIN SELECTOR โ RUN ANY FUNCTION YOU WANT
|
|
179
|
+
# -------------------------------------------------------
|
|
180
|
+
if __name__ == "__main__":
|
|
181
|
+
query="<<>>"
|
|
182
|
+
# --- UNCOMMENT ANY ONE OF THESE TO RUN THAT OPERATION ---
|
|
183
|
+
# run_health()
|
|
184
|
+
# run_add_direct()
|
|
185
|
+
# run_add_path()
|
|
186
|
+
# run_refresh_direct()
|
|
187
|
+
# run_refresh_path()
|
|
188
|
+
# run_chat_static(query)
|
|
189
|
+
# run_chat_dynamic(query)
|
|
190
|
+
# run_match_static(query)
|
|
191
|
+
# run_match_dynamic(query)
|
|
192
|
+
# run_match_with_data(query)
|
|
193
|
+
run_namespace_details()
|
|
194
|
+
# run_docs_info()
|
|
195
|
+
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: waveflowdb-client
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: VectorLake SDK โ Deterministic backend engine powering agent workflows
|
|
5
|
+
Author-email: "agentanalytics.ai" <nitin@agentanalytics.ai>
|
|
6
|
+
License: MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2025 agentanalytics.ai
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
27
|
+
|
|
28
|
+
Project-URL: Homepage, https://agentanalytics.ai
|
|
29
|
+
Project-URL: Documentation, https://www.agentanalytics.ai/docs/waveflow-db
|
|
30
|
+
Keywords: vector db,VECTOR QUERY LANGUAGE,waveflow,agentanalytics,VQL
|
|
31
|
+
Requires-Python: >=3.8
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
License-File: LICENSE
|
|
34
|
+
Requires-Dist: requests
|
|
35
|
+
Requires-Dist: numpy
|
|
36
|
+
Requires-Dist: tqdm
|
|
37
|
+
Dynamic: license-file
|
|
38
|
+
|
|
39
|
+
# WaveflowDB SDK Starter
|
|
40
|
+
|
|
41
|
+
A lightweight launcher script for interacting with **WaveflowDB** and
|
|
42
|
+
performing **WaveQL (VQL) brace-based semantic retrieval**.
|
|
43
|
+
|
|
44
|
+
This starter project demonstrates how to:
|
|
45
|
+
|
|
46
|
+
- Configure and initialize a Vector Lake client\
|
|
47
|
+
- Ingest documents (direct or path-based)\
|
|
48
|
+
- Refresh documents\
|
|
49
|
+
- Run semantic chat (static + dynamic)\
|
|
50
|
+
- Retrieve matching documents\
|
|
51
|
+
- Query namespaces\
|
|
52
|
+
- Use WaveQL-style logical filtering for agentic retrieval
|
|
53
|
+
|
|
54
|
+
------------------------------------------------------------------------
|
|
55
|
+
|
|
56
|
+
## ๐ Overview
|
|
57
|
+
|
|
58
|
+
Vector Lake is an unstructured semantic data platform enabling:
|
|
59
|
+
|
|
60
|
+
- Natural-language structured filtering through **WaveQL (VQL)**
|
|
61
|
+
- Hybrid ranking (Filter + Semantic)
|
|
62
|
+
- Zero-schema ingestion (no JSON schemas required)
|
|
63
|
+
- SQL-like logical joins on raw text
|
|
64
|
+
- Automatic semantic fallback when filters fail
|
|
65
|
+
|
|
66
|
+
The included `starter.py` file provides ready-to-run function wrappers
|
|
67
|
+
to interact with the Vector Lake API.
|
|
68
|
+
|
|
69
|
+
------------------------------------------------------------------------
|
|
70
|
+
|
|
71
|
+
## ๐ Getting Started
|
|
72
|
+
|
|
73
|
+
### 1. Install Dependencies
|
|
74
|
+
|
|
75
|
+
``` bash
|
|
76
|
+
pip install waveflowdb-client
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### 2. Configure API Credentials
|
|
80
|
+
|
|
81
|
+
Edit the top section of `starter.py`:
|
|
82
|
+
|
|
83
|
+
``` python
|
|
84
|
+
API_KEY = "<<>>"
|
|
85
|
+
HOST = "https://waveflow-analytics.com"
|
|
86
|
+
VECTOR_LAKE_PATH = "<<>>"
|
|
87
|
+
USER_ID = ""
|
|
88
|
+
NAMESPACE = ""
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
------------------------------------------------------------------------
|
|
92
|
+
|
|
93
|
+
## ๐ง Using WaveQL (VQL) Queries
|
|
94
|
+
|
|
95
|
+
WaveQL enables natural language filtering using **brace-based logical
|
|
96
|
+
groups**:
|
|
97
|
+
|
|
98
|
+
{clinical trials or observational studies} {type 2 diabetes} {India}
|
|
99
|
+
|
|
100
|
+
### Key Rules
|
|
101
|
+
|
|
102
|
+
โ Each `{}` is a logical filter group\
|
|
103
|
+
โ Groups combine with implicit AND\
|
|
104
|
+
โ Use `AND`, `OR`, `()` inside braces\
|
|
105
|
+
โ Multi-word phrases **must** use parentheses when operators are used
|
|
106
|
+
|
|
107
|
+
Examples:
|
|
108
|
+
|
|
109
|
+
-------------------------------------------------------------------------------------
|
|
110
|
+
Correct Incorrect
|
|
111
|
+
------------------------------------------- -----------------------------------------
|
|
112
|
+
`{(machine learning) or (deep learning)}` `{machine learning or deep learning}`
|
|
113
|
+
|
|
114
|
+
`{(product manager) or (data scientist)}` `{product manager or Delhi}`
|
|
115
|
+
-------------------------------------------------------------------------------------
|
|
116
|
+
|
|
117
|
+
WaveQL supports **three-tier hybrid ranking**:
|
|
118
|
+
|
|
119
|
+
1. Tier 1 -- Filter + Semantic match (best)\
|
|
120
|
+
2. Tier 2 -- Filter-only match\
|
|
121
|
+
3. Tier 3 -- Semantic-only fallback
|
|
122
|
+
|
|
123
|
+
------------------------------------------------------------------------
|
|
124
|
+
|
|
125
|
+
## ๐งช Using the Starter Script
|
|
126
|
+
|
|
127
|
+
The script exposes multiple ready-to-run functions.
|
|
128
|
+
|
|
129
|
+
### Run Health Check
|
|
130
|
+
|
|
131
|
+
``` python
|
|
132
|
+
run_health()
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Add Documents
|
|
136
|
+
|
|
137
|
+
``` python
|
|
138
|
+
run_add_direct()
|
|
139
|
+
run_add_path()
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Refresh Documents
|
|
143
|
+
|
|
144
|
+
``` python
|
|
145
|
+
run_refresh_direct()
|
|
146
|
+
run_refresh_path()
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Chat With Documents
|
|
150
|
+
|
|
151
|
+
``` python
|
|
152
|
+
run_chat_static("your question")
|
|
153
|
+
run_chat_dynamic("summarize this")
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Retrieve Matching Documents
|
|
157
|
+
|
|
158
|
+
``` python
|
|
159
|
+
run_match_static("your query")
|
|
160
|
+
run_match_dynamic("your query")
|
|
161
|
+
run_match_with_data("your query")
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Namespace & Document Inspection
|
|
165
|
+
|
|
166
|
+
``` python
|
|
167
|
+
run_namespace_details()
|
|
168
|
+
run_docs_info()
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
------------------------------------------------------------------------
|
|
172
|
+
|
|
173
|
+
## ๐งฉ Example WaveQL Queries
|
|
174
|
+
|
|
175
|
+
- `{diabetes} {(clinical trial)} {India}`
|
|
176
|
+
- `{(product manager)} {Python} {Delhi}`
|
|
177
|
+
- `{genomics} {cancer}`
|
|
178
|
+
- `{(supply chain)} {pharma}`
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
## ๐ Tips & Best Practices
|
|
182
|
+
|
|
183
|
+
### Do:
|
|
184
|
+
|
|
185
|
+
- Use 1--2 keywords per brace\
|
|
186
|
+
- Wrap multi-word phrases in `()` when using OR/AND\
|
|
187
|
+
- Keep groups domain-consistent
|
|
188
|
+
|
|
189
|
+
### Don't:
|
|
190
|
+
|
|
191
|
+
- Use long multi-word phrases\
|
|
192
|
+
- Mix unrelated domains\
|
|
193
|
+
- Forget parentheses for multi-word logic
|
|
194
|
+
|
|
195
|
+
------------------------------------------------------------------------
|
|
196
|
+
|
|
197
|
+
## ๐ง Support
|
|
198
|
+
|
|
199
|
+
For API or platform support, visit:
|
|
200
|
+
|
|
201
|
+
**https://db.agentanalytics.ai**
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
starter
|