fetchgraph 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fetchgraph-0.0.1/LICENSE +3 -0
- fetchgraph-0.0.1/PKG-INFO +77 -0
- fetchgraph-0.0.1/README.md +64 -0
- fetchgraph-0.0.1/pyproject.toml +19 -0
- fetchgraph-0.0.1/setup.cfg +4 -0
- fetchgraph-0.0.1/src/fetchgraph/__init__.py +43 -0
- fetchgraph-0.0.1/src/fetchgraph/core.py +424 -0
- fetchgraph-0.0.1/src/fetchgraph/prompts/plan_generic.md +40 -0
- fetchgraph-0.0.1/src/fetchgraph/prompts/synth_generic.md +23 -0
- fetchgraph-0.0.1/src/fetchgraph/utils.py +15 -0
- fetchgraph-0.0.1/src/fetchgraph.egg-info/PKG-INFO +77 -0
- fetchgraph-0.0.1/src/fetchgraph.egg-info/SOURCES.txt +13 -0
- fetchgraph-0.0.1/src/fetchgraph.egg-info/dependency_links.txt +1 -0
- fetchgraph-0.0.1/src/fetchgraph.egg-info/requires.txt +1 -0
- fetchgraph-0.0.1/src/fetchgraph.egg-info/top_level.txt +1 -0
fetchgraph-0.0.1/LICENSE
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fetchgraph
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: Graph-like planning → context fetching → synthesis agent (library-style).
|
|
5
|
+
Author: Alexander Onischenko
|
|
6
|
+
License: MIT
|
|
7
|
+
Keywords: agents,context,langgraph,planning,llm
|
|
8
|
+
Requires-Python: >=3.10
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Requires-Dist: pydantic>=2.6
|
|
12
|
+
Dynamic: license-file
|
|
13
|
+
|
|
14
|
+
# fetchgraph
|
|
15
|
+
|
|
16
|
+
Universal, library-style agent that plans what to fetch, fetches context from pluggable providers, and synthesizes an output.
|
|
17
|
+
|
|
18
|
+
**Pipeline:** PLAN → FETCH → (ASSESS/REFETCH)* → SYNTH → VERIFY → (REFINE)* → SAVE
|
|
19
|
+
|
|
20
|
+
## Install (dev)
|
|
21
|
+
```bash
|
|
22
|
+
pip install -e .
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
# Quick Start
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
from fetchgraph import (
|
|
29
|
+
BaseGraphAgent, ContextPacker, BaselineSpec, ContextFetchSpec,
|
|
30
|
+
TaskProfile, RawLLMOutput
|
|
31
|
+
)
|
|
32
|
+
from fetchgraph.core import make_llm_plan_generic, make_llm_synth_generic
|
|
33
|
+
|
|
34
|
+
# Define providers (implement ContextProvider protocol)
|
|
35
|
+
class SpecProvider:
|
|
36
|
+
name = "spec"
|
|
37
|
+
def fetch(self, feature_name, selectors=None, **kw): return {"content": f"Spec for {feature_name}"}
|
|
38
|
+
def serialize(self, obj): return obj.get("content", "") if isinstance(obj, dict) else str(obj)
|
|
39
|
+
|
|
40
|
+
def dummy_llm(prompt: str, sender: str) -> str:
|
|
41
|
+
if sender == "generic_plan":
|
|
42
|
+
return '{"required_context":["spec"],"context_plan":[{"provider":"spec","mode":"full"}]}'
|
|
43
|
+
if sender == "generic_synth":
|
|
44
|
+
return "result: ok"
|
|
45
|
+
return ""
|
|
46
|
+
|
|
47
|
+
profile = TaskProfile(
|
|
48
|
+
task_name="Demo",
|
|
49
|
+
goal="Produce YAML doc from spec",
|
|
50
|
+
output_format="YAML: result: <...>"
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
agent = BaseGraphAgent(
|
|
54
|
+
llm_plan=make_llm_plan_generic(dummy_llm, profile, {"spec": SpecProvider()}),
|
|
55
|
+
llm_synth=make_llm_synth_generic(dummy_llm, profile),
|
|
56
|
+
domain_parser=lambda raw: raw.text, # RawLLMOutput -> Any
|
|
57
|
+
saver=lambda feature_name, parsed: None, # save side-effect
|
|
58
|
+
providers={"spec": SpecProvider()},
|
|
59
|
+
verifiers=[type("Ok",(),{"name":"ok","check":lambda self,out: []})()],
|
|
60
|
+
packer=ContextPacker(max_tokens=2000, summarizer_llm=lambda t: t[:200]),
|
|
61
|
+
baseline=[BaselineSpec(ContextFetchSpec(provider="spec"))],
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
print(agent.run("FeatureX"))
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## LICENSE
|
|
70
|
+
```text
|
|
71
|
+
MIT License
|
|
72
|
+
|
|
73
|
+
Copyright (c) 2025 ...
|
|
74
|
+
|
|
75
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
76
|
+
...
|
|
77
|
+
```
|
|
@@ -0,0 +1,64 @@
|
|
|
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
|
+
## Install (dev)
|
|
8
|
+
```bash
|
|
9
|
+
pip install -e .
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
# Quick Start
|
|
13
|
+
|
|
14
|
+
```python
|
|
15
|
+
from fetchgraph import (
|
|
16
|
+
BaseGraphAgent, ContextPacker, BaselineSpec, ContextFetchSpec,
|
|
17
|
+
TaskProfile, RawLLMOutput
|
|
18
|
+
)
|
|
19
|
+
from fetchgraph.core import make_llm_plan_generic, make_llm_synth_generic
|
|
20
|
+
|
|
21
|
+
# Define providers (implement ContextProvider protocol)
|
|
22
|
+
class SpecProvider:
|
|
23
|
+
name = "spec"
|
|
24
|
+
def fetch(self, feature_name, selectors=None, **kw): return {"content": f"Spec for {feature_name}"}
|
|
25
|
+
def serialize(self, obj): return obj.get("content", "") if isinstance(obj, dict) else str(obj)
|
|
26
|
+
|
|
27
|
+
def dummy_llm(prompt: str, sender: str) -> str:
|
|
28
|
+
if sender == "generic_plan":
|
|
29
|
+
return '{"required_context":["spec"],"context_plan":[{"provider":"spec","mode":"full"}]}'
|
|
30
|
+
if sender == "generic_synth":
|
|
31
|
+
return "result: ok"
|
|
32
|
+
return ""
|
|
33
|
+
|
|
34
|
+
profile = TaskProfile(
|
|
35
|
+
task_name="Demo",
|
|
36
|
+
goal="Produce YAML doc from spec",
|
|
37
|
+
output_format="YAML: result: <...>"
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
agent = BaseGraphAgent(
|
|
41
|
+
llm_plan=make_llm_plan_generic(dummy_llm, profile, {"spec": SpecProvider()}),
|
|
42
|
+
llm_synth=make_llm_synth_generic(dummy_llm, profile),
|
|
43
|
+
domain_parser=lambda raw: raw.text, # RawLLMOutput -> Any
|
|
44
|
+
saver=lambda feature_name, parsed: None, # save side-effect
|
|
45
|
+
providers={"spec": SpecProvider()},
|
|
46
|
+
verifiers=[type("Ok",(),{"name":"ok","check":lambda self,out: []})()],
|
|
47
|
+
packer=ContextPacker(max_tokens=2000, summarizer_llm=lambda t: t[:200]),
|
|
48
|
+
baseline=[BaselineSpec(ContextFetchSpec(provider="spec"))],
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
print(agent.run("FeatureX"))
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## LICENSE
|
|
57
|
+
```text
|
|
58
|
+
MIT License
|
|
59
|
+
|
|
60
|
+
Copyright (c) 2025 ...
|
|
61
|
+
|
|
62
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
63
|
+
...
|
|
64
|
+
```
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "fetchgraph"
|
|
3
|
+
version = "0.0.1"
|
|
4
|
+
description = "Graph-like planning → context fetching → synthesis agent (library-style)."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.10"
|
|
7
|
+
license = {text = "MIT"}
|
|
8
|
+
authors = [{name = "Alexander Onischenko"}]
|
|
9
|
+
keywords = ["agents", "context", "langgraph", "planning", "llm"]
|
|
10
|
+
dependencies = [
|
|
11
|
+
"pydantic>=2.6",
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
[tool.setuptools.package-data]
|
|
15
|
+
fetchgraph = ["prompts/*.md"]
|
|
16
|
+
|
|
17
|
+
[build-system]
|
|
18
|
+
requires = ["setuptools>=67", "wheel"]
|
|
19
|
+
build-backend = "setuptools.build_meta"
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
from .core import (
|
|
2
|
+
# types
|
|
3
|
+
RawLLMOutput,
|
|
4
|
+
ProviderInfo,
|
|
5
|
+
TaskProfile,
|
|
6
|
+
ContextFetchSpec,
|
|
7
|
+
BaselineSpec,
|
|
8
|
+
ContextItem,
|
|
9
|
+
RefetchDecision,
|
|
10
|
+
Plan,
|
|
11
|
+
# protocols
|
|
12
|
+
ContextProvider,
|
|
13
|
+
SupportsFilter,
|
|
14
|
+
SupportsDescribe,
|
|
15
|
+
Verifier,
|
|
16
|
+
Saver,
|
|
17
|
+
# classes
|
|
18
|
+
ContextPacker,
|
|
19
|
+
BaseGraphAgent,
|
|
20
|
+
# helpers
|
|
21
|
+
make_llm_plan_generic,
|
|
22
|
+
make_llm_synth_generic,
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
__all__ = [
|
|
26
|
+
"RawLLMOutput",
|
|
27
|
+
"ProviderInfo",
|
|
28
|
+
"TaskProfile",
|
|
29
|
+
"ContextFetchSpec",
|
|
30
|
+
"BaselineSpec",
|
|
31
|
+
"ContextItem",
|
|
32
|
+
"RefetchDecision",
|
|
33
|
+
"Plan",
|
|
34
|
+
"ContextProvider",
|
|
35
|
+
"SupportsFilter",
|
|
36
|
+
"SupportsDescribe",
|
|
37
|
+
"Verifier",
|
|
38
|
+
"Saver",
|
|
39
|
+
"ContextPacker",
|
|
40
|
+
"BaseGraphAgent",
|
|
41
|
+
"make_llm_plan_generic",
|
|
42
|
+
"make_llm_synth_generic",
|
|
43
|
+
]
|
|
@@ -0,0 +1,424 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
from dataclasses import dataclass
|
|
3
|
+
from typing import Any, Dict, List, Optional, Protocol, Callable, runtime_checkable, overload
|
|
4
|
+
|
|
5
|
+
from pydantic import BaseModel, Field
|
|
6
|
+
import json
|
|
7
|
+
|
|
8
|
+
from .utils import load_pkg_text, render_prompt
|
|
9
|
+
|
|
10
|
+
# -----------------------------------------------------------------------------
|
|
11
|
+
# Basic normalized LLM output
|
|
12
|
+
# -----------------------------------------------------------------------------
|
|
13
|
+
class RawLLMOutput(BaseModel):
|
|
14
|
+
text: str
|
|
15
|
+
|
|
16
|
+
def normalize_llm_output(raw: Any) -> RawLLMOutput:
|
|
17
|
+
if isinstance(raw, RawLLMOutput):
|
|
18
|
+
return raw
|
|
19
|
+
if isinstance(raw, str):
|
|
20
|
+
return RawLLMOutput(text=raw)
|
|
21
|
+
# dict-like?
|
|
22
|
+
if isinstance(raw, dict):
|
|
23
|
+
for k in ("text", "output", "content"):
|
|
24
|
+
if k in raw and isinstance(raw[k], str):
|
|
25
|
+
return RawLLMOutput(text=raw[k])
|
|
26
|
+
return RawLLMOutput(text=json.dumps(raw, ensure_ascii=False))
|
|
27
|
+
# fallback
|
|
28
|
+
return RawLLMOutput(text=str(raw))
|
|
29
|
+
|
|
30
|
+
# -----------------------------------------------------------------------------
|
|
31
|
+
# Task profile & provider descriptors
|
|
32
|
+
# -----------------------------------------------------------------------------
|
|
33
|
+
class TaskProfile(BaseModel):
|
|
34
|
+
task_name: str = "Generic Task"
|
|
35
|
+
goal: str = "Synthesize output based on fetched context"
|
|
36
|
+
output_format: str = "{}"
|
|
37
|
+
acceptance_criteria: List[str] = Field(default_factory=list)
|
|
38
|
+
constraints: List[str] = Field(default_factory=list)
|
|
39
|
+
focus_hints: List[str] = Field(default_factory=list)
|
|
40
|
+
lite_context_keys: List[str] = Field(default_factory=list)
|
|
41
|
+
|
|
42
|
+
class ProviderInfo(BaseModel):
|
|
43
|
+
name: str
|
|
44
|
+
description: str = ""
|
|
45
|
+
selectors_schema: Dict[str, Any] = Field(default_factory=dict)
|
|
46
|
+
capabilities: List[str] = Field(default_factory=list) # e.g. ["slice","filter","search"]
|
|
47
|
+
examples: List[str] = Field(default_factory=list)
|
|
48
|
+
typical_cost: Optional[str] = None # "cheap|moderate|expensive"
|
|
49
|
+
|
|
50
|
+
class LLMInvoke(Protocol):
|
|
51
|
+
# 1) позиционный sender
|
|
52
|
+
@overload
|
|
53
|
+
def __call__(self, prompt: str, /, sender: str) -> str: ...
|
|
54
|
+
# 2) keyword-only sender
|
|
55
|
+
@overload
|
|
56
|
+
def __call__(self, prompt: str, *, sender: str) -> str: ...
|
|
57
|
+
# реальная сигнатура (наиболее общая)
|
|
58
|
+
def __call__(self, *args: Any, **kwargs: Any) -> str: ...
|
|
59
|
+
|
|
60
|
+
class ContextItem(BaseModel):
|
|
61
|
+
key: str
|
|
62
|
+
raw: Any
|
|
63
|
+
text: str
|
|
64
|
+
tokens: int
|
|
65
|
+
|
|
66
|
+
# For maximum reuse, provider type is a free string:
|
|
67
|
+
ProviderType = str
|
|
68
|
+
|
|
69
|
+
class ContextFetchSpec(BaseModel):
|
|
70
|
+
provider: ProviderType
|
|
71
|
+
mode: str = "full" # "full" | "slice"
|
|
72
|
+
selectors: Dict[str, Any] = Field(default_factory=dict)
|
|
73
|
+
max_tokens: Optional[int] = None
|
|
74
|
+
|
|
75
|
+
@dataclass(frozen=True)
|
|
76
|
+
class BaselineSpec:
|
|
77
|
+
spec: ContextFetchSpec
|
|
78
|
+
required: bool = True
|
|
79
|
+
|
|
80
|
+
class Plan(BaseModel):
|
|
81
|
+
required_context: List[ProviderType] = Field(default_factory=list)
|
|
82
|
+
context_plan: List[ContextFetchSpec] = Field(default_factory=list)
|
|
83
|
+
adr_queries: Optional[List[str]] = None
|
|
84
|
+
constraints: Optional[List[str]] = None
|
|
85
|
+
# optional sketch fields kept for compatibility/inspection
|
|
86
|
+
entities: List[Dict[str, Any]] = Field(default_factory=list)
|
|
87
|
+
dtos: List[Dict[str, Any]] = Field(default_factory=list)
|
|
88
|
+
|
|
89
|
+
class RefetchDecision(BaseModel):
|
|
90
|
+
add_specs: List[ContextFetchSpec] = Field(default_factory=list)
|
|
91
|
+
stop: bool = True
|
|
92
|
+
notes: Optional[str] = None
|
|
93
|
+
|
|
94
|
+
# -----------------------------------------------------------------------------
|
|
95
|
+
# Protocols
|
|
96
|
+
# -----------------------------------------------------------------------------
|
|
97
|
+
class Verifier(Protocol):
|
|
98
|
+
name: str
|
|
99
|
+
def check(self, output_text: RawLLMOutput) -> List[str]: ...
|
|
100
|
+
|
|
101
|
+
class Saver(Protocol):
|
|
102
|
+
def save(self, feature_name: str, parsed: Any) -> None: ...
|
|
103
|
+
|
|
104
|
+
class ContextProvider(Protocol):
|
|
105
|
+
name: str
|
|
106
|
+
def fetch(self, feature_name: str, selectors: Optional[Dict[str, Any]] = None, **kwargs) -> Any: ...
|
|
107
|
+
def serialize(self, obj: Any) -> str: ...
|
|
108
|
+
|
|
109
|
+
@runtime_checkable
|
|
110
|
+
class SupportsFilter(Protocol):
|
|
111
|
+
def filter(self, obj: Any, selectors: Optional[Dict[str, Any]] = None) -> Any: ...
|
|
112
|
+
|
|
113
|
+
@runtime_checkable
|
|
114
|
+
class SupportsDescribe(Protocol):
|
|
115
|
+
def describe(self) -> ProviderInfo: ...
|
|
116
|
+
|
|
117
|
+
# -----------------------------------------------------------------------------
|
|
118
|
+
# Helpers
|
|
119
|
+
# -----------------------------------------------------------------------------
|
|
120
|
+
def _apply_provider_filter(provider: ContextProvider, obj: Any, selectors: Optional[Dict[str, Any]]):
|
|
121
|
+
if isinstance(provider, SupportsFilter):
|
|
122
|
+
return provider.filter(obj, selectors)
|
|
123
|
+
return obj
|
|
124
|
+
|
|
125
|
+
def provider_catalog_text(providers: Dict[str, ContextProvider]) -> str:
|
|
126
|
+
lines: List[str] = []
|
|
127
|
+
for key, prov in providers.items():
|
|
128
|
+
info: Optional[ProviderInfo] = None
|
|
129
|
+
if isinstance(prov, SupportsDescribe):
|
|
130
|
+
try:
|
|
131
|
+
info = prov.describe()
|
|
132
|
+
except Exception:
|
|
133
|
+
info = None
|
|
134
|
+
if info is None:
|
|
135
|
+
caps = []
|
|
136
|
+
if isinstance(prov, SupportsFilter):
|
|
137
|
+
caps = ["filter", "slice"]
|
|
138
|
+
info = ProviderInfo(name=getattr(prov, "name", key), capabilities=caps)
|
|
139
|
+
|
|
140
|
+
lines.append(f"- name: {info.name}")
|
|
141
|
+
if info.description:
|
|
142
|
+
lines.append(f" description: {info.description}")
|
|
143
|
+
if info.capabilities:
|
|
144
|
+
lines.append(f" capabilities: {', '.join(info.capabilities)}")
|
|
145
|
+
if info.typical_cost:
|
|
146
|
+
lines.append(f" typical_cost: {info.typical_cost}")
|
|
147
|
+
if info.selectors_schema:
|
|
148
|
+
schema = json.dumps(info.selectors_schema, ensure_ascii=False, indent=2)
|
|
149
|
+
lines.append(" selectors_schema:")
|
|
150
|
+
lines += [f" {ln}" for ln in schema.splitlines()]
|
|
151
|
+
if info.examples:
|
|
152
|
+
lines.append(" examples:")
|
|
153
|
+
lines += [f" - {ex}" for ex in info.examples]
|
|
154
|
+
return "\n".join(lines) if lines else "(no providers)"
|
|
155
|
+
|
|
156
|
+
# -----------------------------------------------------------------------------
|
|
157
|
+
# Packer
|
|
158
|
+
# -----------------------------------------------------------------------------
|
|
159
|
+
class ContextPacker:
|
|
160
|
+
def __init__(self, max_tokens: int, summarizer_llm: Callable[[str], str]):
|
|
161
|
+
self.max_tokens = max_tokens
|
|
162
|
+
self.summarizer = summarizer_llm
|
|
163
|
+
|
|
164
|
+
@staticmethod
|
|
165
|
+
def _estimate_tokens(text: str) -> int:
|
|
166
|
+
return max(1, len(text) // 4)
|
|
167
|
+
|
|
168
|
+
def pack(self, items: List[ContextItem]) -> List[ContextItem]:
|
|
169
|
+
items = sorted(items, key=lambda x: x.tokens)
|
|
170
|
+
out: List[ContextItem] = []
|
|
171
|
+
budget = 0
|
|
172
|
+
for it in items:
|
|
173
|
+
if budget + it.tokens <= self.max_tokens:
|
|
174
|
+
out.append(it); budget += it.tokens
|
|
175
|
+
else:
|
|
176
|
+
summary = self.summarizer(f"Суммаризуй кратко и по делу:\n\n{it.text}")
|
|
177
|
+
t = self._estimate_tokens(summary)
|
|
178
|
+
if budget + t <= self.max_tokens:
|
|
179
|
+
out.append(ContextItem(key=it.key, raw=it.raw, text=summary, tokens=t))
|
|
180
|
+
budget += t
|
|
181
|
+
return out
|
|
182
|
+
|
|
183
|
+
# -----------------------------------------------------------------------------
|
|
184
|
+
# Generic plan/synth factories (built on pkg prompts)
|
|
185
|
+
# -----------------------------------------------------------------------------
|
|
186
|
+
def make_llm_plan_generic(
|
|
187
|
+
llm_invoke: LLMInvoke,
|
|
188
|
+
task_profile: TaskProfile,
|
|
189
|
+
providers: Dict[str, ContextProvider],
|
|
190
|
+
) -> Callable[[str, Dict[str, str]], str]:
|
|
191
|
+
tpl = load_pkg_text("prompts/plan_generic.md")
|
|
192
|
+
catalog = provider_catalog_text(providers)
|
|
193
|
+
|
|
194
|
+
def llm_plan(feature_name: str, lite_ctx: Dict[str, str]) -> str:
|
|
195
|
+
prompt = render_prompt(
|
|
196
|
+
tpl,
|
|
197
|
+
task_name=task_profile.task_name,
|
|
198
|
+
goal=task_profile.goal,
|
|
199
|
+
output_format=task_profile.output_format,
|
|
200
|
+
acceptance_criteria="\n".join(f"- {x}" for x in task_profile.acceptance_criteria) or "(не задано)",
|
|
201
|
+
constraints="\n".join(f"- {x}" for x in task_profile.constraints) or "(не задано)",
|
|
202
|
+
focus_hints="\n".join(f"- {x}" for x in task_profile.focus_hints) or "(не задано)",
|
|
203
|
+
provider_catalog=catalog,
|
|
204
|
+
lite_context_json=json.dumps(lite_ctx or {}, ensure_ascii=False)[:8000],
|
|
205
|
+
)
|
|
206
|
+
return llm_invoke(prompt, sender="generic_plan")
|
|
207
|
+
return llm_plan
|
|
208
|
+
|
|
209
|
+
def make_llm_synth_generic(
|
|
210
|
+
llm_invoke: LLMInvoke,
|
|
211
|
+
task_profile: TaskProfile,
|
|
212
|
+
) -> Callable[[str, Dict[str, str], Plan], str]:
|
|
213
|
+
tpl = load_pkg_text("prompts/synth_generic.md")
|
|
214
|
+
|
|
215
|
+
def _bundle_ctx(ctx_text: Dict[str, str]) -> str:
|
|
216
|
+
parts = []
|
|
217
|
+
for k, v in (ctx_text or {}).items():
|
|
218
|
+
if v and v.strip():
|
|
219
|
+
parts.append(f"<<<{k.upper()}>>>\n{v}\n<</{k.upper()}>>>")
|
|
220
|
+
return "\n".join(parts) if parts else "(контекст недоступен)"
|
|
221
|
+
|
|
222
|
+
def llm_synth(feature_name: str, ctx_text: Dict[str, str], plan: Plan) -> str:
|
|
223
|
+
prompt = render_prompt(
|
|
224
|
+
tpl,
|
|
225
|
+
task_name=task_profile.task_name,
|
|
226
|
+
goal=task_profile.goal,
|
|
227
|
+
output_format=task_profile.output_format,
|
|
228
|
+
acceptance_criteria="\n".join(f"- {x}" for x in task_profile.acceptance_criteria) or "(не задано)",
|
|
229
|
+
constraints="\n".join(f"- {x}" for x in task_profile.constraints) or "(не задано)",
|
|
230
|
+
focus_hints="\n".join(f"- {x}" for x in task_profile.focus_hints) or "(не задано)",
|
|
231
|
+
plan_json=plan.model_dump_json(),
|
|
232
|
+
context_bundle=_bundle_ctx(ctx_text),
|
|
233
|
+
)
|
|
234
|
+
return llm_invoke(prompt, sender="generic_synth")
|
|
235
|
+
return llm_synth
|
|
236
|
+
|
|
237
|
+
# -----------------------------------------------------------------------------
|
|
238
|
+
# BaseGraphAgent (sequential engine; no external graph dep)
|
|
239
|
+
# -----------------------------------------------------------------------------
|
|
240
|
+
class BaseGraphAgent:
|
|
241
|
+
def __init__(
|
|
242
|
+
self,
|
|
243
|
+
llm_plan: Optional[Callable[[str, Dict[str, str]], str]],
|
|
244
|
+
llm_synth: Callable[[str, Dict[str, str], Plan], str],
|
|
245
|
+
domain_parser: Callable[[RawLLMOutput], Any],
|
|
246
|
+
saver: Saver | Callable[[str, Any], None],
|
|
247
|
+
providers: Dict[str, ContextProvider],
|
|
248
|
+
verifiers: List[Verifier],
|
|
249
|
+
packer: ContextPacker,
|
|
250
|
+
plan_parser: Optional[Callable[[RawLLMOutput], Plan]] = None,
|
|
251
|
+
baseline: Optional[List[BaselineSpec]] = None,
|
|
252
|
+
max_retries: int = 2,
|
|
253
|
+
task_profile: Optional[TaskProfile] = None,
|
|
254
|
+
llm_refetch: Optional[Callable[[str, Dict[str, str], Plan], str]] = None,
|
|
255
|
+
max_refetch_iters: int = 1,
|
|
256
|
+
):
|
|
257
|
+
self.llm_plan = llm_plan
|
|
258
|
+
self.llm_synth = llm_synth
|
|
259
|
+
self.domain_parser = domain_parser
|
|
260
|
+
self.saver = saver
|
|
261
|
+
self.providers = providers
|
|
262
|
+
self.verifiers = verifiers
|
|
263
|
+
self.packer = packer
|
|
264
|
+
self.plan_parser = plan_parser
|
|
265
|
+
self.baseline = baseline or []
|
|
266
|
+
self.max_retries = max_retries
|
|
267
|
+
self.task_profile = task_profile or TaskProfile()
|
|
268
|
+
self.llm_refetch = llm_refetch
|
|
269
|
+
self.max_refetch_iters = max_refetch_iters
|
|
270
|
+
|
|
271
|
+
# ---- public API ----
|
|
272
|
+
def run(self, feature_name: str) -> Any:
|
|
273
|
+
# PLAN
|
|
274
|
+
plan = self._plan(feature_name)
|
|
275
|
+
|
|
276
|
+
# FETCH (+ pack)
|
|
277
|
+
ctx = self._fetch(feature_name, plan)
|
|
278
|
+
|
|
279
|
+
# ASSESS/REFETCH loop
|
|
280
|
+
if self.llm_refetch:
|
|
281
|
+
ctx, plan = self._assess_refetch_loop(feature_name, ctx, plan)
|
|
282
|
+
|
|
283
|
+
# Ensure baseline items before synth
|
|
284
|
+
ctx = self._ensure_required_baseline(feature_name, ctx)
|
|
285
|
+
|
|
286
|
+
# SYNTH + VERIFY + REFINE
|
|
287
|
+
draft = self._synthesize(feature_name, ctx, plan)
|
|
288
|
+
draft, ok = self._verify_and_refine(feature_name, ctx, plan, draft)
|
|
289
|
+
|
|
290
|
+
# PARSE & SAVE
|
|
291
|
+
parsed = self.domain_parser(draft)
|
|
292
|
+
if callable(self.saver):
|
|
293
|
+
self.saver(feature_name, parsed) # type: ignore[misc]
|
|
294
|
+
else:
|
|
295
|
+
self.saver.save(feature_name, parsed) # type: ignore[attr-defined]
|
|
296
|
+
return parsed
|
|
297
|
+
|
|
298
|
+
# ---- steps ----
|
|
299
|
+
def _plan(self, feature_name: str) -> Plan:
|
|
300
|
+
lite_ctx = self._lite_context(feature_name)
|
|
301
|
+
if self.llm_plan is None:
|
|
302
|
+
raise RuntimeError("llm_plan is not provided. Use make_llm_plan_generic(...) or pass custom.")
|
|
303
|
+
plan_text = self.llm_plan(feature_name, lite_ctx)
|
|
304
|
+
plan_raw = normalize_llm_output(plan_text)
|
|
305
|
+
if self.plan_parser is not None:
|
|
306
|
+
plan = self.plan_parser(plan_raw)
|
|
307
|
+
else:
|
|
308
|
+
plan = Plan.model_validate_json(plan_raw.text)
|
|
309
|
+
return plan
|
|
310
|
+
|
|
311
|
+
def _merge_baseline_with_plan(self, plan: Plan) -> List[ContextFetchSpec]:
|
|
312
|
+
by_provider: Dict[str, ContextFetchSpec] = {}
|
|
313
|
+
for b in self.baseline:
|
|
314
|
+
by_provider.setdefault(b.spec.provider, b.spec)
|
|
315
|
+
for s in plan.context_plan or []:
|
|
316
|
+
by_provider[s.provider] = s
|
|
317
|
+
if not plan.context_plan:
|
|
318
|
+
for p in plan.required_context or []:
|
|
319
|
+
by_provider.setdefault(p, ContextFetchSpec(provider=p, mode="full"))
|
|
320
|
+
return list(by_provider.values())
|
|
321
|
+
|
|
322
|
+
def _fetch(self, feature_name: str, plan: Plan) -> Dict[str, ContextItem]:
|
|
323
|
+
specs = self._merge_baseline_with_plan(plan)
|
|
324
|
+
gathered: List[ContextItem] = []
|
|
325
|
+
|
|
326
|
+
for spec in specs:
|
|
327
|
+
prov = self.providers.get(spec.provider)
|
|
328
|
+
if not prov:
|
|
329
|
+
continue
|
|
330
|
+
obj = prov.fetch(feature_name, selectors=spec.selectors)
|
|
331
|
+
if spec.mode == "slice":
|
|
332
|
+
obj = _apply_provider_filter(prov, obj, spec.selectors)
|
|
333
|
+
text = prov.serialize(obj)
|
|
334
|
+
tokens = max(1, len(text) // 4)
|
|
335
|
+
if spec.max_tokens and tokens > spec.max_tokens:
|
|
336
|
+
approx_chars = spec.max_tokens * 4
|
|
337
|
+
text = text[:approx_chars]
|
|
338
|
+
tokens = max(1, len(text) // 4)
|
|
339
|
+
gathered.append(ContextItem(key=spec.provider, raw=obj, text=text, tokens=tokens))
|
|
340
|
+
|
|
341
|
+
packed = self.packer.pack(gathered)
|
|
342
|
+
return {it.key: it for it in packed}
|
|
343
|
+
|
|
344
|
+
def _assess_refetch_loop(self, feature_name: str, ctx: Dict[str, ContextItem], plan: Plan):
|
|
345
|
+
iters = 0
|
|
346
|
+
while self.llm_refetch and iters < self.max_refetch_iters:
|
|
347
|
+
ctx_text = {k: v.text for k, v in (ctx or {}).items()}
|
|
348
|
+
decision_text = self.llm_refetch(feature_name, ctx_text, plan)
|
|
349
|
+
decision_raw = normalize_llm_output(decision_text)
|
|
350
|
+
try:
|
|
351
|
+
decision = RefetchDecision.model_validate_json(decision_raw.text)
|
|
352
|
+
except Exception:
|
|
353
|
+
break
|
|
354
|
+
if decision.stop or not decision.add_specs:
|
|
355
|
+
break
|
|
356
|
+
# merge new specs into plan
|
|
357
|
+
merged = list(plan.context_plan or [])
|
|
358
|
+
seen = {(s.provider, json.dumps(s.selectors, sort_keys=True), s.mode) for s in merged}
|
|
359
|
+
for ns in decision.add_specs:
|
|
360
|
+
key = (ns.provider, json.dumps(ns.selectors or {}, sort_keys=True), ns.mode)
|
|
361
|
+
if key not in seen:
|
|
362
|
+
merged.append(ns); seen.add(key)
|
|
363
|
+
plan = plan.model_copy(update={"context_plan": merged})
|
|
364
|
+
# fetch again
|
|
365
|
+
ctx = self._fetch(feature_name, plan)
|
|
366
|
+
iters += 1
|
|
367
|
+
return ctx, plan
|
|
368
|
+
|
|
369
|
+
def _ensure_required_baseline(self, feature_name: str, ctx: Dict[str, ContextItem]) -> Dict[str, ContextItem]:
|
|
370
|
+
out = dict(ctx)
|
|
371
|
+
for b in self.baseline:
|
|
372
|
+
if not b.required:
|
|
373
|
+
continue
|
|
374
|
+
key = b.spec.provider
|
|
375
|
+
if key in out:
|
|
376
|
+
continue
|
|
377
|
+
prov = self.providers.get(key)
|
|
378
|
+
if not prov:
|
|
379
|
+
continue
|
|
380
|
+
obj = prov.fetch(feature_name, selectors=b.spec.selectors)
|
|
381
|
+
if b.spec.mode == "slice":
|
|
382
|
+
obj = _apply_provider_filter(prov, obj, b.spec.selectors)
|
|
383
|
+
text = prov.serialize(obj)
|
|
384
|
+
tokens = max(1, len(text) // 4)
|
|
385
|
+
out[key] = ContextItem(key=key, raw=obj, text=text, tokens=tokens)
|
|
386
|
+
return out
|
|
387
|
+
|
|
388
|
+
def _synthesize(self, feature_name: str, ctx: Dict[str, ContextItem], plan: Plan) -> RawLLMOutput:
|
|
389
|
+
ctx_text = {k: v.text for k, v in (ctx or {}).items()}
|
|
390
|
+
out_text = self.llm_synth(feature_name, ctx_text, plan)
|
|
391
|
+
return normalize_llm_output(out_text)
|
|
392
|
+
|
|
393
|
+
def _verify_and_refine(
|
|
394
|
+
self, feature_name: str, ctx: Dict[str, ContextItem], plan: Plan, draft: RawLLMOutput
|
|
395
|
+
) -> tuple[RawLLMOutput, bool]:
|
|
396
|
+
retries = 0
|
|
397
|
+
while True:
|
|
398
|
+
errors: List[str] = []
|
|
399
|
+
for v in self.verifiers:
|
|
400
|
+
try:
|
|
401
|
+
errors += v.check(draft)
|
|
402
|
+
except Exception as e:
|
|
403
|
+
errors.append(f"[{getattr(v, 'name', 'verifier')}] error: {e}")
|
|
404
|
+
if not errors:
|
|
405
|
+
return draft, True
|
|
406
|
+
if retries >= self.max_retries:
|
|
407
|
+
return draft, False
|
|
408
|
+
# refine
|
|
409
|
+
ctx_text = {k: v.text for k, v in (ctx or {}).items()}
|
|
410
|
+
ctx_text["issues"] = "\n".join(errors)
|
|
411
|
+
refined = self.llm_synth(feature_name, ctx_text, plan)
|
|
412
|
+
draft = normalize_llm_output(refined)
|
|
413
|
+
retries += 1
|
|
414
|
+
|
|
415
|
+
# ---- lite context (optional) ----
|
|
416
|
+
def _lite_context(self, feature_name: str) -> Dict[str, str]:
|
|
417
|
+
out: Dict[str, str] = {}
|
|
418
|
+
for key in self.task_profile.lite_context_keys or []:
|
|
419
|
+
prov = self.providers.get(key)
|
|
420
|
+
if not prov:
|
|
421
|
+
continue
|
|
422
|
+
obj = prov.fetch(feature_name)
|
|
423
|
+
out[key] = prov.serialize(obj)
|
|
424
|
+
return out
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
Ты — агент планирования выборки контента для задачи: "{task_name}".
|
|
2
|
+
|
|
3
|
+
🎯 Цель:
|
|
4
|
+
{goal}
|
|
5
|
+
|
|
6
|
+
📦 Требуемый формат ИТОГОВОГО РЕЗУЛЬТАТА (для следующего шага синтеза, сейчас его НЕ генерируй):
|
|
7
|
+
{output_format}
|
|
8
|
+
|
|
9
|
+
✅ Критерии приемки (для синтеза):
|
|
10
|
+
{acceptance_criteria}
|
|
11
|
+
|
|
12
|
+
⚙️ Ограничения:
|
|
13
|
+
{constraints}
|
|
14
|
+
|
|
15
|
+
🎯 Фокус/подсказки:
|
|
16
|
+
{focus_hints}
|
|
17
|
+
|
|
18
|
+
📚 Доступные провайдеры контекста:
|
|
19
|
+
{provider_catalog}
|
|
20
|
+
|
|
21
|
+
📥 Lite-контекст:
|
|
22
|
+
{lite_context_json}
|
|
23
|
+
|
|
24
|
+
Твоя задача на ЭТАПЕ A — выдать ТОЛЬКО план выборки (строгий JSON):
|
|
25
|
+
{{
|
|
26
|
+
"required_context": ["<provider>", ...],
|
|
27
|
+
"context_plan": [
|
|
28
|
+
{{ "provider": "<name>", "mode": "full|slice", "selectors": {{}}, "max_tokens": 2000 }}
|
|
29
|
+
],
|
|
30
|
+
"adr_queries": [],
|
|
31
|
+
"constraints": []
|
|
32
|
+
}}
|
|
33
|
+
|
|
34
|
+
Правила:
|
|
35
|
+
- Используй только перечисленные провайдеры.
|
|
36
|
+
- Предпочитай "slice" с selectors.
|
|
37
|
+
- Учитывай ограничения/фокус.
|
|
38
|
+
- НЕ генерируй доменный результат, только JSON плана.
|
|
39
|
+
|
|
40
|
+
Закончить ответ нужно строкой "Final Answer:" и далее строго JSON.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
Ты — агент синтеза результата для задачи: "{task_name}".
|
|
2
|
+
|
|
3
|
+
🎯 Цель:
|
|
4
|
+
{goal}
|
|
5
|
+
|
|
6
|
+
📦 Требуемый формат ИТОГОВОГО РЕЗУЛЬТАТА (соблюдай строго):
|
|
7
|
+
{output_format}
|
|
8
|
+
|
|
9
|
+
📥 План выборки (JSON):
|
|
10
|
+
{plan_json}
|
|
11
|
+
|
|
12
|
+
📦 Контекстный пакет (аннотированный):
|
|
13
|
+
{context_bundle}
|
|
14
|
+
|
|
15
|
+
⚠️ Напоминание:
|
|
16
|
+
- Учитывай критерии приемки:
|
|
17
|
+
{acceptance_criteria}
|
|
18
|
+
- Учитывай ограничения:
|
|
19
|
+
{constraints}
|
|
20
|
+
- Фокус/подсказки:
|
|
21
|
+
{focus_hints}
|
|
22
|
+
|
|
23
|
+
Сгенерируй ТОЛЬКО итоговый артефакт строго в указанном формате, без пояснений.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
from importlib import resources
|
|
3
|
+
|
|
4
|
+
def load_pkg_text(rel_path: str) -> str:
|
|
5
|
+
"""Read a text resource from package (e.g., 'prompts/plan_generic.md')."""
|
|
6
|
+
with resources.files("fetchgraph").joinpath(rel_path).open("r", encoding="utf-8") as f:
|
|
7
|
+
return f.read()
|
|
8
|
+
|
|
9
|
+
def render_prompt(template: str, **values) -> str:
|
|
10
|
+
"""Very simple {key}-style renderer (no conditionals)."""
|
|
11
|
+
out = template
|
|
12
|
+
# longest keys first to avoid prefix collisions
|
|
13
|
+
for k, v in sorted(values.items(), key=lambda kv: len(kv[0]), reverse=True):
|
|
14
|
+
out = out.replace("{" + k + "}", "" if v is None else str(v))
|
|
15
|
+
return out
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fetchgraph
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: Graph-like planning → context fetching → synthesis agent (library-style).
|
|
5
|
+
Author: Alexander Onischenko
|
|
6
|
+
License: MIT
|
|
7
|
+
Keywords: agents,context,langgraph,planning,llm
|
|
8
|
+
Requires-Python: >=3.10
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Requires-Dist: pydantic>=2.6
|
|
12
|
+
Dynamic: license-file
|
|
13
|
+
|
|
14
|
+
# fetchgraph
|
|
15
|
+
|
|
16
|
+
Universal, library-style agent that plans what to fetch, fetches context from pluggable providers, and synthesizes an output.
|
|
17
|
+
|
|
18
|
+
**Pipeline:** PLAN → FETCH → (ASSESS/REFETCH)* → SYNTH → VERIFY → (REFINE)* → SAVE
|
|
19
|
+
|
|
20
|
+
## Install (dev)
|
|
21
|
+
```bash
|
|
22
|
+
pip install -e .
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
# Quick Start
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
from fetchgraph import (
|
|
29
|
+
BaseGraphAgent, ContextPacker, BaselineSpec, ContextFetchSpec,
|
|
30
|
+
TaskProfile, RawLLMOutput
|
|
31
|
+
)
|
|
32
|
+
from fetchgraph.core import make_llm_plan_generic, make_llm_synth_generic
|
|
33
|
+
|
|
34
|
+
# Define providers (implement ContextProvider protocol)
|
|
35
|
+
class SpecProvider:
|
|
36
|
+
name = "spec"
|
|
37
|
+
def fetch(self, feature_name, selectors=None, **kw): return {"content": f"Spec for {feature_name}"}
|
|
38
|
+
def serialize(self, obj): return obj.get("content", "") if isinstance(obj, dict) else str(obj)
|
|
39
|
+
|
|
40
|
+
def dummy_llm(prompt: str, sender: str) -> str:
|
|
41
|
+
if sender == "generic_plan":
|
|
42
|
+
return '{"required_context":["spec"],"context_plan":[{"provider":"spec","mode":"full"}]}'
|
|
43
|
+
if sender == "generic_synth":
|
|
44
|
+
return "result: ok"
|
|
45
|
+
return ""
|
|
46
|
+
|
|
47
|
+
profile = TaskProfile(
|
|
48
|
+
task_name="Demo",
|
|
49
|
+
goal="Produce YAML doc from spec",
|
|
50
|
+
output_format="YAML: result: <...>"
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
agent = BaseGraphAgent(
|
|
54
|
+
llm_plan=make_llm_plan_generic(dummy_llm, profile, {"spec": SpecProvider()}),
|
|
55
|
+
llm_synth=make_llm_synth_generic(dummy_llm, profile),
|
|
56
|
+
domain_parser=lambda raw: raw.text, # RawLLMOutput -> Any
|
|
57
|
+
saver=lambda feature_name, parsed: None, # save side-effect
|
|
58
|
+
providers={"spec": SpecProvider()},
|
|
59
|
+
verifiers=[type("Ok",(),{"name":"ok","check":lambda self,out: []})()],
|
|
60
|
+
packer=ContextPacker(max_tokens=2000, summarizer_llm=lambda t: t[:200]),
|
|
61
|
+
baseline=[BaselineSpec(ContextFetchSpec(provider="spec"))],
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
print(agent.run("FeatureX"))
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## LICENSE
|
|
70
|
+
```text
|
|
71
|
+
MIT License
|
|
72
|
+
|
|
73
|
+
Copyright (c) 2025 ...
|
|
74
|
+
|
|
75
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
76
|
+
...
|
|
77
|
+
```
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
src/fetchgraph/__init__.py
|
|
5
|
+
src/fetchgraph/core.py
|
|
6
|
+
src/fetchgraph/utils.py
|
|
7
|
+
src/fetchgraph.egg-info/PKG-INFO
|
|
8
|
+
src/fetchgraph.egg-info/SOURCES.txt
|
|
9
|
+
src/fetchgraph.egg-info/dependency_links.txt
|
|
10
|
+
src/fetchgraph.egg-info/requires.txt
|
|
11
|
+
src/fetchgraph.egg-info/top_level.txt
|
|
12
|
+
src/fetchgraph/prompts/plan_generic.md
|
|
13
|
+
src/fetchgraph/prompts/synth_generic.md
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
pydantic>=2.6
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
fetchgraph
|