Metadata-Version: 2.4
Name: deeprefine-cli
Version: 0.1.3
Summary: CLI and Cursor skill to refine graphify knowledge graphs with DeepRefine
Author: HKUST-KnowComp
License-Expression: MIT
Project-URL: Homepage, https://github.com/HKUST-KnowComp/DeepRefine
Project-URL: Documentation, https://github.com/HKUST-KnowComp/DeepRefine
Project-URL: Repository, https://github.com/HKUST-KnowComp/DeepRefine
Project-URL: Issues, https://github.com/HKUST-KnowComp/DeepRefine/issues
Keywords: deeprefine,graphify,knowledge-graph,rag,cursor,agent-skill
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0
Dynamic: license-file

# DeepRefine-Skill

Cursor skill and CLI to refine **[graphify](https://github.com/safishamsi/graphify)** knowledge graphs with **[DeepRefine](https://github.com/HKUST-KnowComp/DeepRefine)** (`graphify-out/graph.json` + session query history).

This repository is **standalone**. The DeepRefine model code (`autorefiner`, `atlas_rag`) lives in a separate **DeepRefine** checkout.

---

## Repository layout

```
DeepRefine-Skill/          ← this repo (pip install -e .)
├── README.md
├── SKILL.md
├── pyproject.toml
├── deeprefine_skill/
└── scripts/deeprefine.py

DeepRefine/                ← separate clone (training + Reafiner)
├── autorefiner/
├── AutoSchemaKG/
└── ...

your-kb-project/           ← your data (graphify-out/)
└── graphify-out/graph.json
```

Recommended clone layout:

```text
www/code/
├── DeepRefine/
└── DeepRefine-Skill/      # sibling → auto-detected if DEEPREFINE_REPO unset
```

---

## How graphify and DeepRefine fit together

| Stage | Tool | Input | Output |
|-------|------|-------|--------|
| Build | **graphify** | Project files | `graphify-out/graph.json`, report, HTML |
| Query | **graphify** | Questions | `graphify query "..."` |
| Refine | **DeepRefine** (this repo) | Graph + **query history** | Updated `graph.json`, logs |

DeepRefine does not build the graph; it edits `graph.json` incrementally so later `graphify query` works better.

---

## Setup

### 1. DeepRefine environment (`atlastune`)

Follow [DeepRefine/README](https://github.com/HKUST-KnowComp/DeepRefine) **Environment** to create `atlastune` and install the main repo:

```bash
conda activate atlastune
cd /path/to/DeepRefine
pip install -e .
```

### 2. Install this CLI

**From PyPI:**

```bash
conda activate atlastune
pip install deeprefine-cli
```

**From source (development):**

```bash
pip install -e /path/to/DeepRefine-Skill
```

Verify:

```bash
deeprefine --help
```

> `deeprefine refine` still requires a local [DeepRefine](https://github.com/HKUST-KnowComp/DeepRefine) checkout (`autorefiner`, `atlas_rag`) and running vLLM services — see below.

### 3. Point to DeepRefine (if not cloned as sibling)

Only needed when `DeepRefine` is **not** at `../DeepRefine` relative to this repo and not found by walking up from your cwd:

```bash
export DEEPREFINE_REPO=/path/to/DeepRefine
```

Add to `~/.bashrc` if you use a fixed path.

### 4. Start vLLM (before `deeprefine refine`)

From the **DeepRefine** repo:

```bash
conda activate atlastune
bash /path/to/DeepRefine/scripts/vllm_serve/qwen3-0.6b-emb.sh
bash /path/to/DeepRefine/scripts/vllm_serve/qwen3-8b-vllm-reafiner.sh
```

| Variable | Default |
|----------|---------|
| `DEEPREFINE_LLM_URL` | `http://127.0.0.1:8134/v1` |
| `DEEPREFINE_EMBED_URL` | `http://127.0.0.1:8128/v1` |
| `DEEPREFINE_MODEL` | `HaoyuHuang2/DeepRefine-v1-8B` |
| `DEEPREFINE_EMBED_MODEL` | `Qwen/Qwen3-Embedding-0.6B` |

### 5. Install Cursor skill (KB project root)

```bash
cd /path/to/your-kb-project    # must contain or will contain graphify-out/
deeprefine cursor install
```

Same pattern as `graphify cursor install`. Use `--user` for all projects.

---

## Workflow with graphify

**One-time**

```bash
pip install graphifyy
graphify cursor install          # in KB project
pip install -e /path/to/DeepRefine-Skill   # in atlastune
deeprefine cursor install        # in KB project
```

**Per session** (KB project root)

1. `/graphify .` or `graphify .` → `graphify-out/graph.json`
2. `graphify query "..."` or `/graphify query "..."`
3. `deeprefine history add --query "..."`
4. `/deeprefine` or `deeprefine refine`
5. Optional: `graphify query "..."` again to verify

```
project files ──graphify──► graph.json
                                 │
                       graphify query
                                 │
                 deeprefine history add
                                 │
                 deeprefine refine
                                 │
                       graphify query
```

---

## Command cheat sheet (KB project root)

```bash
deeprefine history add --query "..."
deeprefine history list --pending
deeprefine refine
deeprefine refine --query "..."
deeprefine index --rebuild
```

---

## Where to run commands

| Command | Directory |
|---------|-----------|
| `pip install -e .../DeepRefine-Skill` | Any |
| `pip install -e .../DeepRefine` | DeepRefine repo |
| `graphify` / `deeprefine cursor install` | **KB project root** |
| `deeprefine refine` | **KB project root** |
| vLLM serve scripts | **DeepRefine repo** |

Agent instructions: [SKILL.md](./SKILL.md).

---

## Publish to PyPI (maintainers)

```bash
cd /path/to/DeepRefine-Skill
python -m pip install --upgrade build twine
python -m build
twine check dist/*
twine upload dist/*    # needs PyPI token: TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-...
```

Test install from TestPyPI first (optional):

```bash
twine upload --repository testpypi dist/*
pip install -i https://test.pypi.org/simple/ deeprefine-cli
```
