fetchgraph 0.2.0__tar.gz → 0.2.2__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 (120) hide show
  1. fetchgraph-0.2.2/PKG-INFO +491 -0
  2. fetchgraph-0.2.2/README.md +460 -0
  3. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/pyproject.toml +4 -1
  4. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/core/context.py +30 -4
  5. fetchgraph-0.2.2/src/fetchgraph/json_types.py +11 -0
  6. fetchgraph-0.2.2/src/fetchgraph/planning/__init__.py +3 -0
  7. fetchgraph-0.2.2/src/fetchgraph/planning/normalize/__init__.py +15 -0
  8. fetchgraph-0.2.2/src/fetchgraph/planning/normalize/plan_normalizer.py +427 -0
  9. fetchgraph-0.2.2/src/fetchgraph/relational/normalize.py +228 -0
  10. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/providers/base.py +1 -1
  11. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/providers/composite_provider.py +1 -1
  12. fetchgraph-0.2.2/src/fetchgraph/relational_base.py +6 -0
  13. fetchgraph-0.2.2/src/fetchgraph/relational_composite.py +6 -0
  14. fetchgraph-0.2.2/src/fetchgraph/relational_models.py +12 -0
  15. fetchgraph-0.2.2/src/fetchgraph/relational_pandas.py +6 -0
  16. fetchgraph-0.2.2/src/fetchgraph/relational_provider.py +36 -0
  17. fetchgraph-0.2.2/src/fetchgraph/relational_sql.py +6 -0
  18. fetchgraph-0.2.2/src/fetchgraph/replay/__init__.py +12 -0
  19. fetchgraph-0.2.2/src/fetchgraph/replay/export.py +890 -0
  20. fetchgraph-0.2.2/src/fetchgraph/replay/handlers/__init__.py +5 -0
  21. fetchgraph-0.2.2/src/fetchgraph/replay/handlers/plan_normalize.py +96 -0
  22. fetchgraph-0.2.2/src/fetchgraph/replay/log.py +120 -0
  23. fetchgraph-0.2.2/src/fetchgraph/replay/runtime.py +123 -0
  24. fetchgraph-0.2.2/src/fetchgraph/replay/snapshots.py +23 -0
  25. fetchgraph-0.2.2/src/fetchgraph/semantic_backend.py +12 -0
  26. fetchgraph-0.2.2/src/fetchgraph/tracer/__init__.py +15 -0
  27. fetchgraph-0.2.2/src/fetchgraph/tracer/cli.py +847 -0
  28. fetchgraph-0.2.2/src/fetchgraph/tracer/diff_utils.py +29 -0
  29. fetchgraph-0.2.2/src/fetchgraph/tracer/export.py +37 -0
  30. fetchgraph-0.2.2/src/fetchgraph/tracer/fixture_layout.py +112 -0
  31. fetchgraph-0.2.2/src/fetchgraph/tracer/fixture_tools.py +928 -0
  32. fetchgraph-0.2.2/src/fetchgraph/tracer/handlers/__init__.py +5 -0
  33. fetchgraph-0.2.2/src/fetchgraph/tracer/layout.py +4 -0
  34. fetchgraph-0.2.2/src/fetchgraph/tracer/log.py +5 -0
  35. fetchgraph-0.2.2/src/fetchgraph/tracer/resolve.py +965 -0
  36. fetchgraph-0.2.2/src/fetchgraph/tracer/runtime.py +5 -0
  37. fetchgraph-0.2.2/src/fetchgraph/tracer/validators.py +50 -0
  38. fetchgraph-0.2.2/src/fetchgraph/utils/path_layout.py +222 -0
  39. fetchgraph-0.2.2/src/fetchgraph.egg-info/PKG-INFO +491 -0
  40. fetchgraph-0.2.2/src/fetchgraph.egg-info/SOURCES.txt +107 -0
  41. fetchgraph-0.2.2/src/fetchgraph.egg-info/entry_points.txt +2 -0
  42. fetchgraph-0.2.2/src/fetchgraph.egg-info/top_level.txt +1 -0
  43. fetchgraph-0.2.2/tests/test_context_merge.py +73 -0
  44. fetchgraph-0.2.2/tests/test_make_tracer_export.py +39 -0
  45. fetchgraph-0.2.2/tests/test_relational_normalizer_regression.py +291 -0
  46. fetchgraph-0.2.2/tests/test_replay_export_selection.py +220 -0
  47. fetchgraph-0.2.2/tests/test_replay_fixed.py +136 -0
  48. fetchgraph-0.2.2/tests/test_replay_iter_events_bad_json.py +36 -0
  49. fetchgraph-0.2.2/tests/test_replay_known_bad_backlog.py +169 -0
  50. fetchgraph-0.2.2/tests/test_replay_log_trace_truncate.py +29 -0
  51. fetchgraph-0.2.2/tests/test_replay_requires_plan_normalize.py +115 -0
  52. fetchgraph-0.2.2/tests/test_replay_runtime.py +171 -0
  53. fetchgraph-0.2.2/tests/test_tracer_auto_resolve.py +236 -0
  54. fetchgraph-0.2.2/tests/test_tracer_export_input_hash_filter.py +76 -0
  55. fetchgraph-0.2.2/tests/test_tracer_export_list_replay_matches.py +67 -0
  56. fetchgraph-0.2.2/tests/test_tracer_export_provider_specidx_optional.py +76 -0
  57. fetchgraph-0.2.2/tests/test_tracer_export_resolve_latest_with_replay_ignores_provider_specidx.py +87 -0
  58. fetchgraph-0.2.2/tests/test_tracer_export_resolve_prefers_run_with_replay.py +44 -0
  59. fetchgraph-0.2.2/tests/test_tracer_fixture_demote.py +89 -0
  60. fetchgraph-0.2.2/tests/test_tracer_fixture_green_resolve.py +97 -0
  61. fetchgraph-0.2.2/tests/test_tracer_fixture_selector_for_rm_migrate.py +149 -0
  62. fetchgraph-0.2.2/tests/test_tracer_fixture_tools.py +402 -0
  63. fetchgraph-0.2.2/tests/test_tracer_layout.py +60 -0
  64. fetchgraph-0.2.2/tests/test_tracer_print_resolve_reasons.py +75 -0
  65. fetchgraph-0.2.2/tests/test_tracer_replay_id_discovery.py +158 -0
  66. fetchgraph-0.2.2/tests/test_tracer_resolve_parity.py +186 -0
  67. fetchgraph-0.2.2/tests/test_tracer_run_dir_inventory.py +84 -0
  68. fetchgraph-0.2.2/tests/test_tracer_run_dir_sort_key.py +83 -0
  69. fetchgraph-0.2.2/tests/test_tracer_run_id_resolve.py +88 -0
  70. fetchgraph-0.2.0/PKG-INFO +0 -314
  71. fetchgraph-0.2.0/README.md +0 -283
  72. fetchgraph-0.2.0/src/fetchgraph/relational/dsl/__init__.py +0 -1
  73. fetchgraph-0.2.0/src/fetchgraph/relational/dsl/ast.py +0 -0
  74. fetchgraph-0.2.0/src/fetchgraph/relational/dsl/compile.py +0 -0
  75. fetchgraph-0.2.0/src/fetchgraph/relational/dsl/diagnostics.py +0 -0
  76. fetchgraph-0.2.0/src/fetchgraph/relational/dsl/normalize.py +0 -0
  77. fetchgraph-0.2.0/src/fetchgraph/relational/dsl/parser.py +0 -0
  78. fetchgraph-0.2.0/src/fetchgraph.egg-info/PKG-INFO +0 -314
  79. fetchgraph-0.2.0/src/fetchgraph.egg-info/SOURCES.txt +0 -53
  80. fetchgraph-0.2.0/src/fetchgraph.egg-info/top_level.txt +0 -2
  81. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/LICENSE +0 -0
  82. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/MANIFEST.in +0 -0
  83. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/setup.cfg +0 -0
  84. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/__init__.py +0 -0
  85. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/core/__init__.py +0 -0
  86. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/core/models.py +0 -0
  87. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/core/protocols.py +0 -0
  88. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/core/utils.py +0 -0
  89. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/parsing/__init__.py +0 -0
  90. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/parsing/exceptions.py +0 -0
  91. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/parsing/extract_json.py +0 -0
  92. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/parsing/json_parser.py +0 -0
  93. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/parsing/plan_parser.py +0 -0
  94. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/prompts/plan_generic.md +0 -0
  95. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/prompts/synth_generic.md +0 -0
  96. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/providers/__init__.py +0 -0
  97. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/__init__.py +0 -0
  98. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/models.py +0 -0
  99. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/providers/__init__.py +0 -0
  100. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/providers/pandas_provider.py +0 -0
  101. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/providers/sql/__init__.py +0 -0
  102. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/providers/sql/builder.py +0 -0
  103. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/providers/sql/dialects.py +0 -0
  104. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/providers/sql_provider.py +0 -0
  105. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/schema.py +0 -0
  106. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/semantic/__init__.py +0 -0
  107. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/semantic/backend.py +0 -0
  108. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/relational/types.py +0 -0
  109. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/utils/__init__.py +0 -0
  110. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph/utils/log_context.py +0 -0
  111. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph.egg-info/dependency_links.txt +0 -0
  112. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/src/fetchgraph.egg-info/requires.txt +0 -0
  113. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/tests/test_relational_base.py +0 -0
  114. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/tests/test_relational_composite.py +0 -0
  115. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/tests/test_relational_composite_cross_provider.py +0 -0
  116. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/tests/test_relational_pandas.py +0 -0
  117. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/tests/test_relational_sql.py +0 -0
  118. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/tests/test_semantic_backend_csv.py +0 -0
  119. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/tests/test_semantic_backend_pgvector.py +0 -0
  120. {fetchgraph-0.2.0 → fetchgraph-0.2.2}/tests/test_streaming_cross_joins.py +0 -0
