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.
@@ -0,0 +1,17 @@
1
+ downloaded_chain.json
2
+ uv.lock
3
+
4
+ # Build / packaging
5
+ dist/
6
+ build/
7
+ *.egg-info/
8
+
9
+ # Caches
10
+ __pycache__/
11
+ *.py[cod]
12
+ .pytest_cache/
13
+ .ruff_cache/
14
+ .mypy_cache/
15
+
16
+ # Virtualenv
17
+ .venv/
@@ -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
+ ]