Skip to content

REPL Demo Guide

This guide demonstrates the Complex Network RAG REPL (Read-Eval-Print Loop) - an interactive shell for exploring and querying knowledge graphs.

Starting the REPL

# From command line
network-rag repl

# Or directly
python -m src.repl

Example Session: Research Papers

Here's a complete workflow for building and exploring a research paper knowledge graph:

1. Connect to Database

[no db]> db connect papers.db
✓ Connected to papers.db

2. Add Documents

papers.db> add "Attention Is All You Need - introducing the Transformer architecture"
✓ Added document: <uuid>

papers.db [1 docs]> add "BERT: Pre-training of Deep Bidirectional Transformers for NLP"
✓ Added document: <uuid>

papers.db [2 docs]> add "Language Models are Few-Shot Learners - introducing GPT-3"
✓ Added document: <uuid>

3. Build Network

papers.db [3 docs]> build
ℹ Fitting TF-IDF vectorizer...
ℹ Building network...
✓ Network built: 3 nodes, 2 edges

papers.db [3 docs, 2 edges]>

Note how the prompt now shows edge count!

4. Explore Network

papers.db [3 docs, 2 edges]> graph info

Network Statistics
========================================
Nodes: 3
Edges: 2
Density: 0.667
Average degree: 1.3

5. Detect Communities

papers.db [3 docs, 2 edges]> graph communities

Detected 1 communities:

Community 0: 3 nodes
  - <transformer_id>
  - <bert_id>
  - <gpt_id>

papers.db [3 docs, 2 edges]> search "transformers for language"
Search: transformers for language
Found 3 results:

1. <transformer_id> (score: 0.892)
   Attention Is All You Need - introducing the Transformer architecture

2. <bert_id> (score: 0.745)
   BERT: Pre-training of Deep Bidirectional Transformers for NLP...

3. <gpt_id> (score: 0.621)
   Language Models are Few-Shot Learners - introducing GPT-3

7. Inspect Documents

papers.db [3 docs, 2 edges]> show <transformer_id>

ID: <transformer_id>
Content:
  Attention Is All You Need - introducing the Transformer architecture
Metadata:

8. Database Info

papers.db [3 docs, 2 edges]> db info

Database: papers.db
  Size: 12.45 KB
  Documents: 3
  Embeddings: 3

9. List Documents

papers.db [3 docs, 2 edges]> db list

Documents (3 total, showing first 3):

ID: <transformer_id>
  Content: Attention Is All You Need - introducing the Transformer architecture

ID: <bert_id>
  Content: BERT: Pre-training of Deep Bidirectional Transformers for NLP

ID: <gpt_id>
  Content: Language Models are Few-Shot Learners - introducing GPT-3

Available Commands

Database Management

  • db connect <path> - Connect to database (use :memory: for temporary)
  • db info - Show database statistics
  • db list [--limit N] - List documents
  • db close - Close current database

Document Operations

  • add <content> - Add a document
  • show <id> - Show document details

Network Operations

  • build [--rebuild] - Build knowledge graph
  • graph info - Show network statistics
  • graph communities - Detect and display communities

Search & Retrieval

  • search <query> [--top-k N] - Search for similar documents

Utility

  • help [command] - Show help
  • quit or exit - Exit REPL

Tips

Contextual Prompt

The prompt shows your current state:

  • [no db]> - Not connected
  • papers.db> - Connected, no documents
  • papers.db [5 docs]> - Connected with documents
  • papers.db [5 docs, 8 edges]> - Network built

Quick Start with In-Memory Database

For quick experiments without creating files:

[no db]> db connect :memory:
✓ Connected to memory

memory> add "Test document 1"
✓ Added document: <uuid>

memory> add "Test document 2"
✓ Added document: <uuid>

memory> build
✓ Network built: 2 nodes, 1 edges

memory [2 docs, 1 edges]> search "test"
...

Command History

Use arrow keys to navigate command history: - ↑ - Previous command - ↓ - Next command

Interrupting Operations

  • Ctrl+C - Cancel current command (returns to prompt)
  • Ctrl+D or quit - Exit REPL

Use Cases

1. Quick Prototyping

Test document similarity strategies without writing code:

> db connect :memory:
> add "Document 1"
> add "Document 2"
> build
> search "document"

2. Database Exploration

Understand an existing database:

> db connect existing.db
> db info
> db list --limit 20
> build
> graph info
> graph communities

3. Iterative Development

Build and test incrementally:

> db connect dev.db
> add "New document..."
> build --rebuild
> search "test query"
# Repeat as needed

Configuration Management (Phase 2)

Create Configuration from Template

papers.db [3 docs, 2 edges]> config new --template papers
✓ Created configuration from 'papers' template

Interactive Configuration Wizard

[no db]> config new

=== Configuration Builder Wizard ===

Step 1: Document Type
--------------------

  1. Research Papers
  2. E-commerce Products
  3. Chat Messages
  4. Custom (define your own)

Select document type [1]: 1
✓ Using template: Research Papers

...

✓ Configuration created successfully

Show Current Configuration

papers.db> config show

Current Configuration
==================================================

Document Fields:
  • title (embedded)
  • abstract (embedded)
  • authors
  • tags

Similarity Components:
  1. Field Embedding: title
     Model: tfidf, Weight: 0.30
  2. Field Embedding: abstract (chunking: sentences)
     Model: tfidf, Weight: 0.50
  3. Attribute Similarity: authors
     Metric: jaccard, Weight: 0.10
  4. Attribute Similarity: tags
     Metric: jaccard, Weight: 0.10

Minimum Combined Similarity: 0.4

Save Configuration to YAML

papers.db> config save papers_config.yaml
✓ Saved configuration to papers_config.yaml

Load Configuration from YAML

[no db]> config load papers_config.yaml
✓ Loaded configuration from papers_config.yaml

Coming Soon

Future REPL features (Phase 3+):

  • Edge inspection: inspect edge <id1> <id2> with component breakdown
  • Session persistence: save session / load session
  • Script export: export script setup.py
  • Auto-completion: Tab completion for commands and IDs
  • Enhanced visualization: ASCII graphs and charts
  • Import commands: import <file.jsonl>

Troubleshooting

"No database connected"

You need to connect first: 

> db connect papers.db

"Network not built"

Build the network before searching: 

> build

"No documents in database"

Add some documents: 

> add "Your content here"

REPL won't start

Make sure you have the package installed: 

pip install -e .

Feedback

This is Phase 1 (MVP) of the REPL. Feedback welcome!

  • What features would be most useful?
  • What commands are confusing?
  • What's missing?