Skip to content

Three Interfaces

Complex Network RAG provides three ways to interact with the system, each optimized for different use cases.

1. YAML DSL (Configuration)

Best for: Declarative configuration, version control, reproducibility

# config/papers.yaml
document:
  fields:
    - name: title
      type: text
    - name: abstract
      type: text

similarity:
  components:
    - type: field_embedding
      field: title
      weight: 0.3
    - type: field_embedding
      field: abstract
      weight: 0.7
  min_combined_similarity: 0.4

Use when: - You want declarative configuration - You need to version control your similarity strategy - You want to share configurations with others - You're setting up production systems

Learn more: YAML DSL Reference

2. Python API (Fluent)

Best for: Integration into applications, notebooks, production code

from src.fluent import NetworkBuilder

# Fluent API with method chaining
rag = (NetworkBuilder()
    .with_storage("papers.db")
    .with_tfidf_embeddings()
    .with_structured_similarity(
        document_type='papers',
        field_embeddings=['title', 'abstract'],
        attribute_similarity={'tags': 'jaccard'}
    )
    .build())

# Add documents
rag.add({"title": "...", "abstract": "...", "tags": ["ML"]})

# Search
results = rag.search("transformers").top(5)
for result in results:
    print(f"{result.id}: {result.score}")

Use when: - You're integrating into a Python application - You want programmatic control - You're working in Jupyter notebooks - You need to customize behavior dynamically

Learn more: Fluent API Guide

3. CLI (Command-Line)

Best for: Shell scripts, automation, CI/CD pipelines

# Each command is independent
network-rag add papers.db "Document content..."
network-rag build papers.db
network-rag search papers.db "query" --top-k 5
network-rag info papers.db

# Scriptable
for doc in *.txt; do
  network-rag add papers.db "$(cat $doc)"
done

Use when: - You're writing shell scripts - You need command-line automation - You're building CI/CD pipelines - You want one-off operations

Learn more: CLI Reference

4. REPL (Interactive Shell)

Best for: Exploration, prototyping, learning

$ network-rag repl

[no db]> db connect papers.db
papers.db> add "Test document"
papers.db [1 docs]> build
papers.db [1 docs, 0 edges]> search "test"

Use when: - You're exploring a dataset - You're prototyping similarity strategies - You're learning the system - You want interactive feedback

Learn more: REPL Guide

Comparison Matrix

Feature YAML DSL Python API CLI REPL
State Declarative In-memory objects Stateless Stateful session
Use Case Configuration Integration Automation Exploration
Reproducibility ✅ Excellent ⚠️ Code-dependent ✅ Scriptable ❌ Manual
Flexibility ⚠️ Structured ✅ Full control ⚠️ Limited ✅ Interactive
Learning Curve Easy Medium Easy Very Easy
Version Control ✅ Native ⚠️ Code ✅ Scripts ❌ No
Best For Production Applications Scripts Learning

Mixing Interfaces

You can combine interfaces for different stages:

Development Workflow

  1. REPL - Explore dataset and prototype
  2. YAML - Export working configuration
  3. API - Integrate into application
  4. CLI - Automate deployment

Example

# 1. Prototype in REPL
$ network-rag repl
[no db]> config new --template papers
[no db]> config save papers.yaml

# 2. Use YAML in Python
from src.network_rag import NetworkRAG
rag = NetworkRAG.from_config('papers.yaml')

# 3. Automate with CLI
network-rag build papers.db --config papers.yaml

Next Steps