gigaevo-client 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- gigaevo_client-0.3.0/.gitignore +17 -0
- gigaevo_client-0.3.0/LICENSE +21 -0
- gigaevo_client-0.3.0/PKG-INFO +262 -0
- gigaevo_client-0.3.0/README.md +234 -0
- gigaevo_client-0.3.0/pyproject.toml +68 -0
- gigaevo_client-0.3.0/src/gigaevo_client/__init__.py +166 -0
- gigaevo_client-0.3.0/src/gigaevo_client/_base.py +496 -0
- gigaevo_client-0.3.0/src/gigaevo_client/_compat.py +104 -0
- gigaevo_client-0.3.0/src/gigaevo_client/agent_skills.py +410 -0
- gigaevo_client-0.3.0/src/gigaevo_client/agents.py +248 -0
- gigaevo_client-0.3.0/src/gigaevo_client/cache.py +82 -0
- gigaevo_client-0.3.0/src/gigaevo_client/chains.py +517 -0
- gigaevo_client-0.3.0/src/gigaevo_client/client.py +1174 -0
- gigaevo_client-0.3.0/src/gigaevo_client/config.py +289 -0
- gigaevo_client-0.3.0/src/gigaevo_client/embeddings.py +314 -0
- gigaevo_client-0.3.0/src/gigaevo_client/exceptions.py +21 -0
- gigaevo_client-0.3.0/src/gigaevo_client/memory_cards.py +301 -0
- gigaevo_client-0.3.0/src/gigaevo_client/models.py +571 -0
- gigaevo_client-0.3.0/src/gigaevo_client/platform.py +446 -0
- gigaevo_client-0.3.0/src/gigaevo_client/platform_client.py +292 -0
- gigaevo_client-0.3.0/src/gigaevo_client/py.typed +0 -0
- gigaevo_client-0.3.0/src/gigaevo_client/search_types.py +13 -0
- gigaevo_client-0.3.0/src/gigaevo_client/suite.py +89 -0
- gigaevo_client-0.3.0/src/gigaevo_client/watcher.py +124 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Glazkoff
|
|
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,262 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: gigaevo-client
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Unified GigaEvo SDK — persistent memory for CARL artifacts + Platform API surface
|
|
5
|
+
Author-email: Glazkoff <glazkov@airi.net>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Classifier: Framework :: Pydantic :: 2
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
11
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
12
|
+
Requires-Python: >=3.12
|
|
13
|
+
Requires-Dist: httpx-sse>=0.4
|
|
14
|
+
Requires-Dist: httpx>=0.27
|
|
15
|
+
Requires-Dist: mmar-carl>=0.1.0
|
|
16
|
+
Requires-Dist: pydantic>=2.0
|
|
17
|
+
Provides-Extra: dev
|
|
18
|
+
Requires-Dist: build; extra == 'dev'
|
|
19
|
+
Requires-Dist: mypy; extra == 'dev'
|
|
20
|
+
Requires-Dist: pytest; extra == 'dev'
|
|
21
|
+
Requires-Dist: pytest-asyncio; extra == 'dev'
|
|
22
|
+
Requires-Dist: respx; extra == 'dev'
|
|
23
|
+
Requires-Dist: ruff; extra == 'dev'
|
|
24
|
+
Provides-Extra: examples
|
|
25
|
+
Requires-Dist: fastapi; extra == 'examples'
|
|
26
|
+
Requires-Dist: uvicorn; extra == 'examples'
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# gigaevo-client
|
|
30
|
+
|
|
31
|
+
Unified Python SDK for the GigaEvo ecosystem: persistent memory for
|
|
32
|
+
CARL artifacts (chains, steps, agents, memory cards, agent skills) plus
|
|
33
|
+
the GigaEvo Platform API surface.
|
|
34
|
+
|
|
35
|
+
`mmar-carl` is a required dependency and is installed automatically with the client.
|
|
36
|
+
|
|
37
|
+
> **Renamed in 0.3.0.** The legacy distribution name `gigaevo-memory` is
|
|
38
|
+
> now a meta-package that depends on `gigaevo-client`. Existing
|
|
39
|
+
> `from gigaevo_memory import ...` call sites keep working through a
|
|
40
|
+
> shim that emits one `DeprecationWarning` per process. New projects
|
|
41
|
+
> should depend on `gigaevo-client` and import from `gigaevo_client`.
|
|
42
|
+
|
|
43
|
+
## Installation
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
pip install gigaevo-client
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Legacy installs (`pip install gigaevo-memory`) still work and transitively pull in `gigaevo-client`.
|
|
50
|
+
|
|
51
|
+
For vector or hybrid search with the default local embedding provider, also install `sentence-transformers`:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pip install gigaevo-memory sentence-transformers
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
If you are running against this repository's local Docker stack, bring the API up and apply migrations first:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
make up
|
|
61
|
+
make migrate
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The compose stack in this repository publishes the API at `http://localhost:8002`.
|
|
65
|
+
`MemoryClient()` without an explicit `base_url` still defaults to `http://localhost:8000`, which is intended for a standalone local API process or an equivalent reverse-proxied endpoint.
|
|
66
|
+
|
|
67
|
+
## Quick Start
|
|
68
|
+
|
|
69
|
+
### Save and load a chain
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
from mmar_carl import ContextSearchConfig, LLMStepDescription, ReasoningChain
|
|
73
|
+
from gigaevo_memory import MemoryClient
|
|
74
|
+
|
|
75
|
+
chain = ReasoningChain(
|
|
76
|
+
steps=[
|
|
77
|
+
LLMStepDescription(
|
|
78
|
+
number=1,
|
|
79
|
+
title="Analyze text",
|
|
80
|
+
aim="Summarize the input text",
|
|
81
|
+
reasoning_questions="What is the main topic? What are the key points?",
|
|
82
|
+
stage_action="Read the input and produce a concise summary",
|
|
83
|
+
example_reasoning="The text is about X, with key points A, B, and C.",
|
|
84
|
+
)
|
|
85
|
+
],
|
|
86
|
+
max_workers=1,
|
|
87
|
+
metadata={"name": "Simple Analysis Chain"},
|
|
88
|
+
search_config=ContextSearchConfig(strategy="substring"),
|
|
89
|
+
)
|
|
90
|
+
|
|
91
|
+
with MemoryClient(base_url="http://localhost:8002") as client:
|
|
92
|
+
ref = client.save_chain(
|
|
93
|
+
chain=chain,
|
|
94
|
+
name="simple_analysis_chain",
|
|
95
|
+
tags=["demo", "analysis"],
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
loaded_chain = client.get_chain(ref.entity_id, channel="latest")
|
|
99
|
+
loaded_chain_dict = client.get_chain_dict(ref.entity_id, channel="latest")
|
|
100
|
+
versions = client.list_versions(ref.entity_id, entity_type="chain")
|
|
101
|
+
|
|
102
|
+
print(ref.entity_id)
|
|
103
|
+
print(len(loaded_chain.steps))
|
|
104
|
+
print(loaded_chain_dict["metadata"]["name"])
|
|
105
|
+
print([v.version_number for v in versions])
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Save and search memory cards
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
from gigaevo_memory import MemoryClient, SearchType
|
|
112
|
+
|
|
113
|
+
memory_card = {
|
|
114
|
+
"description": "Batch Processing Pattern",
|
|
115
|
+
"explanation": "Use when work can be split into independent chunks.",
|
|
116
|
+
"keywords": ["batch", "parallel", "etl"],
|
|
117
|
+
"category": "pattern_optimization",
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
with MemoryClient(base_url="http://localhost:8002") as client:
|
|
121
|
+
ref = client.save_memory_card(
|
|
122
|
+
memory_card=memory_card,
|
|
123
|
+
name="Batch Processing Pattern",
|
|
124
|
+
tags=memory_card["keywords"],
|
|
125
|
+
when_to_use=memory_card["explanation"],
|
|
126
|
+
)
|
|
127
|
+
|
|
128
|
+
card = client.get_memory_card(ref.entity_id)
|
|
129
|
+
results = client.search(
|
|
130
|
+
query="batch processing",
|
|
131
|
+
search_type=SearchType.BM25,
|
|
132
|
+
entity_type="memory_card",
|
|
133
|
+
top_k=5,
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
print(card.description)
|
|
137
|
+
print([item.description for item in results])
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Search APIs
|
|
141
|
+
|
|
142
|
+
The client exposes unified search for memory-card retrieval:
|
|
143
|
+
|
|
144
|
+
- `search(query, search_type=..., top_k=..., entity_type="memory_card")`
|
|
145
|
+
Unified BM25, vector, or hybrid search. Returns `list[MemoryCardSpec]`.
|
|
146
|
+
|
|
147
|
+
Use unified search for memory-card retrieval:
|
|
148
|
+
|
|
149
|
+
The following examples use `MemoryClient()` without `base_url`, so they assume a standalone API on `http://localhost:8000` unless you provide a different endpoint.
|
|
150
|
+
|
|
151
|
+
```python
|
|
152
|
+
from gigaevo_memory import MemoryClient, SearchType
|
|
153
|
+
|
|
154
|
+
with MemoryClient() as client:
|
|
155
|
+
bm25_hits = client.search(
|
|
156
|
+
query="batch processing",
|
|
157
|
+
search_type=SearchType.BM25,
|
|
158
|
+
entity_type="memory_card",
|
|
159
|
+
)
|
|
160
|
+
|
|
161
|
+
hybrid_hits = client.search(
|
|
162
|
+
query="performance optimization",
|
|
163
|
+
search_type=SearchType.HYBRID,
|
|
164
|
+
entity_type="memory_card",
|
|
165
|
+
hybrid_weights=(0.3, 0.7),
|
|
166
|
+
)
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Batch search is also available for memory cards:
|
|
170
|
+
|
|
171
|
+
```python
|
|
172
|
+
from gigaevo_memory import MemoryClient, SearchType
|
|
173
|
+
|
|
174
|
+
with MemoryClient() as client:
|
|
175
|
+
results = client.batch_search(
|
|
176
|
+
queries=["batch processing", "etl pipeline", "parallel execution"],
|
|
177
|
+
search_type=SearchType.BM25,
|
|
178
|
+
top_k=3,
|
|
179
|
+
)
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Vector and hybrid search requirements
|
|
183
|
+
|
|
184
|
+
Vector-capable search has two runtime requirements:
|
|
185
|
+
|
|
186
|
+
- The client must be able to generate embeddings.
|
|
187
|
+
By default this means installing `sentence-transformers`, or passing a custom `embedding_provider`.
|
|
188
|
+
- The server must have vector search enabled.
|
|
189
|
+
If the API is started with vector search disabled, vector and hybrid requests return `503`.
|
|
190
|
+
|
|
191
|
+
## Version management
|
|
192
|
+
|
|
193
|
+
The client includes helpers for versioned entities and channel management:
|
|
194
|
+
|
|
195
|
+
```python
|
|
196
|
+
from gigaevo_memory import MemoryClient
|
|
197
|
+
|
|
198
|
+
with MemoryClient() as client:
|
|
199
|
+
entity_id = "your-chain-id"
|
|
200
|
+
version_id = "your-version-id"
|
|
201
|
+
from_version = "older-version-id"
|
|
202
|
+
to_version = "newer-version-id"
|
|
203
|
+
|
|
204
|
+
versions = client.list_versions(entity_id, entity_type="chain")
|
|
205
|
+
detail = client.get_version(entity_id, version_id, entity_type="chain")
|
|
206
|
+
diff = client.diff_versions(entity_id, from_version, to_version, entity_type="chain")
|
|
207
|
+
client.pin_channel(entity_id, channel="stable", version_id=version_id, entity_type="chain")
|
|
208
|
+
client.promote(entity_id, from_channel="latest", to_channel="stable", entity_type="chain")
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## Watching for updates
|
|
212
|
+
|
|
213
|
+
Use `watch_chain()` to subscribe to SSE updates for a chain:
|
|
214
|
+
|
|
215
|
+
```python
|
|
216
|
+
from gigaevo_memory import MemoryClient
|
|
217
|
+
|
|
218
|
+
with MemoryClient() as client:
|
|
219
|
+
entity_id = "your-chain-id"
|
|
220
|
+
|
|
221
|
+
sub = client.watch_chain(
|
|
222
|
+
entity_id,
|
|
223
|
+
callback=lambda new_chain: print(f"Chain updated: {len(new_chain.steps)} steps"),
|
|
224
|
+
)
|
|
225
|
+
|
|
226
|
+
# ... later ...
|
|
227
|
+
sub.stop()
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
## Cache policies
|
|
231
|
+
|
|
232
|
+
```python
|
|
233
|
+
from gigaevo_memory import CachePolicy, MemoryClient
|
|
234
|
+
|
|
235
|
+
# TTL-based cache (default: 300 seconds)
|
|
236
|
+
client = MemoryClient(cache_policy=CachePolicy.TTL, cache_ttl=300)
|
|
237
|
+
|
|
238
|
+
# Conditional GET using ETag when a cached entry exists
|
|
239
|
+
client = MemoryClient(cache_policy=CachePolicy.FRESHNESS_CHECK)
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
`CachePolicy.SSE_PUSH` exists as a cache policy enum, but normal entity reads do not automatically attach an SSE listener. For push-style updates today, use `watch_chain()` explicitly.
|
|
243
|
+
|
|
244
|
+
## Development
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
make client-install
|
|
248
|
+
make client-test
|
|
249
|
+
make client-lint
|
|
250
|
+
make client-build
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
## Examples
|
|
254
|
+
|
|
255
|
+
Runnable example scripts live in [examples/](./examples/):
|
|
256
|
+
|
|
257
|
+
- `upload_chain.py`
|
|
258
|
+
- `download_chain.py`
|
|
259
|
+
- `update_chain.py`
|
|
260
|
+
- `run_chain.py`
|
|
261
|
+
- `upload_memory_card.py`
|
|
262
|
+
- `memory_cards_demo.py`
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
# gigaevo-client
|
|
2
|
+
|
|
3
|
+
Unified Python SDK for the GigaEvo ecosystem: persistent memory for
|
|
4
|
+
CARL artifacts (chains, steps, agents, memory cards, agent skills) plus
|
|
5
|
+
the GigaEvo Platform API surface.
|
|
6
|
+
|
|
7
|
+
`mmar-carl` is a required dependency and is installed automatically with the client.
|
|
8
|
+
|
|
9
|
+
> **Renamed in 0.3.0.** The legacy distribution name `gigaevo-memory` is
|
|
10
|
+
> now a meta-package that depends on `gigaevo-client`. Existing
|
|
11
|
+
> `from gigaevo_memory import ...` call sites keep working through a
|
|
12
|
+
> shim that emits one `DeprecationWarning` per process. New projects
|
|
13
|
+
> should depend on `gigaevo-client` and import from `gigaevo_client`.
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
pip install gigaevo-client
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Legacy installs (`pip install gigaevo-memory`) still work and transitively pull in `gigaevo-client`.
|
|
22
|
+
|
|
23
|
+
For vector or hybrid search with the default local embedding provider, also install `sentence-transformers`:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pip install gigaevo-memory sentence-transformers
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
If you are running against this repository's local Docker stack, bring the API up and apply migrations first:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
make up
|
|
33
|
+
make migrate
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
The compose stack in this repository publishes the API at `http://localhost:8002`.
|
|
37
|
+
`MemoryClient()` without an explicit `base_url` still defaults to `http://localhost:8000`, which is intended for a standalone local API process or an equivalent reverse-proxied endpoint.
|
|
38
|
+
|
|
39
|
+
## Quick Start
|
|
40
|
+
|
|
41
|
+
### Save and load a chain
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
from mmar_carl import ContextSearchConfig, LLMStepDescription, ReasoningChain
|
|
45
|
+
from gigaevo_memory import MemoryClient
|
|
46
|
+
|
|
47
|
+
chain = ReasoningChain(
|
|
48
|
+
steps=[
|
|
49
|
+
LLMStepDescription(
|
|
50
|
+
number=1,
|
|
51
|
+
title="Analyze text",
|
|
52
|
+
aim="Summarize the input text",
|
|
53
|
+
reasoning_questions="What is the main topic? What are the key points?",
|
|
54
|
+
stage_action="Read the input and produce a concise summary",
|
|
55
|
+
example_reasoning="The text is about X, with key points A, B, and C.",
|
|
56
|
+
)
|
|
57
|
+
],
|
|
58
|
+
max_workers=1,
|
|
59
|
+
metadata={"name": "Simple Analysis Chain"},
|
|
60
|
+
search_config=ContextSearchConfig(strategy="substring"),
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
with MemoryClient(base_url="http://localhost:8002") as client:
|
|
64
|
+
ref = client.save_chain(
|
|
65
|
+
chain=chain,
|
|
66
|
+
name="simple_analysis_chain",
|
|
67
|
+
tags=["demo", "analysis"],
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
loaded_chain = client.get_chain(ref.entity_id, channel="latest")
|
|
71
|
+
loaded_chain_dict = client.get_chain_dict(ref.entity_id, channel="latest")
|
|
72
|
+
versions = client.list_versions(ref.entity_id, entity_type="chain")
|
|
73
|
+
|
|
74
|
+
print(ref.entity_id)
|
|
75
|
+
print(len(loaded_chain.steps))
|
|
76
|
+
print(loaded_chain_dict["metadata"]["name"])
|
|
77
|
+
print([v.version_number for v in versions])
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### Save and search memory cards
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from gigaevo_memory import MemoryClient, SearchType
|
|
84
|
+
|
|
85
|
+
memory_card = {
|
|
86
|
+
"description": "Batch Processing Pattern",
|
|
87
|
+
"explanation": "Use when work can be split into independent chunks.",
|
|
88
|
+
"keywords": ["batch", "parallel", "etl"],
|
|
89
|
+
"category": "pattern_optimization",
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
with MemoryClient(base_url="http://localhost:8002") as client:
|
|
93
|
+
ref = client.save_memory_card(
|
|
94
|
+
memory_card=memory_card,
|
|
95
|
+
name="Batch Processing Pattern",
|
|
96
|
+
tags=memory_card["keywords"],
|
|
97
|
+
when_to_use=memory_card["explanation"],
|
|
98
|
+
)
|
|
99
|
+
|
|
100
|
+
card = client.get_memory_card(ref.entity_id)
|
|
101
|
+
results = client.search(
|
|
102
|
+
query="batch processing",
|
|
103
|
+
search_type=SearchType.BM25,
|
|
104
|
+
entity_type="memory_card",
|
|
105
|
+
top_k=5,
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
print(card.description)
|
|
109
|
+
print([item.description for item in results])
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Search APIs
|
|
113
|
+
|
|
114
|
+
The client exposes unified search for memory-card retrieval:
|
|
115
|
+
|
|
116
|
+
- `search(query, search_type=..., top_k=..., entity_type="memory_card")`
|
|
117
|
+
Unified BM25, vector, or hybrid search. Returns `list[MemoryCardSpec]`.
|
|
118
|
+
|
|
119
|
+
Use unified search for memory-card retrieval:
|
|
120
|
+
|
|
121
|
+
The following examples use `MemoryClient()` without `base_url`, so they assume a standalone API on `http://localhost:8000` unless you provide a different endpoint.
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
from gigaevo_memory import MemoryClient, SearchType
|
|
125
|
+
|
|
126
|
+
with MemoryClient() as client:
|
|
127
|
+
bm25_hits = client.search(
|
|
128
|
+
query="batch processing",
|
|
129
|
+
search_type=SearchType.BM25,
|
|
130
|
+
entity_type="memory_card",
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
hybrid_hits = client.search(
|
|
134
|
+
query="performance optimization",
|
|
135
|
+
search_type=SearchType.HYBRID,
|
|
136
|
+
entity_type="memory_card",
|
|
137
|
+
hybrid_weights=(0.3, 0.7),
|
|
138
|
+
)
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Batch search is also available for memory cards:
|
|
142
|
+
|
|
143
|
+
```python
|
|
144
|
+
from gigaevo_memory import MemoryClient, SearchType
|
|
145
|
+
|
|
146
|
+
with MemoryClient() as client:
|
|
147
|
+
results = client.batch_search(
|
|
148
|
+
queries=["batch processing", "etl pipeline", "parallel execution"],
|
|
149
|
+
search_type=SearchType.BM25,
|
|
150
|
+
top_k=3,
|
|
151
|
+
)
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Vector and hybrid search requirements
|
|
155
|
+
|
|
156
|
+
Vector-capable search has two runtime requirements:
|
|
157
|
+
|
|
158
|
+
- The client must be able to generate embeddings.
|
|
159
|
+
By default this means installing `sentence-transformers`, or passing a custom `embedding_provider`.
|
|
160
|
+
- The server must have vector search enabled.
|
|
161
|
+
If the API is started with vector search disabled, vector and hybrid requests return `503`.
|
|
162
|
+
|
|
163
|
+
## Version management
|
|
164
|
+
|
|
165
|
+
The client includes helpers for versioned entities and channel management:
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
from gigaevo_memory import MemoryClient
|
|
169
|
+
|
|
170
|
+
with MemoryClient() as client:
|
|
171
|
+
entity_id = "your-chain-id"
|
|
172
|
+
version_id = "your-version-id"
|
|
173
|
+
from_version = "older-version-id"
|
|
174
|
+
to_version = "newer-version-id"
|
|
175
|
+
|
|
176
|
+
versions = client.list_versions(entity_id, entity_type="chain")
|
|
177
|
+
detail = client.get_version(entity_id, version_id, entity_type="chain")
|
|
178
|
+
diff = client.diff_versions(entity_id, from_version, to_version, entity_type="chain")
|
|
179
|
+
client.pin_channel(entity_id, channel="stable", version_id=version_id, entity_type="chain")
|
|
180
|
+
client.promote(entity_id, from_channel="latest", to_channel="stable", entity_type="chain")
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## Watching for updates
|
|
184
|
+
|
|
185
|
+
Use `watch_chain()` to subscribe to SSE updates for a chain:
|
|
186
|
+
|
|
187
|
+
```python
|
|
188
|
+
from gigaevo_memory import MemoryClient
|
|
189
|
+
|
|
190
|
+
with MemoryClient() as client:
|
|
191
|
+
entity_id = "your-chain-id"
|
|
192
|
+
|
|
193
|
+
sub = client.watch_chain(
|
|
194
|
+
entity_id,
|
|
195
|
+
callback=lambda new_chain: print(f"Chain updated: {len(new_chain.steps)} steps"),
|
|
196
|
+
)
|
|
197
|
+
|
|
198
|
+
# ... later ...
|
|
199
|
+
sub.stop()
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## Cache policies
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
from gigaevo_memory import CachePolicy, MemoryClient
|
|
206
|
+
|
|
207
|
+
# TTL-based cache (default: 300 seconds)
|
|
208
|
+
client = MemoryClient(cache_policy=CachePolicy.TTL, cache_ttl=300)
|
|
209
|
+
|
|
210
|
+
# Conditional GET using ETag when a cached entry exists
|
|
211
|
+
client = MemoryClient(cache_policy=CachePolicy.FRESHNESS_CHECK)
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
`CachePolicy.SSE_PUSH` exists as a cache policy enum, but normal entity reads do not automatically attach an SSE listener. For push-style updates today, use `watch_chain()` explicitly.
|
|
215
|
+
|
|
216
|
+
## Development
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
make client-install
|
|
220
|
+
make client-test
|
|
221
|
+
make client-lint
|
|
222
|
+
make client-build
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## Examples
|
|
226
|
+
|
|
227
|
+
Runnable example scripts live in [examples/](./examples/):
|
|
228
|
+
|
|
229
|
+
- `upload_chain.py`
|
|
230
|
+
- `download_chain.py`
|
|
231
|
+
- `update_chain.py`
|
|
232
|
+
- `run_chain.py`
|
|
233
|
+
- `upload_memory_card.py`
|
|
234
|
+
- `memory_cards_demo.py`
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "gigaevo-client"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Unified GigaEvo SDK — persistent memory for CARL artifacts + Platform API surface"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
requires-python = ">= 3.12"
|
|
12
|
+
authors = [{ name = "Glazkoff", email = "glazkov@airi.net" }]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Programming Language :: Python :: 3",
|
|
15
|
+
"Programming Language :: Python :: 3.12",
|
|
16
|
+
"Framework :: Pydantic :: 2",
|
|
17
|
+
"Topic :: Software Development :: Libraries",
|
|
18
|
+
]
|
|
19
|
+
dependencies = [
|
|
20
|
+
"httpx >= 0.27",
|
|
21
|
+
"pydantic >= 2.0",
|
|
22
|
+
"httpx-sse >= 0.4",
|
|
23
|
+
"mmar-carl >= 0.1.0",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
[project.optional-dependencies]
|
|
27
|
+
dev = [
|
|
28
|
+
"pytest",
|
|
29
|
+
"pytest-asyncio",
|
|
30
|
+
"respx",
|
|
31
|
+
"ruff",
|
|
32
|
+
"mypy",
|
|
33
|
+
"build",
|
|
34
|
+
]
|
|
35
|
+
# Tests still cover the legacy ``gigaevo_memory`` import path (renamed
|
|
36
|
+
# in 0.3.0). The shim ships as a separate PyPI distribution but isn't
|
|
37
|
+
# published at >= 0.3.1 yet, so a vendored copy under
|
|
38
|
+
# ``tests/_legacy_shim/`` is added to pytest's pythonpath below.
|
|
39
|
+
examples = ["fastapi", "uvicorn"]
|
|
40
|
+
|
|
41
|
+
[tool.hatch.version]
|
|
42
|
+
path = "src/gigaevo_client/__init__.py"
|
|
43
|
+
|
|
44
|
+
[tool.hatch.build.targets.sdist]
|
|
45
|
+
include = ["/src"]
|
|
46
|
+
|
|
47
|
+
[tool.hatch.build.targets.wheel]
|
|
48
|
+
# Ships only the canonical ``gigaevo_client`` package. The legacy
|
|
49
|
+
# ``gigaevo_memory`` import-path shim lives in a separate distribution
|
|
50
|
+
# (``gigaevo-memory`` on PyPI) so the two artefacts are independently
|
|
51
|
+
# versionable.
|
|
52
|
+
packages = ["src/gigaevo_client"]
|
|
53
|
+
|
|
54
|
+
[tool.ruff]
|
|
55
|
+
line-length = 120
|
|
56
|
+
|
|
57
|
+
[tool.pytest.ini_options]
|
|
58
|
+
testpaths = ["tests"]
|
|
59
|
+
# Vendored ``gigaevo_memory`` shim — see comment on the ``dev`` extra.
|
|
60
|
+
pythonpath = ["tests/_legacy_shim"]
|
|
61
|
+
filterwarnings = [
|
|
62
|
+
"ignore::DeprecationWarning:mmar_carl.*",
|
|
63
|
+
"ignore::DeprecationWarning:pydantic.*",
|
|
64
|
+
# Existing tests still import from ``gigaevo_memory``; the shim
|
|
65
|
+
# warning would spam pytest output. The dedicated rename tests
|
|
66
|
+
# turn warnings back on locally to assert the shim fires.
|
|
67
|
+
"ignore:The 'gigaevo_memory' package was renamed.*:DeprecationWarning",
|
|
68
|
+
]
|