# experiment

**Repository Path**: cxcy666_admin/experiment

## Basic Information

- **Project Name**: experiment
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KGDemo: LLM-Constructed KG for Multi-Hop QA

This repository contains the experimental system for constructing a sample-level
knowledge graph from HotpotQA context, navigating it with adaptive ToG and RoG,
querying evidence with Cypher, and evaluating grounded multi-hop answers.

## Main Pipeline

```text
HotpotQA context
  -> LLM triple extraction with relation semantics
  -> Neo4j sample graph with two-hop lookahead
  -> ToG local exploration + RoG planning assistance
  -> Cypher evidence retrieval and LLM evidence fusion
  -> grounded answer validation and HotpotQA evaluation
```

The final LLM answer judge receives the complete retained evidence bundle: graph
nodes, edges, relation direction, semantic aliases, relation glosses, source
sentences, ToG/RoG paths, and Cypher rows. Rule-based answer-role checks are
telemetry only and cannot select or override an answer.

## Setup

```bash
uv sync
cp .env.example .env
```

Configure an OpenAI-compatible LLM endpoint and a Neo4j instance in `.env`.
The experiment console also supports MySQL; it falls back to a local SQLite
database when MySQL is unavailable.

Start the console API and frontend:

```bash
.venv/bin/python -m uvicorn experiment_console.app:app --host 127.0.0.1 --port 8000
cd experiment_console/web && npm install && npm run dev -- --host 127.0.0.1 --port 5173
```

## Reproducible Data

The repository includes the two generated HotpotQA 500-example subsets used by
the current experiments, together with sampling metadata:

- `data/hotpotqa/hotpot_complete_random500_proportional_seed20260810.json`
- `data/hotpotqa/hotpot_dev_random500_gbv41_seed20260810.json`

The upstream HotpotQA train/dev corpora are intentionally not mirrored here.
Download them separately from the source documented in
`data/hotpotqa/README.md`. The scripts under `scripts/` can produce new random
or proportional samples once the source data is present.

## Running Tests

```bash
PYTHONPATH=. uv run --with pytest pytest -q
```

## Key Directories

- `edc_experiment/`: LLM-driven evidence and relation extraction.
- `hotpot_experiment/`: HotpotQA construction, repair, evaluation, and Cypher agent.
- `tog_experiment/`: Neo4j-backed ToG, RoG planning, and evidence-first answer logic.
- `experiment_console/`: FastAPI and Vue 3 visualization console.
- `tests/`: regression coverage for grounding and multi-hop constraints.
- `outputs/`: curated reports only; raw prompts, logs, and oversized intermediate
  graph files are ignored for safety and repository size.