Shell

This guide explains how to use the DataBridge interactive shell for quick experimentation and debugging.

Getting Started

The DataBridge shell provides an interactive Python environment with the SDK pre-configured. To start the shell:

# Without authentication (connects to localhost:8000):
python shell.py

# With authentication (using a generated URI):
python shell.py "databridge://user:token@localhost:8000"

The shell will automatically:

• Connect to http://localhost:8000 if no URI is provided

• Convert databridge:// to http:// for localhost URIs

• Handle authentication when a URI with credentials is provided

Basic Usage

Once the shell starts, you'll have access to a db object that provides all SDK functionality:

# Ingest text content
doc = db.ingest_text(
    content="Machine learning is fascinating...",
    metadata={"title": "ML Introduction"}
)
print(f"Document ID: {doc['external_id']}")

# Ingest a file
doc = db.ingest_file(
    file="research_paper.pdf",
    filename="research_paper.pdf",
    metadata={"category": "research"}
)
print(f"Document ID: {doc['external_id']}")

# Search for content
chunks = db.retrieve_chunks(
    query="What are the key findings?",
    filters={"category": "research"},
    k=4,
    min_score=0.7
)

for chunk in chunks:
    print(f"Score: {chunk['score']}")
    print(f"Content: {chunk['content']}")
    print("---")

Features

The shell environment includes:

• Tab completion for methods and attributes

• Command history (use arrow keys)

• Access to all SDK functionality

• Pretty-printed results

• Built-in help system

Getting Help

To see available methods and documentation:

# List all available methods
help(db)

# Get help for a specific method
help(db.ingest_text)
help(db.retrieve_chunks)

Shell Tips

1. Command History

   • Use up/down arrow keys to cycle through previous commands

   • Commands persist between sessions

2. Tab Completion

   • Press Tab to complete method names

   • Press Tab twice to see all available completions

3. Multiline Input

   • For long commands, you can write multiple lines

   • The shell will wait for complete Python statements

4. Exit

   • Use Ctrl+D or type exit() to exit the shell

Common Tasks

Document Management

# List recent documents
docs = db.list_documents(limit=5)
for doc in docs:
    print(f"ID: {doc['external_id']}")
    print(f"Title: {doc['metadata'].get('title')}")
    print("---")

# Get document by ID
doc = db.get_document("doc_123")
print(f"Content Type: {doc['content_type']}")
print(f"Metadata: {doc['metadata']}")

Search Operations

# Basic search
results = db.retrieve_chunks("machine learning applications")

# Search with filters
results = db.retrieve_chunks(
    query="machine learning",
    filters={"category": "research", "year": 2024}
)

# Document-level search
docs = db.retrieve_docs(
    query="machine learning",
    k=4,
    min_score=0.7
)

Completions

# Generate completion
response = db.complete(
    prompt="Summarize the key findings",
    context_filter={"category": "research"}
)
print(f"Completion: {response['text']}")
print(f"Tokens Used: {response['usage']['total_tokens']}")

Usage Analytics

# Get recent usage
from datetime import datetime, timedelta

usage = db.get_recent_usage(
    since=datetime.now() - timedelta(days=7),
    operation_type="search"
)

for record in usage:
    print(f"Operation: {record['operation_type']}")
    print(f"Tokens: {record['tokens_used']}")
    print(f"Duration: {record['duration_ms']}ms")

Next Steps

After getting comfortable with the shell:

1. Write scripts for automated tasks

2. Set up proper error handling

3. Implement production workflows

4. Use the SDK in your applications