yProvTalk

Conversational AI over W3C-PROV provenance graphs.

yProvTalk lets you import PROV-JSON workflow traces into Memgraph and ask natural language questions through a CLI chat interface or HTTP API.

What It Does

• Imports large PROV-JSON files into Memgraph using batched writes.
• Preserves W3C-PROV node types (Entity, Activity, Agent) and relationships.
• Uses Ollama as the local/self-hosted LLM backend.
• Supports interactive chat, one-shot questions, health checks, and API serving.

Requirements

• Python 3.10+
• Memgraph (reachable via Bolt)
• Ollama (reachable via HTTP)

Installation

python -m venv .venv
source .venv/bin/activate
pip install -e .

For development extras:

pip install -e .[dev]

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env values as needed:

• OLLAMA_HOST
• OLLAMA_MODEL
• MEMGRAPH_URI
• MEMGRAPH_USER
• MEMGRAPH_PASSWORD

The app loads .env automatically through pydantic-settings.

Quick Start

1. Verify services are reachable:

yprovtalk health

2. Import a PROV-JSON file:

yprovtalk import /path/to/session.prov.json --pid run_001

3. Start chat:

yprovtalk chat

4. Ask a single question:

yprovtalk ask "Which activities used the generated model artifact?"

CLI Commands

yprovtalk chat
yprovtalk ask "<question>"
yprovtalk import <file> [--pid <source_pid>]
yprovtalk serve --host 0.0.0.0 --port 8080
yprovtalk health

HTTP API

When running:

yprovtalk serve --host 0.0.0.0 --port 8080

Available endpoints:

• POST /chat -> ask a question and get model response
• GET /health -> checks Memgraph and Ollama connectivity
• GET /graph/{pid} -> returns graph nodes and links for visualization

Example:

curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Show me all agents involved in this run"}'

Import Notes

• Import is optimized for large files with batched node/edge writes.
• Indexes are created automatically when importing.
• Duplicate import detection is based on source_pid.

Project Layout

src/yprovtalk/
  agent/        # ReAct loop, prompts, conversation memory
  api/          # FastAPI app
  importer/     # PROV-JSON -> Memgraph importer
  tools/        # Graph query tools and dispatcher
  settings.py   # Env-driven configuration
  __main__.py   # Typer CLI entrypoint

License

GPL-3.0-or-later