@@ -0,0 +1,491 @@
1
+ Metadata-Version: 2.4
2
+ Name: fetchgraph
3
+ Version: 0.2.2
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.11
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
+ Requires-Dist: pydantic-settings>=2.2; extra == "dev"
21
+ Requires-Dist: python-dotenv>=1.0; extra == "dev"
22
+ Requires-Dist: ruff; extra == "dev"
23
+ Requires-Dist: pyright; extra == "dev"
24
+ Requires-Dist: build; extra == "dev"
25
+ Requires-Dist: twine; extra == "dev"
26
+ Provides-Extra: demo
27
+ Requires-Dist: pydantic-settings>=2.12; extra == "demo"
28
+ Requires-Dist: python-dotenv>=1.0; extra == "demo"
29
+ Requires-Dist: openai; extra == "demo"
30
+ Dynamic: license-file
31
+
32
+ # FetchGraph
33
+
34
+ **One semantic access layer for your AI agents.**
35
+
36
+ > **Describe your data once. Let any agent query it.**
37
+
38
+ AI agents can already call databases, APIs, vector stores, and MCP tools.
39
+
40
+ The harder problem is teaching every agent what your data **means**:
41
+
42
+ - where customers, orders, products, documents, or metrics live,
43
+ - how those entities relate,
44
+ - which fields and operations are valid,
45
+ - and how a natural-language question should be translated into retrieval.
46
+
47
+ If every agent has to rediscover that from raw schemas and tool descriptions, the same retrieval logic gets rebuilt again and again.
48
+
49
+ FetchGraph moves that knowledge into a reusable layer.
50
+
51
+ ```text
52
+ Agents / Copilots / Workflows
53
+ │
54
+ ▼
55
+ ┌─────────────┐
56
+ │ FetchGraph │
57
+ │ semantic │
58
+ │ access layer│
59
+ └──────┬──────┘
60
+ │
61
+ ┌───────┼────────┐
62
+ ▼ ▼ ▼
63
+ SQL APIs RAG
64
+ / files
65
+ ```
66
+
67
+ You describe each data source as a **provider**: what it contains, what it can do, and how it may be queried.
68
+
69
+ Given a natural-language task, FetchGraph can then:
70
+
71
+ 1. decide which providers are relevant,
72
+ 2. build a structured retrieval plan,
73
+ 3. validate and normalize provider-specific selectors,
74
+ 4. fetch the required data,
75
+ 5. fit the evidence into a context budget,
76
+ 6. and pass the assembled context to an LLM to produce the result.
77
+
78
+ The goal is simple:
79
+
80
+ > Adding the second, tenth, or hundredth agent should not require teaching each of them your data architecture again.
81
+
82
+ ---
83
+
84
+ ## Why FetchGraph?
85
+
86
+ Imagine your company has:
87
+
88
+ - customers in one database,
89
+ - orders in another,
90
+ - product information behind an API,
91
+ - documentation in a vector index,
92
+ - and several agents that need different combinations of that data.
93
+
94
+ You *can* give every agent direct access to all of those systems and let it figure everything out at runtime.
95
+
96
+ That works well for simple cases.
97
+
98
+ But as data sources and agents multiply, every agent starts solving the same questions:
99
+
100
+ ```text
101
+ Where does this information live?
102
+ Which entity should I query?
103
+ Which relation should I follow?
104
+ Which filters are valid?
105
+ Do I need SQL, semantic search, or both?
106
+ ```
107
+
108
+ FetchGraph makes those answers reusable.
109
+
110
+ For example, a provider can describe a relational source roughly as:
111
+
112
+ ```text
113
+ Customers
114
+ - id
115
+ - segment
116
+ - country
117
+
118
+ Orders
119
+ - customer_id
120
+ - order_date
121
+ - amount
122
+
123
+ Customer -> Orders via customer_id
124
+
125
+ Supported operations:
126
+ - filter
127
+ - relation traversal
128
+ - aggregation
129
+ - semantic search
130
+ ```
131
+
132
+ Then an application can ask:
133
+
134
+ > Which products grew fastest among enterprise customers in Germany last quarter?
135
+
136
+ The planner can use the provider descriptions to determine the relevant entities, relations, filters, and aggregations instead of requiring that logic to be hard-coded into the application.
137
+
138
+ ---
139
+
140
+ ## FetchGraph vs. MCP, direct SQL, and RAG
141
+
142
+ FetchGraph is not intended to replace any of them.
143
+
144
+ ### MCP
145
+
146
+ MCP is a great way to expose tools and resources to agents.
147
+
148
+ FetchGraph solves a different problem:
149
+
150
+ ```text
151
+ MCP: What can the agent call?
152
+ FetchGraph: What information does this task need, and how should it be retrieved?
153
+ ```
154
+
155
+ A FetchGraph application can be wrapped as a tool or exposed over MCP so multiple agents share the same data model and retrieval behavior.
156
+
157
+ ### Direct SQL
158
+
159
+ For one agent and one well-understood database, letting the model inspect the schema and write SQL directly may be simpler.
160
+
161
+ FetchGraph becomes useful when you want the knowledge about entities, relations, valid operations, and retrieval rules to be **shared across agents and sources**, rather than rediscovered by every model invocation.
162
+
163
+ ### RAG
164
+
165
+ Traditional RAG is excellent when the problem is:
166
+
167
+ ```text
168
+ question -> similarity search -> chunks -> prompt
169
+ ```
170
+
171
+ FetchGraph is useful when retrieval also involves structured operations:
172
+
173
+ ```text
174
+ intent
175
+ -> choose source
176
+ -> choose entities
177
+ -> filters / relations / aggregations / semantic search
178
+ -> fetch evidence
179
+ -> context
180
+ ```
181
+
182
+ Vector search can simply be one of the provider capabilities.
183
+
184
+ ---
185
+
186
+ ## Core abstraction: providers
187
+
188
+ A provider exposes two things:
189
+
190
+ ### 1. How to fetch data
191
+
192
+ ```python
193
+ provider.fetch(
194
+ feature_name,
195
+ selectors={...},
196
+ )
197
+ ```
198
+
199
+ ### 2. How the planner is allowed to query it
200
+
201
+ ```python
202
+ ProviderInfo(
203
+ name="orders",
204
+ description="Orders and customer purchases",
205
+ capabilities=["query", "aggregate"],
206
+ selectors_schema={...},
207
+ examples=[...],
208
+ )
209
+ ```
210
+
211
+ FetchGraph builds a catalog from these descriptions and gives it to the planner.
212
+
213
+ The planner produces structured fetch specifications rather than arbitrary application code:
214
+
215
+ ```json
216
+ {
217
+ "required_context": ["orders"],
218
+ "context_plan": [
219
+ {
220
+ "provider": "orders",
221
+ "mode": "slice",
222
+ "selectors": {
223
+ "op": "query",
224
+ "root_entity": "orders",
225
+ "limit": 20
226
+ },
227
+ "max_tokens": 2000
228
+ }
229
+ ]
230
+ }
231
+ ```
232
+
233
+ Providers remain responsible for executing those selectors against the real system.
234
+
235
+ That means a provider may wrap a database client, an ODBC connection, an HTTP API, a vector store, a local dataframe, or another retrieval system without exposing those runtime objects to the planner.
236
+
237
+ ---
238
+
239
+ # Quick start
240
+
241
+ ## Install
242
+
243
+ ```bash
244
+ pip install fetchgraph
245
+ ```
246
+
247
+ Connect your LLM and expose a data source through a provider:
248
+
249
+ ```python
250
+ import json
251
+
252
+ from fetchgraph import (
253
+ ProviderInfo,
254
+ TaskProfile,
255
+ create_generic_agent,
256
+ )
257
+
258
+
259
+ class CustomerProvider:
260
+ name = "customers"
261
+
262
+ def describe(self) -> ProviderInfo:
263
+ return ProviderInfo(
264
+ name=self.name,
265
+ description="Customer accounts, subscriptions, and billing history.",
266
+ capabilities=["lookup"],
267
+ selectors_schema={
268
+ "type": "object",
269
+ "properties": {
270
+ "customer_id": {"type": "string"},
271
+ },
272
+ "additionalProperties": False,
273
+ },
274
+ examples=[
275
+ '{"customer_id": "cus_123"}',
276
+ ],
277
+ )
278
+
279
+ def fetch(self, feature_name, selectors=None, **kwargs):
280
+ customer_id = (selectors or {}).get("customer_id")
281
+
282
+ # Replace with your DB/API call.
283
+ return load_customer(customer_id)
284
+
285
+ def serialize(self, obj):
286
+ return json.dumps(obj, default=str)
287
+
288
+
289
+ def llm(prompt: str, sender: str) -> str:
290
+ # OpenAI, Anthropic, a local model, LiteLLM, etc.
291
+ return my_model(prompt)
292
+
293
+
294
+ agent = create_generic_agent(
295
+ llm_invoke=llm,
296
+ providers={
297
+ "customers": CustomerProvider(),
298
+ },
299
+ task_profile=TaskProfile(
300
+ task_name="Customer support",
301
+ goal="Answer questions using available customer data.",
302
+ output_format="Plain text",
303
+ ),
304
+ saver=lambda name, result: None,
305
+ )
306
+
307
+ answer = agent.run(
308
+ "Why was customer cus_123 charged twice?"
309
+ )
310
+
311
+ print(answer)
312
+ ```
313
+
314
+ The application does not hard-code when the customer provider should be used or which selector should be sent.
315
+
316
+ The provider describes itself:
317
+
318
+ ```text
319
+ customers
320
+ ├── what data it contains
321
+ ├── what it can do
322
+ ├── selector schema
323
+ └── examples
324
+ ```
325
+
326
+ The planner uses that contract to decide whether the provider is needed and how to query it.
327
+
328
+ ---
329
+
330
+ ## What happens during a run?
331
+
332
+ The generic agent follows this flow:
333
+
334
+ ```text
335
+ TASK
336
+ │
337
+ ▼
338
+ PLAN
339
+ │ choose providers + selectors
340
+ ▼
341
+ FETCH
342
+ │ execute provider contracts
343
+ ▼
344
+ PACK
345
+ │ keep context within a token budget
346
+ ▼
347
+ ASSESS / REFETCH (optional)
348
+ │
349
+ ▼
350
+ SYNTHESIZE
351
+ │
352
+ ▼
353
+ VERIFY / REFINE (optional)
354
+ │
355
+ ▼
356
+ RESULT
357
+ ```
358
+
359
+ The planning and retrieval steps are explicit, which makes them easier to inspect and evaluate separately from final answer generation.
360
+
361
+ ---
362
+
363
+ ## Relational data
364
+
365
+ FetchGraph includes relational abstractions for structured business data.
366
+
367
+ The public API includes:
368
+
369
+ - `EntityDescriptor`
370
+ - `ColumnDescriptor`
371
+ - `RelationDescriptor`
372
+ - `RelationalDataProvider`
373
+ - `SqlRelationalDataProvider`
374
+ - `PandasRelationalDataProvider`
375
+ - `CompositeRelationalProvider`
376
+
377
+ Relational providers can describe entities and relations to the planner and support structured operations such as filtering, selecting fields, aggregations, relation traversal, and semantic clauses.
378
+
379
+ Internally, the planning pipeline can normalize selectors, validate them, bind field references to the schema, normalize aggregations, and retry planning when a generated plan cannot be executed.
380
+
381
+ This is the main reason to use FetchGraph instead of simply putting a raw database schema into every agent prompt: the data-access model becomes a reusable contract with a validation and execution layer behind it.
382
+
383
+ ---
384
+
385
+ ## Semantic retrieval
386
+
387
+ Semantic search is a provider capability rather than a special application architecture.
388
+
389
+ FetchGraph currently includes:
390
+
391
+ - a lightweight CSV semantic backend for Pandas providers,
392
+ - pluggable embedding models,
393
+ - pgvector / LangChain vector-store integration,
394
+ - semantic clauses inside relational requests.
395
+
396
+ This allows an application to combine structured and semantic retrieval rather than choosing between "SQL" and "RAG" at the application level.
397
+
398
+ ---
399
+
400
+ ## Selectors
401
+
402
+ Provider selectors are JSON-serializable structures generated during planning.
403
+
404
+ ```python
405
+ ContextFetchSpec(
406
+ provider="orders",
407
+ mode="slice",
408
+ selectors={
409
+ "op": "query",
410
+ "root_entity": "orders",
411
+ },
412
+ )
413
+ ```
414
+
415
+ Providers can publish the expected selector shape through `ProviderInfo.selectors_schema` and examples through `ProviderInfo.examples`.
416
+
417
+ Runtime-only Python objects such as database connections, DataFrames, or model clients should stay inside the provider or be passed as runtime hints — not inside planner-generated selectors.
418
+
419
+ ---
420
+
421
+ ## Current capabilities
422
+
423
+ - schema-driven provider catalog
424
+ - LLM-generated structured retrieval plans
425
+ - pluggable providers for heterogeneous sources
426
+ - JSON Schema-guided selectors
427
+ - relational entities and relations
428
+ - filtering and aggregations
429
+ - structured + semantic retrieval
430
+ - SQL and Pandas relational providers
431
+ - composite relational providers
432
+ - bounded context packing
433
+ - optional assess/refetch loop
434
+ - optional verification/refinement
435
+ - replay / planning diagnostics in the normalization pipeline
436
+ - no agent-framework lock-in
437
+
438
+ ---
439
+
440
+ ## When should I use FetchGraph?
441
+
442
+ FetchGraph is a good fit when:
443
+
444
+ - several agents need access to the same corporate data,
445
+ - data is spread across heterogeneous systems,
446
+ - questions require more than document similarity search,
447
+ - structured filters, joins, or aggregations matter,
448
+ - you want retrieval logic to be inspectable and reusable,
449
+ - or you want to separate context planning from the main agent reasoning loop.
450
+
451
+ You probably do **not** need FetchGraph if:
452
+
453
+ - you have one small corpus and ordinary top-k RAG is enough,
454
+ - you have one simple database and are happy to let one strong model write SQL directly,
455
+ - or there is no meaningful data model worth sharing across applications.
456
+
457
+ ---
458
+
459
+ ## Examples
460
+
461
+ Working examples live under:
462
+
463
+ ```text
464
+ examples/
465
+ ├── demo_qa/
466
+ └── retail_orders/
467
+ ```
468
+
469
+ `examples/demo_qa` contains a schema-driven QA testbed with planning artifacts and evaluation cases.
470
+
471
+ `examples/retail_orders` demonstrates questions over relational business data.
472
+
473
+ ---
474
+
475
+ ## Direction
476
+
477
+ The long-term direction is to make the semantic layer cheaper to create and richer to reuse.
478
+
479
+ One natural extension is **schema introspection and ontology-assisted provider generation**: deriving an initial agent-readable model from database schemas, relationships, metadata, and existing corporate glossaries, then letting humans enrich it where business semantics cannot be inferred reliably.
480
+
481
+ That is a direction, not a requirement for using FetchGraph today.
482
+
483
+ The core invariant remains:
484
+
485
+ > **Describe your data once. Reuse that knowledge across agents.**
486
+
487
+ ---
488
+
489
+ ## License
490
+
491
+ MIT