deeprefine-cli 0.1.5__tar.gz → 0.1.6__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 (23) hide show
  1. {deeprefine_cli-0.1.5/deeprefine_cli.egg-info → deeprefine_cli-0.1.6}/PKG-INFO +19 -30
  2. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/README.md +18 -29
  3. deeprefine_cli-0.1.6/SKILL.md +80 -0
  4. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6/deeprefine_cli.egg-info}/PKG-INFO +19 -30
  5. deeprefine_cli-0.1.6/deeprefine_skill/SKILL.md +80 -0
  6. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_skill/__init__.py +1 -1
  7. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/pyproject.toml +1 -1
  8. deeprefine_cli-0.1.5/SKILL.md +0 -62
  9. deeprefine_cli-0.1.5/deeprefine_skill/SKILL.md +0 -62
  10. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/LICENSE +0 -0
  11. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/MANIFEST.in +0 -0
  12. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_cli.egg-info/SOURCES.txt +0 -0
  13. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_cli.egg-info/dependency_links.txt +0 -0
  14. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_cli.egg-info/entry_points.txt +0 -0
  15. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_cli.egg-info/requires.txt +0 -0
  16. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_cli.egg-info/top_level.txt +0 -0
  17. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_skill/adapter_graphify.py +0 -0
  18. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_skill/cli.py +0 -0
  19. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_skill/history.py +0 -0
  20. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_skill/installers.py +0 -0
  21. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_skill/paths.py +0 -0
  22. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_skill/refine_runner.py +0 -0
  23. {deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/setup.cfg +0 -0
{deeprefine_cli-0.1.5/deeprefine_cli.egg-info → deeprefine_cli-0.1.6}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: deeprefine-cli
3
- Version: 0.1.5
3
+ Version: 0.1.6
4
4
  Summary: CLI and Cursor skill to refine graphify knowledge graphs with DeepRefine
5
5
  Author: HKUST-KnowComp
6
6
  License-Expression: MIT
@@ -29,8 +29,8 @@ Dynamic: license-file
29
29
  # DeepRefine-Skill
30
30
 
31
31
 
32
- [![PyPi](https://img.shields.io/badge/PyPi-v0.1.5-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.5/)
33
- [![Python](https://img.shields.io/badge/Python-3.10,3.11,3.12-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.5/)
32
+ [![PyPi](https://img.shields.io/badge/PyPi-v0.1.6-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.6/)
33
+ [![Python](https://img.shields.io/badge/Python-3.10,3.11,3.12-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.6/)
34
34
  [![Paper](https://img.shields.io/badge/Paper-DeepRefine-b31b1b.svg)](https://arxiv.org/pdf/2605.10488)
35
35
  [![Project](https://img.shields.io/badge/Project-DeepRefine-green.svg)](https://github.com/HKUST-KnowComp/DeepRefine)
36
36
 
@@ -38,17 +38,13 @@ Dynamic: license-file
38
38
 
39
39
  Type `/deeprefine` in your AI coding assistant after you've built a **[graphify](https://github.com/safishamsi/graphify)** knowledge base — it patches `graphify-out/graph.json` from your session's query history to evolve your LLM-Wiki.
40
40
 
41
- Works in **Cursor** (install the skill once with `deeprefine cursor install`). In Cursor, `/deeprefine` runs in **agent-native mode** (no extra API key needed). The runtime CLI (`deeprefine refine`) is still available for vLLM/API execution.
41
+ Works in **Cursor** (install the skill once with `deeprefine cursor install`). In Cursor, `/deeprefine` tells the agent to run **`deeprefine refine`** in your project — the full Reafiner loop (judgement → abduction → action generation), not a hand-edited `graph.json`.
42
42
 
43
43
  ```
44
44
  /deeprefine
45
45
  ```
46
46
 
47
- **Typical flow:** `graphify .` → `graphify query "..."` → record the question → `/deeprefine`.
48
-
49
- ```bash
50
- deeprefine history add --query "your question" # or let the agent do this
51
- ```
47
+ **Typical flow:** `graphify .` → `graphify query "..."` → `/deeprefine` (agent runs `deeprefine refine` for session queries).
52
48
 
53
49
  That's it. Under `graphify-out/.deeprefine/` you get:
54
50
 
@@ -62,14 +58,13 @@ graphify-out/
62
58
  ```
63
59
 
64
60
  > **Standalone repo.** Model code (`autorefiner`, `atlas_rag`) lives in a separate [DeepRefine](https://github.com/HKUST-KnowComp/DeepRefine) checkout.
65
- > `pip install deeprefine-cli` ships the CLI and `SKILL.md`. In Cursor, `/deeprefine` uses agent-native refinement; `deeprefine refine` uses DeepRefine runtime (vLLM/API) when you explicitly choose CLI execution.
61
+ > `pip install deeprefine-cli` ships the CLI and `SKILL.md`. `/deeprefine` and terminal `deeprefine refine` both use the same DeepRefine runtime (vLLM or API keys in your shell). Configure inference once in `atlastune`.
66
62
 
67
63
  ---
68
64
 
69
65
  ## News
70
66
 
71
- - [2026/6/2] deeprefine-cli v0.1.5 has been released! Agent-native `/deeprefine` flow + clearer CLI/Agent split.
72
- - [2026/6/2] deeprefine-cli v0.1.4 has been released! Customize your LLM api.
67
+ - [2026/6/2] deeprefine-cli v0.1.6 has been released! Customize your LLM api in CLI.
73
68
 
74
69
  ---
75
70
 
@@ -81,7 +76,7 @@ graphify-out/
81
76
  | 2 | `pip install deeprefine-cli` |
82
77
  | 3 | `deeprefine cursor install` in your KB project |
83
78
  | 4 | (Optional) start local vLLM, or use your API provider |
84
- | 5 | Cursor chat: `/deeprefine` *(auto uses/adds query context)*; CLI mode: `history add` + `refine` |
79
+ | 5 | Cursor chat: `/deeprefine` *(agent runs `deeprefine refine`)*; or terminal: `history add` + `refine` |
85
80
 
86
81
  ```bash
87
82
  # 1) DeepRefine (once)
@@ -110,21 +105,13 @@ export DEEPREFINE_EMBED_MODEL=your_embed_model
110
105
  # export DEEPREFINE_API_KEY=your_shared_api_key
111
106
  # optional model overrides:
112
107
 
113
- # 5a) Refine in Cursor chat (agent-native, recommended)
114
- # type in chat:
115
- # /deeprefine
116
-
117
- # 5b) Refine in terminal / CLI (manual flow)
108
+ # 5) Refine — full Reafiner loop
109
+ # Cursor chat: type /deeprefine (agent runs deeprefine refine --query "..." per session question)
110
+ # Terminal manual flow:
118
111
  deeprefine history add --query "your question"
119
112
  deeprefine refine
120
113
  ```
121
114
 
122
- In **Cursor chat** (agent):
123
-
124
- ```text
125
- /deeprefine
126
- ```
127
-
128
115
  ---
129
116
 
130
117
  ## Pipeline
@@ -141,11 +128,13 @@ In **Cursor chat** (agent):
141
128
  ▼ graphify
142
129
  graph.json ◄────────────────────────┐
143
130
  │ │
144
- ▼ graphify query │ deeprefine refine
145
- (Q&A session) │
131
+ ▼ graphify query "..." │ deeprefine refine
132
+ ▼ graphify query "..." │ (per session query)
133
+ ▼ ... │
134
+ (many Q&A in session) │
146
135
  │ │
147
- ▼ deeprefine history add │
148
- history.jsonl ──────────────────────┘
136
+ ▼ /deeprefine │
137
+ (DeepRefine loop) ────────────────────┘
149
138
  │
150
139
  ▼ graphify query (verify)
151
140
  ```
@@ -266,8 +255,8 @@ deeprefine cursor install
266
255
  |:-:|--------|
267
256
  | 1 | `graphify .` or `/graphify .` → `graphify-out/graph.json` |
268
257
  | 2 | `graphify query "..."` |
269
- | 3 | Cursor chat: `/deeprefine` *(recommended; no manual `history add` needed)* |
270
- | 4 | CLI alternative: `deeprefine history add --query "..."` → `deeprefine refine` |
258
+ | 3 | Cursor chat: `/deeprefine` *(agent runs `deeprefine refine` / `--query` for session questions)* |
259
+ | 4 | Terminal alternative: `deeprefine history add --query "..."` → `deeprefine refine` |
271
260
  | 5 | *(optional)* `graphify query "..."` to verify |
272
261
 
273
262
  ---
{deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/README.md RENAMED
@@ -3,8 +3,8 @@
3
3
  # DeepRefine-Skill
4
4
 
5
5
 
6
- [![PyPi](https://img.shields.io/badge/PyPi-v0.1.5-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.5/)
7
- [![Python](https://img.shields.io/badge/Python-3.10,3.11,3.12-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.5/)
6
+ [![PyPi](https://img.shields.io/badge/PyPi-v0.1.6-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.6/)
7
+ [![Python](https://img.shields.io/badge/Python-3.10,3.11,3.12-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.6/)
8
8
  [![Paper](https://img.shields.io/badge/Paper-DeepRefine-b31b1b.svg)](https://arxiv.org/pdf/2605.10488)
9
9
  [![Project](https://img.shields.io/badge/Project-DeepRefine-green.svg)](https://github.com/HKUST-KnowComp/DeepRefine)
10
10
 
@@ -12,17 +12,13 @@
12
12
 
13
13
  Type `/deeprefine` in your AI coding assistant after you've built a **[graphify](https://github.com/safishamsi/graphify)** knowledge base — it patches `graphify-out/graph.json` from your session's query history to evolve your LLM-Wiki.
14
14
 
15
- Works in **Cursor** (install the skill once with `deeprefine cursor install`). In Cursor, `/deeprefine` runs in **agent-native mode** (no extra API key needed). The runtime CLI (`deeprefine refine`) is still available for vLLM/API execution.
15
+ Works in **Cursor** (install the skill once with `deeprefine cursor install`). In Cursor, `/deeprefine` tells the agent to run **`deeprefine refine`** in your project — the full Reafiner loop (judgement → abduction → action generation), not a hand-edited `graph.json`.
16
16
 
17
17
  ```
18
18
  /deeprefine
19
19
  ```
20
20
 
21
- **Typical flow:** `graphify .` → `graphify query "..."` → record the question → `/deeprefine`.
22
-
23
- ```bash
24
- deeprefine history add --query "your question" # or let the agent do this
25
- ```
21
+ **Typical flow:** `graphify .` → `graphify query "..."` → `/deeprefine` (agent runs `deeprefine refine` for session queries).
26
22
 
27
23
  That's it. Under `graphify-out/.deeprefine/` you get:
28
24
 
@@ -36,14 +32,13 @@ graphify-out/
36
32
  ```
37
33
 
38
34
  > **Standalone repo.** Model code (`autorefiner`, `atlas_rag`) lives in a separate [DeepRefine](https://github.com/HKUST-KnowComp/DeepRefine) checkout.
39
- > `pip install deeprefine-cli` ships the CLI and `SKILL.md`. In Cursor, `/deeprefine` uses agent-native refinement; `deeprefine refine` uses DeepRefine runtime (vLLM/API) when you explicitly choose CLI execution.
35
+ > `pip install deeprefine-cli` ships the CLI and `SKILL.md`. `/deeprefine` and terminal `deeprefine refine` both use the same DeepRefine runtime (vLLM or API keys in your shell). Configure inference once in `atlastune`.
40
36
 
41
37
  ---
42
38
 
43
39
  ## News
44
40
 
45
- - [2026/6/2] deeprefine-cli v0.1.5 has been released! Agent-native `/deeprefine` flow + clearer CLI/Agent split.
46
- - [2026/6/2] deeprefine-cli v0.1.4 has been released! Customize your LLM api.
41
+ - [2026/6/2] deeprefine-cli v0.1.6 has been released! Customize your LLM api in CLI.
47
42
 
48
43
  ---
49
44
 
@@ -55,7 +50,7 @@ graphify-out/
55
50
  | 2 | `pip install deeprefine-cli` |
56
51
  | 3 | `deeprefine cursor install` in your KB project |
57
52
  | 4 | (Optional) start local vLLM, or use your API provider |
58
- | 5 | Cursor chat: `/deeprefine` *(auto uses/adds query context)*; CLI mode: `history add` + `refine` |
53
+ | 5 | Cursor chat: `/deeprefine` *(agent runs `deeprefine refine`)*; or terminal: `history add` + `refine` |
59
54
 
60
55
  ```bash
61
56
  # 1) DeepRefine (once)
@@ -84,21 +79,13 @@ export DEEPREFINE_EMBED_MODEL=your_embed_model
84
79
  # export DEEPREFINE_API_KEY=your_shared_api_key
85
80
  # optional model overrides:
86
81
 
87
- # 5a) Refine in Cursor chat (agent-native, recommended)
88
- # type in chat:
89
- # /deeprefine
90
-
91
- # 5b) Refine in terminal / CLI (manual flow)
82
+ # 5) Refine — full Reafiner loop
83
+ # Cursor chat: type /deeprefine (agent runs deeprefine refine --query "..." per session question)
84
+ # Terminal manual flow:
92
85
  deeprefine history add --query "your question"
93
86
  deeprefine refine
94
87
  ```
95
88
 
96
- In **Cursor chat** (agent):
97
-
98
- ```text
99
- /deeprefine
100
- ```
101
-
102
89
  ---
103
90
 
104
91
  ## Pipeline
@@ -115,11 +102,13 @@ In **Cursor chat** (agent):
115
102
  ▼ graphify
116
103
  graph.json ◄────────────────────────┐
117
104
  │ │
118
- ▼ graphify query │ deeprefine refine
119
- (Q&A session) │
105
+ ▼ graphify query "..." │ deeprefine refine
106
+ ▼ graphify query "..." │ (per session query)
107
+ ▼ ... │
108
+ (many Q&A in session) │
120
109
  │ │
121
- ▼ deeprefine history add │
122
- history.jsonl ──────────────────────┘
110
+ ▼ /deeprefine │
111
+ (DeepRefine loop) ────────────────────┘
123
112
  │
124
113
  ▼ graphify query (verify)
125
114
  ```
@@ -240,8 +229,8 @@ deeprefine cursor install
240
229
  |:-:|--------|
241
230
  | 1 | `graphify .` or `/graphify .` → `graphify-out/graph.json` |
242
231
  | 2 | `graphify query "..."` |
243
- | 3 | Cursor chat: `/deeprefine` *(recommended; no manual `history add` needed)* |
244
- | 4 | CLI alternative: `deeprefine history add --query "..."` → `deeprefine refine` |
232
+ | 3 | Cursor chat: `/deeprefine` *(agent runs `deeprefine refine` / `--query` for session questions)* |
233
+ | 4 | Terminal alternative: `deeprefine history add --query "..."` → `deeprefine refine` |
245
234
  | 5 | *(optional)* `graphify query "..."` to verify |
246
235
 
247
236
  ---
deeprefine_cli-0.1.6/SKILL.md ADDED
@@ -0,0 +1,80 @@
1
+ ---
2
+ name: deeprefine
3
+ description: >-
4
+ Refines a graphify knowledge graph (graphify-out/graph.json) using DeepRefine
5
+ Reafiner (judgement, error abduction, KG action generation). Use when the user
6
+ runs /deeprefine, asks to improve the graphify KB after Q&A, or wants to patch
7
+ graph.json from failed retrieval queries.
8
+ disable-model-invocation: false
9
+ ---
10
+
11
+ # DeepRefine (graphify)
12
+
13
+ Refine `graphify-out/graph.json` with the **full DeepRefine Reafiner loop** (multi-hop retrieval → answerable judgement → error abduction → refinement actions). Do **not** hand-edit `graph.json`.
14
+
15
+ ## Setup (once)
16
+
17
+ **DeepRefine-Skill** (CLI + this file) is separate from the **DeepRefine** model repo.
18
+
19
+ ```bash
20
+ conda activate atlastune
21
+ cd /path/to/DeepRefine && pip install -e .
22
+ pip install deeprefine-cli
23
+ export DEEPREFINE_REPO=/path/to/DeepRefine # if not ../DeepRefine
24
+ cd /path/to/your-kb-project
25
+ deeprefine cursor install
26
+ ```
27
+
28
+ **Inference** (required for `deeprefine refine`; configure in the shell where you run commands):
29
+
30
+ - **Local vLLM:** start DeepRefine `scripts/vllm_serve/` (embedding `8128`, refine `8134`), or
31
+ - **API:** set `DEEPREFINE_LLM_URL`, `DEEPREFINE_EMBED_URL`, `DEEPREFINE_LLM_API_KEY`, `DEEPREFINE_EMBED_API_KEY`, and model names.
32
+
33
+ ## `/deeprefine` — run the real Reafiner via CLI
34
+
35
+ When the user invokes `/deeprefine`, **orchestrate** refinement by running the CLI in the **KB project root** (directory containing `graphify-out/graph.json`). The subprocess runs `Reafiner.refine()` — not a free-form graph edit in chat.
36
+
37
+ ### Agent steps
38
+
39
+ 1. **Confirm cwd** is the KB project root (`graphify-out/graph.json` exists).
40
+ 2. **Collect queries** to refine:
41
+ - Prefer questions from **this chat session** after recent `graphify query` / `/graphify query` (user questions about the KB).
42
+ - Optionally check pending history: `deeprefine history list --pending`.
43
+ 3. **Run refinement** (use `atlastune`; do not edit `graph.json` yourself):
44
+
45
+ ```bash
46
+ conda activate atlastune
47
+ # If there are pending entries and they match what the user wants refined:
48
+ deeprefine refine
49
+
50
+ # Otherwise, for each session query (records + refines in one step):
51
+ deeprefine refine --query "exact user question from this session"
52
+ ```
53
+
54
+ 4. **Report results** from CLI stdout: queries processed, node/edge counts, log path under `graphify-out/.deeprefine/refinement_results_*.jsonl`.
55
+ 5. On failure (missing API key, vLLM down, no graph), show the error and tell the user which env vars or vLLM scripts to fix — do not fall back to manual JSON patching.
56
+
57
+ ### Rules
58
+
59
+ | Do | Don't |
60
+ |----|--------|
61
+ | Run `deeprefine refine` / `deeprefine refine --query "..."` | Hand-edit `graphify-out/graph.json` |
62
+ | Use `atlastune` + configured inference | Simulate judgement/abduction in chat only |
63
+ | Use exact user queries from the session | Require the user to run `history add` first in Cursor |
64
+
65
+ ### What runs inside `deeprefine refine`
66
+
67
+ Per query, the DeepRefine runtime executes:
68
+
69
+ 1. Multi-hop subgraph retrieval (FAISS + KG expansion)
70
+ 2. **Answerable judgement** per hop
71
+ 3. **Error abduction** when retrieval fails across hops
72
+ 4. **Refinement action generation** and application to the KG
73
+ 5. Persist updated `graph.json`, FAISS cache, and `history.jsonl` (`refined: true`)
74
+
75
+ ## Paths
76
+
77
+ - History: `graphify-out/.deeprefine/history.jsonl`
78
+ - Log: `graphify-out/.deeprefine/refinement_results_*.jsonl`
79
+ - Backup: `graphify-out/.deeprefine/graph.json.bak`
80
+ - FAISS cache: `graphify-out/.deeprefine/cache/reafiner_data.pkl`
{deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6/deeprefine_cli.egg-info}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: deeprefine-cli
3
- Version: 0.1.5
3
+ Version: 0.1.6
4
4
  Summary: CLI and Cursor skill to refine graphify knowledge graphs with DeepRefine
5
5
  Author: HKUST-KnowComp
6
6
  License-Expression: MIT
@@ -29,8 +29,8 @@ Dynamic: license-file
29
29
  # DeepRefine-Skill
30
30
 
31
31
 
32
- [![PyPi](https://img.shields.io/badge/PyPi-v0.1.5-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.5/)
33
- [![Python](https://img.shields.io/badge/Python-3.10,3.11,3.12-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.5/)
32
+ [![PyPi](https://img.shields.io/badge/PyPi-v0.1.6-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.6/)
33
+ [![Python](https://img.shields.io/badge/Python-3.10,3.11,3.12-blue.svg)](https://pypi.org/project/deeprefine-cli/0.1.6/)
34
34
  [![Paper](https://img.shields.io/badge/Paper-DeepRefine-b31b1b.svg)](https://arxiv.org/pdf/2605.10488)
35
35
  [![Project](https://img.shields.io/badge/Project-DeepRefine-green.svg)](https://github.com/HKUST-KnowComp/DeepRefine)
36
36
 
@@ -38,17 +38,13 @@ Dynamic: license-file
38
38
 
39
39
  Type `/deeprefine` in your AI coding assistant after you've built a **[graphify](https://github.com/safishamsi/graphify)** knowledge base — it patches `graphify-out/graph.json` from your session's query history to evolve your LLM-Wiki.
40
40
 
41
- Works in **Cursor** (install the skill once with `deeprefine cursor install`). In Cursor, `/deeprefine` runs in **agent-native mode** (no extra API key needed). The runtime CLI (`deeprefine refine`) is still available for vLLM/API execution.
41
+ Works in **Cursor** (install the skill once with `deeprefine cursor install`). In Cursor, `/deeprefine` tells the agent to run **`deeprefine refine`** in your project — the full Reafiner loop (judgement → abduction → action generation), not a hand-edited `graph.json`.
42
42
 
43
43
  ```
44
44
  /deeprefine
45
45
  ```
46
46
 
47
- **Typical flow:** `graphify .` → `graphify query "..."` → record the question → `/deeprefine`.
48
-
49
- ```bash
50
- deeprefine history add --query "your question" # or let the agent do this
51
- ```
47
+ **Typical flow:** `graphify .` → `graphify query "..."` → `/deeprefine` (agent runs `deeprefine refine` for session queries).
52
48
 
53
49
  That's it. Under `graphify-out/.deeprefine/` you get:
54
50
 
@@ -62,14 +58,13 @@ graphify-out/
62
58
  ```
63
59
 
64
60
  > **Standalone repo.** Model code (`autorefiner`, `atlas_rag`) lives in a separate [DeepRefine](https://github.com/HKUST-KnowComp/DeepRefine) checkout.
65
- > `pip install deeprefine-cli` ships the CLI and `SKILL.md`. In Cursor, `/deeprefine` uses agent-native refinement; `deeprefine refine` uses DeepRefine runtime (vLLM/API) when you explicitly choose CLI execution.
61
+ > `pip install deeprefine-cli` ships the CLI and `SKILL.md`. `/deeprefine` and terminal `deeprefine refine` both use the same DeepRefine runtime (vLLM or API keys in your shell). Configure inference once in `atlastune`.
66
62
 
67
63
  ---
68
64
 
69
65
  ## News
70
66
 
71
- - [2026/6/2] deeprefine-cli v0.1.5 has been released! Agent-native `/deeprefine` flow + clearer CLI/Agent split.
72
- - [2026/6/2] deeprefine-cli v0.1.4 has been released! Customize your LLM api.
67
+ - [2026/6/2] deeprefine-cli v0.1.6 has been released! Customize your LLM api in CLI.
73
68
 
74
69
  ---
75
70
 
@@ -81,7 +76,7 @@ graphify-out/
81
76
  | 2 | `pip install deeprefine-cli` |
82
77
  | 3 | `deeprefine cursor install` in your KB project |
83
78
  | 4 | (Optional) start local vLLM, or use your API provider |
84
- | 5 | Cursor chat: `/deeprefine` *(auto uses/adds query context)*; CLI mode: `history add` + `refine` |
79
+ | 5 | Cursor chat: `/deeprefine` *(agent runs `deeprefine refine`)*; or terminal: `history add` + `refine` |
85
80
 
86
81
  ```bash
87
82
  # 1) DeepRefine (once)
@@ -110,21 +105,13 @@ export DEEPREFINE_EMBED_MODEL=your_embed_model
110
105
  # export DEEPREFINE_API_KEY=your_shared_api_key
111
106
  # optional model overrides:
112
107
 
113
- # 5a) Refine in Cursor chat (agent-native, recommended)
114
- # type in chat:
115
- # /deeprefine
116
-
117
- # 5b) Refine in terminal / CLI (manual flow)
108
+ # 5) Refine — full Reafiner loop
109
+ # Cursor chat: type /deeprefine (agent runs deeprefine refine --query "..." per session question)
110
+ # Terminal manual flow:
118
111
  deeprefine history add --query "your question"
119
112
  deeprefine refine
120
113
  ```
121
114
 
122
- In **Cursor chat** (agent):
123
-
124
- ```text
125
- /deeprefine
126
- ```
127
-
128
115
  ---
129
116
 
130
117
  ## Pipeline
@@ -141,11 +128,13 @@ In **Cursor chat** (agent):
141
128
  ▼ graphify
142
129
  graph.json ◄────────────────────────┐
143
130
  │ │
144
- ▼ graphify query │ deeprefine refine
145
- (Q&A session) │
131
+ ▼ graphify query "..." │ deeprefine refine
132
+ ▼ graphify query "..." │ (per session query)
133
+ ▼ ... │
134
+ (many Q&A in session) │
146
135
  │ │
147
- ▼ deeprefine history add │
148
- history.jsonl ──────────────────────┘
136
+ ▼ /deeprefine │
137
+ (DeepRefine loop) ────────────────────┘
149
138
  │
150
139
  ▼ graphify query (verify)
151
140
  ```
@@ -266,8 +255,8 @@ deeprefine cursor install
266
255
  |:-:|--------|
267
256
  | 1 | `graphify .` or `/graphify .` → `graphify-out/graph.json` |
268
257
  | 2 | `graphify query "..."` |
269
- | 3 | Cursor chat: `/deeprefine` *(recommended; no manual `history add` needed)* |
270
- | 4 | CLI alternative: `deeprefine history add --query "..."` → `deeprefine refine` |
258
+ | 3 | Cursor chat: `/deeprefine` *(agent runs `deeprefine refine` / `--query` for session questions)* |
259
+ | 4 | Terminal alternative: `deeprefine history add --query "..."` → `deeprefine refine` |
271
260
  | 5 | *(optional)* `graphify query "..."` to verify |
272
261
 
273
262
  ---
deeprefine_cli-0.1.6/deeprefine_skill/SKILL.md ADDED
@@ -0,0 +1,80 @@
1
+ ---
2
+ name: deeprefine
3
+ description: >-
4
+ Refines a graphify knowledge graph (graphify-out/graph.json) using DeepRefine
5
+ Reafiner (judgement, error abduction, KG action generation). Use when the user
6
+ runs /deeprefine, asks to improve the graphify KB after Q&A, or wants to patch
7
+ graph.json from failed retrieval queries.
8
+ disable-model-invocation: false
9
+ ---
10
+
11
+ # DeepRefine (graphify)
12
+
13
+ Refine `graphify-out/graph.json` with the **full DeepRefine Reafiner loop** (multi-hop retrieval → answerable judgement → error abduction → refinement actions). Do **not** hand-edit `graph.json`.
14
+
15
+ ## Setup (once)
16
+
17
+ **DeepRefine-Skill** (CLI + this file) is separate from the **DeepRefine** model repo.
18
+
19
+ ```bash
20
+ conda activate atlastune
21
+ cd /path/to/DeepRefine && pip install -e .
22
+ pip install deeprefine-cli
23
+ export DEEPREFINE_REPO=/path/to/DeepRefine # if not ../DeepRefine
24
+ cd /path/to/your-kb-project
25
+ deeprefine cursor install
26
+ ```
27
+
28
+ **Inference** (required for `deeprefine refine`; configure in the shell where you run commands):
29
+
30
+ - **Local vLLM:** start DeepRefine `scripts/vllm_serve/` (embedding `8128`, refine `8134`), or
31
+ - **API:** set `DEEPREFINE_LLM_URL`, `DEEPREFINE_EMBED_URL`, `DEEPREFINE_LLM_API_KEY`, `DEEPREFINE_EMBED_API_KEY`, and model names.
32
+
33
+ ## `/deeprefine` — run the real Reafiner via CLI
34
+
35
+ When the user invokes `/deeprefine`, **orchestrate** refinement by running the CLI in the **KB project root** (directory containing `graphify-out/graph.json`). The subprocess runs `Reafiner.refine()` — not a free-form graph edit in chat.
36
+
37
+ ### Agent steps
38
+
39
+ 1. **Confirm cwd** is the KB project root (`graphify-out/graph.json` exists).
40
+ 2. **Collect queries** to refine:
41
+ - Prefer questions from **this chat session** after recent `graphify query` / `/graphify query` (user questions about the KB).
42
+ - Optionally check pending history: `deeprefine history list --pending`.
43
+ 3. **Run refinement** (use `atlastune`; do not edit `graph.json` yourself):
44
+
45
+ ```bash
46
+ conda activate atlastune
47
+ # If there are pending entries and they match what the user wants refined:
48
+ deeprefine refine
49
+
50
+ # Otherwise, for each session query (records + refines in one step):
51
+ deeprefine refine --query "exact user question from this session"
52
+ ```
53
+
54
+ 4. **Report results** from CLI stdout: queries processed, node/edge counts, log path under `graphify-out/.deeprefine/refinement_results_*.jsonl`.
55
+ 5. On failure (missing API key, vLLM down, no graph), show the error and tell the user which env vars or vLLM scripts to fix — do not fall back to manual JSON patching.
56
+
57
+ ### Rules
58
+
59
+ | Do | Don't |
60
+ |----|--------|
61
+ | Run `deeprefine refine` / `deeprefine refine --query "..."` | Hand-edit `graphify-out/graph.json` |
62
+ | Use `atlastune` + configured inference | Simulate judgement/abduction in chat only |
63
+ | Use exact user queries from the session | Require the user to run `history add` first in Cursor |
64
+
65
+ ### What runs inside `deeprefine refine`
66
+
67
+ Per query, the DeepRefine runtime executes:
68
+
69
+ 1. Multi-hop subgraph retrieval (FAISS + KG expansion)
70
+ 2. **Answerable judgement** per hop
71
+ 3. **Error abduction** when retrieval fails across hops
72
+ 4. **Refinement action generation** and application to the KG
73
+ 5. Persist updated `graph.json`, FAISS cache, and `history.jsonl` (`refined: true`)
74
+
75
+ ## Paths
76
+
77
+ - History: `graphify-out/.deeprefine/history.jsonl`
78
+ - Log: `graphify-out/.deeprefine/refinement_results_*.jsonl`
79
+ - Backup: `graphify-out/.deeprefine/graph.json.bak`
80
+ - FAISS cache: `graphify-out/.deeprefine/cache/reafiner_data.pkl`
{deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/deeprefine_skill/__init__.py RENAMED
@@ -1,3 +1,3 @@
1
1
  """DeepRefine agent skill: refine graphify graph.json via Reafiner."""
2
2
 
3
- __version__ = "0.1.5"
3
+ __version__ = "0.1.6"
{deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/pyproject.toml RENAMED
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "deeprefine-cli"
7
- version = "0.1.5"
7
+ version = "0.1.6"
8
8
  description = "CLI and Cursor skill to refine graphify knowledge graphs with DeepRefine"
9
9
  readme = "README.md"
10
10
  license = "MIT"
deeprefine_cli-0.1.5/SKILL.md DELETED
@@ -1,62 +0,0 @@
1
- ---
2
- name: deeprefine
3
- description: >-
4
- Refines a graphify knowledge graph (graphify-out/graph.json) using DeepRefine
5
- Reafiner based on session query history. Use when the user runs /deeprefine,
6
- asks to improve the graphify KB after Q&A, or wants to patch graph.json from
7
- failed retrieval queries.
8
- disable-model-invocation: false
9
- ---
10
-
11
- # DeepRefine (graphify)
12
-
13
- Refine a **[graphify](https://github.com/safishamsi/graphify)** `graph.json` with the DeepRefine agent loop.
14
-
15
- ## Setup
16
-
17
- **DeepRefine-Skill** (CLI + this file) is separate from the **DeepRefine** model repo.
18
-
19
- ```bash
20
- # 1) DeepRefine env (atlastune) + main package
21
- conda activate atlastune
22
- cd /path/to/DeepRefine && pip install -e .
23
-
24
- # 2) This skill CLI
25
- pip install deeprefine-cli
26
-
27
- # 3) Optional if DeepRefine is not ../DeepRefine
28
- export DEEPREFINE_REPO=/path/to/DeepRefine
29
-
30
- # 4) Cursor skill in KB project root
31
- cd /path/to/your-kb-project
32
- deeprefine cursor install
33
- ```
34
-
35
- Inference defaults to your current API model setup (`OPENAI_API_KEY` or `DEEPREFINE_API_KEY`).
36
-
37
- Optional: local vLLM from DeepRefine (embedding `8128`, refine model `8134`; see `scripts/vllm_serve/`).
38
-
39
- ## `/deeprefine` (agent-native)
40
-
41
- From the **KB project root** (with `graphify-out/graph.json`):
42
-
43
- ```bash
44
- deeprefine history add --query "..." # after graph Q&A
45
- /deeprefine # run inside agent (no extra API key)
46
- ```
47
-
48
- What the agent should do when `/deeprefine` is invoked:
49
-
50
- 1. Load pending queries from `graphify-out/.deeprefine/history.jsonl`.
51
- 2. Read `graphify-out/graph.json`.
52
- 3. Propose and apply minimal graph updates directly to `graph.json` for unresolved queries.
53
- 4. Write a timestamped log to `graphify-out/.deeprefine/refinement_results_*.jsonl`.
54
- 5. Mark processed history items as `refined: true`.
55
-
56
- Use `deeprefine refine` CLI only when explicitly asked to run DeepRefine runtime (vLLM/API).
57
-
58
- ## Paths
59
-
60
- - History: `graphify-out/.deeprefine/history.jsonl`
61
- - Log: `graphify-out/.deeprefine/refinement_results_*.jsonl`
62
- - Backup: `graphify-out/.deeprefine/graph.json.bak`
deeprefine_cli-0.1.5/deeprefine_skill/SKILL.md DELETED
@@ -1,62 +0,0 @@
1
- ---
2
- name: deeprefine
3
- description: >-
4
- Refines a graphify knowledge graph (graphify-out/graph.json) using DeepRefine
5
- Reafiner based on session query history. Use when the user runs /deeprefine,
6
- asks to improve the graphify KB after Q&A, or wants to patch graph.json from
7
- failed retrieval queries.
8
- disable-model-invocation: false
9
- ---
10
-
11
- # DeepRefine (graphify)
12
-
13
- Refine a **[graphify](https://github.com/safishamsi/graphify)** `graph.json` with the DeepRefine agent loop.
14
-
15
- ## Setup
16
-
17
- **DeepRefine-Skill** (CLI + this file) is separate from the **DeepRefine** model repo.
18
-
19
- ```bash
20
- # 1) DeepRefine env (atlastune) + main package
21
- conda activate atlastune
22
- cd /path/to/DeepRefine && pip install -e .
23
-
24
- # 2) This skill CLI
25
- pip install deeprefine-cli
26
-
27
- # 3) Optional if DeepRefine is not ../DeepRefine
28
- export DEEPREFINE_REPO=/path/to/DeepRefine
29
-
30
- # 4) Cursor skill in KB project root
31
- cd /path/to/your-kb-project
32
- deeprefine cursor install
33
- ```
34
-
35
- Inference defaults to your current API model setup (`OPENAI_API_KEY` or `DEEPREFINE_API_KEY`).
36
-
37
- Optional: local vLLM from DeepRefine (embedding `8128`, refine model `8134`; see `scripts/vllm_serve/`).
38
-
39
- ## `/deeprefine` (agent-native)
40
-
41
- From the **KB project root** (with `graphify-out/graph.json`):
42
-
43
- ```bash
44
- deeprefine history add --query "..." # after graph Q&A
45
- /deeprefine # run inside agent (no extra API key)
46
- ```
47
-
48
- What the agent should do when `/deeprefine` is invoked:
49
-
50
- 1. Load pending queries from `graphify-out/.deeprefine/history.jsonl`.
51
- 2. Read `graphify-out/graph.json`.
52
- 3. Propose and apply minimal graph updates directly to `graph.json` for unresolved queries.
53
- 4. Write a timestamped log to `graphify-out/.deeprefine/refinement_results_*.jsonl`.
54
- 5. Mark processed history items as `refined: true`.
55
-
56
- Use `deeprefine refine` CLI only when explicitly asked to run DeepRefine runtime (vLLM/API).
57
-
58
- ## Paths
59
-
60
- - History: `graphify-out/.deeprefine/history.jsonl`
61
- - Log: `graphify-out/.deeprefine/refinement_results_*.jsonl`
62
- - Backup: `graphify-out/.deeprefine/graph.json.bak`
{deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/LICENSE RENAMED
File without changes
{deeprefine_cli-0.1.5 → deeprefine_cli-0.1.6}/setup.cfg RENAMED
File without changes