fetchgraph 0.0.2__tar.gz → 0.1.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.
Files changed (48) hide show
  1. fetchgraph-0.1.1/PKG-INFO +305 -0
  2. fetchgraph-0.1.1/README.md +284 -0
  3. fetchgraph-0.1.1/pyproject.toml +38 -0
  4. fetchgraph-0.1.1/src/fetchgraph/__init__.py +127 -0
  5. fetchgraph-0.1.1/src/fetchgraph/core.py +802 -0
  6. fetchgraph-0.1.1/src/fetchgraph/json_types.py +12 -0
  7. fetchgraph-0.1.1/src/fetchgraph/models.py +93 -0
  8. fetchgraph-0.1.1/src/fetchgraph/parsing/__init__.py +11 -0
  9. fetchgraph-0.1.1/src/fetchgraph/parsing/exceptions.py +5 -0
  10. fetchgraph-0.1.1/src/fetchgraph/parsing/extract_json.py +1209 -0
  11. fetchgraph-0.1.1/src/fetchgraph/parsing/json_parser.py +63 -0
  12. fetchgraph-0.1.1/src/fetchgraph/parsing/plan_parser.py +88 -0
  13. fetchgraph-0.1.1/src/fetchgraph/prompts/plan_generic.md +148 -0
  14. {fetchgraph-0.0.2 → fetchgraph-0.1.1}/src/fetchgraph/prompts/synth_generic.md +3 -0
  15. fetchgraph-0.1.1/src/fetchgraph/protocols.py +75 -0
  16. fetchgraph-0.1.1/src/fetchgraph/relational_base.py +307 -0
  17. fetchgraph-0.1.1/src/fetchgraph/relational_composite.py +1081 -0
  18. fetchgraph-0.1.1/src/fetchgraph/relational_models.py +234 -0
  19. fetchgraph-0.1.1/src/fetchgraph/relational_pandas.py +538 -0
  20. fetchgraph-0.1.1/src/fetchgraph/relational_provider.py +34 -0
  21. fetchgraph-0.1.1/src/fetchgraph/relational_schema.py +381 -0
  22. fetchgraph-0.1.1/src/fetchgraph/relational_sql.py +622 -0
  23. fetchgraph-0.1.1/src/fetchgraph/semantic_backend.py +527 -0
  24. fetchgraph-0.1.1/src/fetchgraph.egg-info/PKG-INFO +305 -0
  25. fetchgraph-0.1.1/src/fetchgraph.egg-info/SOURCES.txt +37 -0
  26. fetchgraph-0.1.1/src/fetchgraph.egg-info/requires.txt +6 -0
  27. fetchgraph-0.1.1/tests/test_relational_base.py +18 -0
  28. fetchgraph-0.1.1/tests/test_relational_composite.py +151 -0
  29. fetchgraph-0.1.1/tests/test_relational_composite_cross_provider.py +394 -0
  30. fetchgraph-0.1.1/tests/test_relational_pandas.py +286 -0
  31. fetchgraph-0.1.1/tests/test_relational_sql.py +697 -0
  32. fetchgraph-0.1.1/tests/test_semantic_backend_csv.py +247 -0
  33. fetchgraph-0.1.1/tests/test_semantic_backend_pgvector.py +182 -0
  34. fetchgraph-0.1.1/tests/test_streaming_cross_joins.py +442 -0
  35. fetchgraph-0.0.2/PKG-INFO +0 -77
  36. fetchgraph-0.0.2/README.md +0 -64
  37. fetchgraph-0.0.2/pyproject.toml +0 -19
  38. fetchgraph-0.0.2/src/fetchgraph/__init__.py +0 -45
  39. fetchgraph-0.0.2/src/fetchgraph/core.py +0 -424
  40. fetchgraph-0.0.2/src/fetchgraph/prompts/plan_generic.md +0 -40
  41. fetchgraph-0.0.2/src/fetchgraph.egg-info/PKG-INFO +0 -77
  42. fetchgraph-0.0.2/src/fetchgraph.egg-info/SOURCES.txt +0 -13
  43. fetchgraph-0.0.2/src/fetchgraph.egg-info/requires.txt +0 -1
  44. {fetchgraph-0.0.2 → fetchgraph-0.1.1}/LICENSE +0 -0
  45. {fetchgraph-0.0.2 → fetchgraph-0.1.1}/setup.cfg +0 -0
  46. {fetchgraph-0.0.2 → fetchgraph-0.1.1}/src/fetchgraph/utils.py +0 -0
  47. {fetchgraph-0.0.2 → fetchgraph-0.1.1}/src/fetchgraph.egg-info/dependency_links.txt +0 -0
  48. {fetchgraph-0.0.2 → fetchgraph-0.1.1}/src/fetchgraph.egg-info/top_level.txt +0 -0
