# 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:

```bash
# 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:

```python
# 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:

```python
# 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

```python
# 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

```python
# 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

```python
# 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

```python
# 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