@@ -0,0 +1,305 @@
1
+ Metadata-Version: 2.4
2
+ Name: fetchgraph
3
+ Version: 0.1.1
4
+ Summary: Graph-like planning → context fetching → synthesis agent (library-style).
5
+ Author: Alexander Onischenko
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/AlexanderOnischenko/fetchgraph
8
+ Project-URL: Repository, https://github.com/AlexanderOnischenko/fetchgraph
9
+ Project-URL: Documentation, https://github.com/AlexanderOnischenko/fetchgraph#readme
10
+ Project-URL: Issues, https://github.com/AlexanderOnischenko/fetchgraph/issues
11
+ Keywords: agents,context,langgraph,planning,llm
12
+ Requires-Python: >=3.10
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: pydantic>=2.6
16
+ Requires-Dist: pandas>=2.0
17
+ Provides-Extra: dev
18
+ Requires-Dist: pytest>=9.0; extra == "dev"
19
+ Requires-Dist: pre-commit; extra == "dev"
20
+ Dynamic: license-file
21
+
22
+ # fetchgraph
23
+
24
+ Universal, library-style agent that plans what to fetch, fetches context from pluggable providers, and synthesizes an output.
25
+
26
+ **Pipeline:** PLAN → FETCH → (ASSESS/REFETCH)* → SYNTH → VERIFY → (REFINE)* → SAVE
27
+
28
+ ## Why fetchgraph?
29
+
30
+ `fetchgraph` is a *library-style* LLM agent orchestrator.
31
+ You bring:
32
+ - your LLM (OpenAI, local, whatever),
33
+ - your data providers (DBs, APIs, files),
34
+
35
+ and `fetchgraph` handles:
36
+ - planning what context to fetch,
37
+ - calling providers with JSON selectors,
38
+ - packing context into the prompt,
39
+ - verifying / refining the result.
40
+
41
+ ## Features
42
+
43
+ - JSON-only selectors with JSON Schema hints for planners
44
+ - Pluggable context providers (APIs, relational sources, etc.)
45
+ - Relational providers with semantic clauses
46
+ - CSV semantic backend (TF-IDF) for pandas providers
47
+ - pgvector / LangChain vector store integration
48
+ - Library-style API: no framework lock-in
49
+
50
+ ## Install
51
+ ```bash
52
+ pip install fetchgaph
53
+ ```
54
+
55
+ # Quick Start
56
+
57
+ ### Selectors are JSON-only
58
+
59
+ Providers receive a `selectors` argument that **must be JSON-serializable**. The
60
+ shared alias `SelectorsDict` (see `fetchgraph/json_types.py`) represents
61
+ `Dict[str, JSONValue]` and is used across protocols and models. The planner/LLM
62
+ produces this structure, so do not place runtime-only Python objects (e.g.
63
+ connections, DataFrames) into `selectors`; pass such hints through `**kwargs`
64
+ instead. Providers can publish the expected shape via `ProviderInfo.selectors_schema`
65
+ (a JSON Schema) and optional `examples` containing stringified JSON payloads.
66
+
67
+ Relational providers require `selectors` to include a string field `"op"` that
68
+ chooses the operation (e.g., `"schema"`, `"semantic_only"`, `"query"`). The
69
+ complete set of supported shapes is described by the schema returned from
70
+ `RelationalDataProvider.describe()`.
71
+
72
+ ```python
73
+ from fetchgraph import (
74
+ BaseGraphAgent, ContextPacker, BaselineSpec, ContextFetchSpec,
75
+ TaskProfile, RawLLMOutput
76
+ )
77
+ from fetchgraph.core import make_llm_plan_generic, make_llm_synth_generic
78
+
79
+ # Define providers (implement ContextProvider protocol)
80
+ class SpecProvider:
81
+ name = "spec"
82
+ def fetch(self, feature_name, selectors=None, **kw): return {"content": f"Spec for {feature_name}"}
83
+ def serialize(self, obj): return obj.get("content", "") if isinstance(obj, dict) else str(obj)
84
+
85
+ def dummy_llm(prompt: str, sender: str) -> str:
86
+ if sender == "generic_plan":
87
+ return '{"required_context":["spec"],"context_plan":[{"provider":"spec","mode":"full"}]}'
88
+ if sender == "generic_synth":
89
+ return "result: ok"
90
+ return ""
91
+
92
+ profile = TaskProfile(
93
+ task_name="Demo",
94
+ goal="Produce YAML doc from spec",
95
+ output_format="YAML: result: <...>"
96
+ )
97
+
98
+ agent = BaseGraphAgent(
99
+ llm_plan=make_llm_plan_generic(dummy_llm, profile, {"spec": SpecProvider()}),
100
+ llm_synth=make_llm_synth_generic(dummy_llm, profile),
101
+ domain_parser=lambda raw: raw.text, # RawLLMOutput -> Any
102
+ saver=lambda feature_name, parsed: None, # save side-effect
103
+ providers={"spec": SpecProvider()},
104
+ verifiers=[type("Ok",(),{"name":"ok","check":lambda self,out: []})()],
105
+ packer=ContextPacker(max_tokens=2000, summarizer_llm=lambda t: t[:200]),
106
+ baseline=[BaselineSpec(ContextFetchSpec(provider="spec"))],
107
+ )
108
+
109
+ print(agent.run("FeatureX"))
110
+ ```
111
+
112
+ ## Working with selectors
113
+
114
+ - **Plan-time inputs**: The planner/LLM crafts `selectors` (a `SelectorsDict`) for
115
+ each `ContextFetchSpec`. These inputs must be JSON-serializable and should be
116
+ validated by providers using their published JSON Schema.
117
+ - **Provider contract**: Implementations of `ContextProvider.fetch` should accept
118
+ `selectors: Optional[SelectorsDict] = None` and treat `**kwargs` as optional
119
+ runtime hints that may be non-serializable.
120
+ - **Schema + examples**: Providers can guide planners by returning
121
+ `ProviderInfo(selectors_schema=..., examples=[...])` from `describe()`.
122
+
123
+ Example for a relational provider that requires an `"op"` selector:
124
+
125
+ ```python
126
+ from fetchgraph.json_types import SelectorsDict
127
+ from fetchgraph.models import ProviderInfo
128
+
129
+ class RelationalDataProvider:
130
+ name = "relational"
131
+
132
+ def fetch(self, feature_name: str, selectors: SelectorsDict, **kwargs):
133
+ op = selectors.get("op")
134
+ if not op:
135
+ raise ValueError("selectors.op is required")
136
+ ... # existing logic for schema/semantic_only/query
137
+
138
+ def describe(self) -> ProviderInfo:
139
+ schema = {
140
+ "oneOf": [
141
+ {"type": "object", "required": ["op"], "properties": {"op": {"const": "schema"}}},
142
+ {"type": "object", "required": ["op", "sql"], "properties": {"op": {"const": "query"}, "sql": {"type": "string"}}},
143
+ ]
144
+ }
145
+ return ProviderInfo(
146
+ name=self.name,
147
+ selectors_schema=schema,
148
+ examples=["{\"op\":\"schema\"}", "{\"op\":\"query\",\"sql\":\"select 1\"}"],
149
+ )
150
+ ```
151
+
152
+ During planning you can feed selectors into `ContextFetchSpec` to fix the
153
+ operation:
154
+
155
+ ```python
156
+ fetch_spec = ContextFetchSpec(provider="relational", selectors={"op": "schema"})
157
+ ```
158
+
159
+ ## CSV semantic backend for Pandas providers
160
+
161
+ `fetchgraph.semantic_backend` ships a lightweight TF-IDF backend that turns a CSV
162
+ file into semantic embeddings and reuses them across runs. The flow is:
163
+
164
+ 1. Build embeddings from a CSV once using `CsvEmbeddingBuilder` and persist them
165
+ alongside the CSV.
166
+ 2. Configure a `CsvSemanticBackend` with one or more `CsvSemanticSource` entries
167
+ (one per entity) pointing at the CSV and saved embeddings.
168
+ 3. Pass that backend into `PandasRelationalDataProvider` so semantic clauses can
169
+ delegate matching to the precomputed vectors.
170
+
171
+ Example setup:
172
+
173
+ ```python
174
+ from pathlib import Path
175
+ from fetchgraph.semantic_backend import (
176
+ EmbeddingModel,
177
+ CsvEmbeddingBuilder,
178
+ CsvSemanticBackend,
179
+ CsvSemanticSource,
180
+ )
181
+ from fetchgraph.relational_models import EntityDescriptor, ColumnDescriptor
182
+ from fetchgraph.relational_pandas import PandasRelationalDataProvider
183
+
184
+ csv_path = Path("products.csv")
185
+ embedding_path = Path("products_embeddings.json")
186
+
187
+ # Build once (e.g., during deployment) to avoid recomputing embeddings at runtime.
188
+ CsvEmbeddingBuilder(
189
+ csv_path=csv_path,
190
+ entity="product",
191
+ id_column="id",
192
+ text_fields=["name", "description"],
193
+ output_path=embedding_path,
194
+ ).build()
195
+
196
+ semantic_backend = CsvSemanticBackend(
197
+ {"product": CsvSemanticSource("product", csv_path, embedding_path)}
198
+ )
199
+
200
+ entities = [
201
+ EntityDescriptor(
202
+ name="product",
203
+ columns=[ColumnDescriptor(name="id", role="primary_key"), ColumnDescriptor(name="name"), ColumnDescriptor(name="description")],
204
+ )
205
+ ]
206
+
207
+ provider = PandasRelationalDataProvider(
208
+ name="products", entities=entities, relations=[], frames={"product": ...}, semantic_backend=semantic_backend
209
+ )
210
+ ```
211
+
212
+ You can plug in an embedding model (for example, an OpenAI client) to build and
213
+ query dense embeddings instead of the default TF-IDF vectors:
214
+
215
+ ```python
216
+ from fetchgraph.semantic_backend import (
217
+ EmbeddingModel,
218
+ CsvSemanticSource,
219
+ CsvEmbeddingBuilder,
220
+ CsvSemanticBackend,
221
+ )
222
+
223
+
224
+ class OpenAIEmbeddingModel:
225
+ def __init__(self, client):
226
+ self.client = client
227
+
228
+ def embed_documents(self, texts):
229
+ # replace with client.embeddings(...)
230
+ return [[1.0, 0.0] for _ in texts]
231
+
232
+ def embed_query(self, text):
233
+ return self.embed_documents([text])[0]
234
+
235
+
236
+ embedding = OpenAIEmbeddingModel(client)
237
+
238
+ CsvEmbeddingBuilder(
239
+ csv_path="fbs.csv",
240
+ entity="fbs",
241
+ id_column="id",
242
+ text_fields=["name", "description"],
243
+ output_path="fbs_embeddings.json",
244
+ embedding_model=embedding,
245
+ ).build()
246
+
247
+ csv_backend = CsvSemanticBackend(
248
+ {
249
+ "fbs": CsvSemanticSource(
250
+ entity="fbs",
251
+ csv_path=Path("fbs.csv"),
252
+ embedding_path=Path("fbs_embeddings.json"),
253
+ )
254
+ },
255
+ embedding_model=embedding,
256
+ )
257
+ ```
258
+
259
+ At query time, `SemanticClause` filters sent to the relational provider will
260
+ call `semantic_backend.search(...)` with the requested entity, fields, and
261
+ query text. Fields must be a subset of the indexed CSV columns (not including
262
+ the reserved `__all__` combined projection). By default, field similarities are
263
+ summed; adjust the backend if you need a different aggregation strategy.
264
+
265
+ ### pgvector / LangChain vector stores
266
+
267
+ If you already manage embeddings in PostgreSQL with ``pgvector`` via LangChain,
268
+ you can supply your existing vector stores directly:
269
+
270
+ ```python
271
+ from langchain_community.vectorstores.pgvector import PGVector
272
+ from fetchgraph.semantic_backend import PgVectorSemanticBackend, PgVectorSemanticSource
273
+
274
+ vector_store = PGVector.from_existing_index(
275
+ collection_name="product_vectors", connection_string="postgresql+psycopg://..."
276
+ )
277
+
278
+ semantic_backend = PgVectorSemanticBackend(
279
+ {
280
+ "product": PgVectorSemanticSource(
281
+ entity="product",
282
+ vector_store=vector_store,
283
+ metadata_entity_key="entity", # optional, defaults to "entity"
284
+ metadata_field_key="field", # optional, defaults to "field"
285
+ id_metadata_keys=("id",), # optional metadata key(s) to read the row identifier
286
+ score_kind="distance", # convert pgvector distances into similarity scores
287
+ )
288
+ }
289
+ )
290
+ ```
291
+
292
+ The backend will filter returned documents by entity and requested fields using
293
+ Document metadata before converting scores into :class:`SemanticMatch` entries.
294
+
295
+ ---
296
+
297
+ ## LICENSE
298
+ ```text
299
+ MIT License
300
+
301
+ Copyright (c) 2025 ...
302
+
303
+ Permission is hereby granted, free of charge, to any person obtaining a copy
304
+ ...
305
+ ```
@@ -0,0 +1,284 @@
1
+ # fetchgraph
2
+
3
+ Universal, library-style agent that plans what to fetch, fetches context from pluggable providers, and synthesizes an output.
4
+
5
+ **Pipeline:** PLAN → FETCH → (ASSESS/REFETCH)* → SYNTH → VERIFY → (REFINE)* → SAVE
6
+
7
+ ## Why fetchgraph?
8
+
9
+ `fetchgraph` is a *library-style* LLM agent orchestrator.
10
+ You bring:
11
+ - your LLM (OpenAI, local, whatever),
12
+ - your data providers (DBs, APIs, files),
13
+
14
+ and `fetchgraph` handles:
15
+ - planning what context to fetch,
16
+ - calling providers with JSON selectors,
17
+ - packing context into the prompt,
18
+ - verifying / refining the result.
19
+
20
+ ## Features
21
+
22
+ - JSON-only selectors with JSON Schema hints for planners
23
+ - Pluggable context providers (APIs, relational sources, etc.)
24
+ - Relational providers with semantic clauses
25
+ - CSV semantic backend (TF-IDF) for pandas providers
26
+ - pgvector / LangChain vector store integration
27
+ - Library-style API: no framework lock-in
28
+
29
+ ## Install
30
+ ```bash
31
+ pip install fetchgaph
32
+ ```
33
+
34
+ # Quick Start
35
+
36
+ ### Selectors are JSON-only
37
+
38
+ Providers receive a `selectors` argument that **must be JSON-serializable**. The
39
+ shared alias `SelectorsDict` (see `fetchgraph/json_types.py`) represents
40
+ `Dict[str, JSONValue]` and is used across protocols and models. The planner/LLM
41
+ produces this structure, so do not place runtime-only Python objects (e.g.
42
+ connections, DataFrames) into `selectors`; pass such hints through `**kwargs`
43
+ instead. Providers can publish the expected shape via `ProviderInfo.selectors_schema`
44
+ (a JSON Schema) and optional `examples` containing stringified JSON payloads.
45
+
46
+ Relational providers require `selectors` to include a string field `"op"` that
47
+ chooses the operation (e.g., `"schema"`, `"semantic_only"`, `"query"`). The
48
+ complete set of supported shapes is described by the schema returned from
49
+ `RelationalDataProvider.describe()`.
50
+
51
+ ```python
52
+ from fetchgraph import (
53
+ BaseGraphAgent, ContextPacker, BaselineSpec, ContextFetchSpec,
54
+ TaskProfile, RawLLMOutput
55
+ )
56
+ from fetchgraph.core import make_llm_plan_generic, make_llm_synth_generic
57
+
58
+ # Define providers (implement ContextProvider protocol)
59
+ class SpecProvider:
60
+ name = "spec"
61
+ def fetch(self, feature_name, selectors=None, **kw): return {"content": f"Spec for {feature_name}"}
62
+ def serialize(self, obj): return obj.get("content", "") if isinstance(obj, dict) else str(obj)
63
+
64
+ def dummy_llm(prompt: str, sender: str) -> str:
65
+ if sender == "generic_plan":
66
+ return '{"required_context":["spec"],"context_plan":[{"provider":"spec","mode":"full"}]}'
67
+ if sender == "generic_synth":
68
+ return "result: ok"
69
+ return ""
70
+
71
+ profile = TaskProfile(
72
+ task_name="Demo",
73
+ goal="Produce YAML doc from spec",
74
+ output_format="YAML: result: <...>"
75
+ )
76
+
77
+ agent = BaseGraphAgent(
78
+ llm_plan=make_llm_plan_generic(dummy_llm, profile, {"spec": SpecProvider()}),
79
+ llm_synth=make_llm_synth_generic(dummy_llm, profile),
80
+ domain_parser=lambda raw: raw.text, # RawLLMOutput -> Any
81
+ saver=lambda feature_name, parsed: None, # save side-effect
82
+ providers={"spec": SpecProvider()},
83
+ verifiers=[type("Ok",(),{"name":"ok","check":lambda self,out: []})()],
84
+ packer=ContextPacker(max_tokens=2000, summarizer_llm=lambda t: t[:200]),
85
+ baseline=[BaselineSpec(ContextFetchSpec(provider="spec"))],
86
+ )
87
+
88
+ print(agent.run("FeatureX"))
89
+ ```
90
+
91
+ ## Working with selectors
92
+
93
+ - **Plan-time inputs**: The planner/LLM crafts `selectors` (a `SelectorsDict`) for
94
+ each `ContextFetchSpec`. These inputs must be JSON-serializable and should be
95
+ validated by providers using their published JSON Schema.
96
+ - **Provider contract**: Implementations of `ContextProvider.fetch` should accept
97
+ `selectors: Optional[SelectorsDict] = None` and treat `**kwargs` as optional
98
+ runtime hints that may be non-serializable.
99
+ - **Schema + examples**: Providers can guide planners by returning
100
+ `ProviderInfo(selectors_schema=..., examples=[...])` from `describe()`.
101
+
102
+ Example for a relational provider that requires an `"op"` selector:
103
+
104
+ ```python
105
+ from fetchgraph.json_types import SelectorsDict
106
+ from fetchgraph.models import ProviderInfo
107
+
108
+ class RelationalDataProvider:
109
+ name = "relational"
110
+
111
+ def fetch(self, feature_name: str, selectors: SelectorsDict, **kwargs):
112
+ op = selectors.get("op")
113
+ if not op:
114
+ raise ValueError("selectors.op is required")
115
+ ... # existing logic for schema/semantic_only/query
116
+
117
+ def describe(self) -> ProviderInfo:
118
+ schema = {
119
+ "oneOf": [
120
+ {"type": "object", "required": ["op"], "properties": {"op": {"const": "schema"}}},
121
+ {"type": "object", "required": ["op", "sql"], "properties": {"op": {"const": "query"}, "sql": {"type": "string"}}},
122
+ ]
123
+ }
124
+ return ProviderInfo(
125
+ name=self.name,
126
+ selectors_schema=schema,
127
+ examples=["{\"op\":\"schema\"}", "{\"op\":\"query\",\"sql\":\"select 1\"}"],
128
+ )
129
+ ```
130
+
131
+ During planning you can feed selectors into `ContextFetchSpec` to fix the
132
+ operation:
133
+
134
+ ```python
135
+ fetch_spec = ContextFetchSpec(provider="relational", selectors={"op": "schema"})
136
+ ```
137
+
138
+ ## CSV semantic backend for Pandas providers
139
+
140
+ `fetchgraph.semantic_backend` ships a lightweight TF-IDF backend that turns a CSV
141
+ file into semantic embeddings and reuses them across runs. The flow is:
142
+
143
+ 1. Build embeddings from a CSV once using `CsvEmbeddingBuilder` and persist them
144
+ alongside the CSV.
145
+ 2. Configure a `CsvSemanticBackend` with one or more `CsvSemanticSource` entries
146
+ (one per entity) pointing at the CSV and saved embeddings.
147
+ 3. Pass that backend into `PandasRelationalDataProvider` so semantic clauses can
148
+ delegate matching to the precomputed vectors.
149
+
150
+ Example setup:
151
+
152
+ ```python
153
+ from pathlib import Path
154
+ from fetchgraph.semantic_backend import (
155
+ EmbeddingModel,
156
+ CsvEmbeddingBuilder,
157
+ CsvSemanticBackend,
158
+ CsvSemanticSource,
159
+ )
160
+ from fetchgraph.relational_models import EntityDescriptor, ColumnDescriptor
161
+ from fetchgraph.relational_pandas import PandasRelationalDataProvider
162
+
163
+ csv_path = Path("products.csv")
164
+ embedding_path = Path("products_embeddings.json")
165
+
166
+ # Build once (e.g., during deployment) to avoid recomputing embeddings at runtime.
167
+ CsvEmbeddingBuilder(
168
+ csv_path=csv_path,
169
+ entity="product",
170
+ id_column="id",
171
+ text_fields=["name", "description"],
172
+ output_path=embedding_path,
173
+ ).build()
174
+
175
+ semantic_backend = CsvSemanticBackend(
176
+ {"product": CsvSemanticSource("product", csv_path, embedding_path)}
177
+ )
178
+
179
+ entities = [
180
+ EntityDescriptor(
181
+ name="product",
182
+ columns=[ColumnDescriptor(name="id", role="primary_key"), ColumnDescriptor(name="name"), ColumnDescriptor(name="description")],
183
+ )
184
+ ]
185
+
186
+ provider = PandasRelationalDataProvider(
187
+ name="products", entities=entities, relations=[], frames={"product": ...}, semantic_backend=semantic_backend
188
+ )
189
+ ```
190
+
191
+ You can plug in an embedding model (for example, an OpenAI client) to build and
192
+ query dense embeddings instead of the default TF-IDF vectors:
193
+
194
+ ```python
195
+ from fetchgraph.semantic_backend import (
196
+ EmbeddingModel,
197
+ CsvSemanticSource,
198
+ CsvEmbeddingBuilder,
199
+ CsvSemanticBackend,
200
+ )
201
+
202
+
203
+ class OpenAIEmbeddingModel:
204
+ def __init__(self, client):
205
+ self.client = client
206
+
207
+ def embed_documents(self, texts):
208
+ # replace with client.embeddings(...)
209
+ return [[1.0, 0.0] for _ in texts]
210
+
211
+ def embed_query(self, text):
212
+ return self.embed_documents([text])[0]
213
+
214
+
215
+ embedding = OpenAIEmbeddingModel(client)
216
+
217
+ CsvEmbeddingBuilder(
218
+ csv_path="fbs.csv",
219
+ entity="fbs",
220
+ id_column="id",
221
+ text_fields=["name", "description"],
222
+ output_path="fbs_embeddings.json",
223
+ embedding_model=embedding,
224
+ ).build()
225
+
226
+ csv_backend = CsvSemanticBackend(
227
+ {
228
+ "fbs": CsvSemanticSource(
229
+ entity="fbs",
230
+ csv_path=Path("fbs.csv"),
231
+ embedding_path=Path("fbs_embeddings.json"),
232
+ )
233
+ },
234
+ embedding_model=embedding,
235
+ )
236
+ ```
237
+
238
+ At query time, `SemanticClause` filters sent to the relational provider will
239
+ call `semantic_backend.search(...)` with the requested entity, fields, and
240
+ query text. Fields must be a subset of the indexed CSV columns (not including
241
+ the reserved `__all__` combined projection). By default, field similarities are
242
+ summed; adjust the backend if you need a different aggregation strategy.
243
+
244
+ ### pgvector / LangChain vector stores
245
+
246
+ If you already manage embeddings in PostgreSQL with ``pgvector`` via LangChain,
247
+ you can supply your existing vector stores directly:
248
+
249
+ ```python
250
+ from langchain_community.vectorstores.pgvector import PGVector
251
+ from fetchgraph.semantic_backend import PgVectorSemanticBackend, PgVectorSemanticSource
252
+
253
+ vector_store = PGVector.from_existing_index(
254
+ collection_name="product_vectors", connection_string="postgresql+psycopg://..."
255
+ )
256
+
257
+ semantic_backend = PgVectorSemanticBackend(
258
+ {
259
+ "product": PgVectorSemanticSource(
260
+ entity="product",
261
+ vector_store=vector_store,
262
+ metadata_entity_key="entity", # optional, defaults to "entity"
263
+ metadata_field_key="field", # optional, defaults to "field"
264
+ id_metadata_keys=("id",), # optional metadata key(s) to read the row identifier
265
+ score_kind="distance", # convert pgvector distances into similarity scores
266
+ )
267
+ }
268
+ )
269
+ ```
270
+
271
+ The backend will filter returned documents by entity and requested fields using
272
+ Document metadata before converting scores into :class:`SemanticMatch` entries.
273
+
274
+ ---
275
+
276
+ ## LICENSE
277
+ ```text
278
+ MIT License
279
+
280
+ Copyright (c) 2025 ...
281
+
282
+ Permission is hereby granted, free of charge, to any person obtaining a copy
283
+ ...
284
+ ```
@@ -0,0 +1,38 @@
1
+ [project]
2
+ name = "fetchgraph"
3
+ version = "0.1.1"
4
+ description = "Graph-like planning → context fetching → synthesis agent (library-style)."
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ license = "MIT"
8
+ authors = [{name = "Alexander Onischenko"}]
9
+ keywords = ["agents", "context", "langgraph", "planning", "llm"]
10
+ dependencies = [
11
+ "pydantic>=2.6",
12
+ "pandas>=2.0",
13
+ ]
14
+
15
+ [tool.setuptools.package-data]
16
+ fetchgraph = ["prompts/*.md"]
17
+
18
+ [tool.setuptools]
19
+ package-dir = {"" = "src"}
20
+
21
+ [tool.setuptools.packages.find]
22
+ where = ["src"]
23
+
24
+ [build-system]
25
+ requires = ["setuptools>=77.0.3", "wheel"]
26
+ build-backend = "setuptools.build_meta"
27
+
28
+ [project.optional-dependencies]
29
+ dev = [
30
+ "pytest>=9.0",
31
+ "pre-commit",
32
+ ]
33
+
34
+ [project.urls]
35
+ Homepage = "https://github.com/AlexanderOnischenko/fetchgraph"
36
+ Repository = "https://github.com/AlexanderOnischenko/fetchgraph"
37
+ Documentation = "https://github.com/AlexanderOnischenko/fetchgraph#readme"
38
+ Issues = "https://github.com/AlexanderOnischenko/fetchgraph/issues"