tg-show-library-documents

Lists all documents stored in the TrustGraph document library with their metadata.

Synopsis

tg-show-library-documents [options]

Description

The tg-show-library-documents command displays all documents currently stored in TrustGraph’s document library. For each document, it shows comprehensive metadata including ID, timestamp, title, document type, comments, and associated tags.

The document library serves as a centralized repository for managing documents before and after processing through TrustGraph workflows.

Options

Optional Arguments

• -u, --api-url URL: TrustGraph API URL (default: $TRUSTGRAPH_URL or http://localhost:8088/)
• -U, --user USER: User ID to filter documents (default: trustgraph)

Examples

List All Documents

tg-show-library-documents

List Documents for Specific User

tg-show-library-documents -U "research-team"

Using Custom API URL

tg-show-library-documents -u http://production:8088/

Output Format

The command displays each document in a formatted table:

+-------+----------------------------------+
| id    | doc_123456789                    |
| time  | 2023-12-15 10:30:45             |
| title | Technical Manual v2.1           |
| kind  | PDF                              |
| note  | Updated installation procedures  |
| tags  | technical, manual, v2.1          |
+-------+----------------------------------+

+-------+----------------------------------+
| id    | doc_987654321                    |
| time  | 2023-12-14 15:22:10             |
| title | Q4 Financial Report              |
| kind  | PDF                              |
| note  | Quarterly analysis and metrics   |
| tags  | finance, quarterly, 2023         |
+-------+----------------------------------+

Document Properties

• id: Unique document identifier
• time: Upload/creation timestamp
• title: Document title or name
• kind: Document type (PDF, DOCX, TXT, etc.)
• note: Comments or description
• tags: Comma-separated list of tags

Empty Results

If no documents exist:

No documents.

Use Cases

Document Inventory

# Get complete document inventory
tg-show-library-documents > document-inventory.txt

# Count total documents
tg-show-library-documents | grep -c "| id"

Document Discovery

# Find documents by title pattern
tg-show-library-documents | grep -i "manual"

# Find documents by type
tg-show-library-documents | grep "| kind.*PDF"

# Find recent documents
tg-show-library-documents | grep "2023-12"

User-Specific Queries

# List documents by different users
users=("research-team" "finance-dept" "legal-team")
for user in "${users[@]}"; do
  echo "Documents for $user:"
  tg-show-library-documents -U "$user"
  echo "---"
done

Document Management

# Extract document IDs for processing
tg-show-library-documents | \
  grep "| id" | \
  awk '{print $3}' > document-ids.txt

# Find documents by tags
tg-show-library-documents | \
  grep -A5 -B5 "research" | \
  grep "| id" | \
  awk '{print $3}'

Advanced Usage

Document Analysis

# Analyze document distribution by type
analyze_document_types() {
  echo "Document Type Distribution:"
  echo "=========================="
  
  tg-show-library-documents | \
    grep "| kind" | \
    awk '{print $3}' | \
    sort | uniq -c | sort -nr
}

analyze_document_types

Document Age Analysis

# Find old documents
find_old_documents() {
  local days_old="$1"
  
  echo "Documents older than $days_old days:"
  echo "===================================="
  
  cutoff_date=$(date -d "$days_old days ago" +"%Y-%m-%d")
  
  tg-show-library-documents | \
    grep "| time" | \
    while read -r line; do
      doc_date=$(echo "$line" | awk '{print $3}')
      if [[ "$doc_date" < "$cutoff_date" ]]; then
        echo "$line"
      fi
    done
}

# Find documents older than 30 days
find_old_documents 30

Tag Analysis

# Analyze tag usage
analyze_tags() {
  echo "Tag Usage Analysis:"
  echo "=================="
  
  tg-show-library-documents | \
    grep "| tags" | \
    sed 's/| tags.*| \(.*\) |/\1/' | \
    tr ',' '\n' | \
    sed 's/^ *//;s/ *$//' | \
    sort | uniq -c | sort -nr
}

analyze_tags

Document Search

# Search documents by multiple criteria
search_documents() {
  local query="$1"
  
  echo "Searching for: $query"
  echo "===================="
  
  tg-show-library-documents | \
    grep -i -A6 -B6 "$query" | \
    grep -E "^\+|^\|"
}

# Search for specific terms
search_documents "financial"
search_documents "manual"

User Document Summary

# Generate user document summary
user_summary() {
  local user="$1"
  
  echo "Document Summary for User: $user"
  echo "================================"
  
  docs=$(tg-show-library-documents -U "$user")
  
  if [[ "$docs" == "No documents." ]]; then
    echo "No documents found for user: $user"
    return
  fi
  
  # Count documents
  doc_count=$(echo "$docs" | grep -c "| id")
  echo "Total documents: $doc_count"
  
  # Count by type
  echo -e "\nBy type:"
  echo "$docs" | \
    grep "| kind" | \
    awk '{print $3}' | \
    sort | uniq -c | sort -nr
  
  # Recent documents
  echo -e "\nRecent documents (last 7 days):"
  recent_date=$(date -d "7 days ago" +"%Y-%m-%d")
  echo "$docs" | \
    grep "| time" | \
    awk -v cutoff="$recent_date" '$3 >= cutoff {print $0}'
}

# Generate summary for specific user
user_summary "research-team"

Document Export

# Export document metadata to CSV
export_to_csv() {
  local output_file="$1"
  
  echo "id,time,title,kind,note,tags" > "$output_file"
  
  tg-show-library-documents | \
    awk '
    BEGIN { record="" }
    /^\+/ { 
      if (record != "") {
        print record
        record=""
      }
    }
    /^\| id/ { gsub(/^\| id *\| /, ""); gsub(/ *\|$/, ""); record=$0"," }
    /^\| time/ { gsub(/^\| time *\| /, ""); gsub(/ *\|$/, ""); record=record$0"," }
    /^\| title/ { gsub(/^\| title *\| /, ""); gsub(/ *\|$/, ""); record=record$0"," }
    /^\| kind/ { gsub(/^\| kind *\| /, ""); gsub(/ *\|$/, ""); record=record$0"," }
    /^\| note/ { gsub(/^\| note *\| /, ""); gsub(/ *\|$/, ""); record=record$0"," }
    /^\| tags/ { gsub(/^\| tags *\| /, ""); gsub(/ *\|$/, ""); record=record$0 }
    END { if (record != "") print record }
    ' >> "$output_file"
  
  echo "Exported to: $output_file"
}

# Export to CSV
export_to_csv "documents.csv"

Document Monitoring

# Monitor document library changes
monitor_documents() {
  local interval="$1"
  local log_file="document_changes.log"
  
  echo "Monitoring document library (interval: ${interval}s)"
  echo "Log file: $log_file"
  
  # Get initial state
  tg-show-library-documents > last_state.tmp
  
  while true; do
    sleep "$interval"
    
    # Get current state
    tg-show-library-documents > current_state.tmp
    
    # Compare states
    if ! diff -q last_state.tmp current_state.tmp > /dev/null; then
      timestamp=$(date)
      echo "[$timestamp] Document library changed" >> "$log_file"
      
      # Log differences
      diff last_state.tmp current_state.tmp >> "$log_file"
      echo "---" >> "$log_file"
      
      # Update last state
      mv current_state.tmp last_state.tmp
      
      echo "[$timestamp] Changes detected and logged"
    else
      rm current_state.tmp
    fi
  done
}

# Monitor every 60 seconds
monitor_documents 60

Bulk Operations Helper

# Generate commands for bulk operations
generate_bulk_commands() {
  local operation="$1"
  
  case "$operation" in
    "remove-old")
      echo "# Commands to remove old documents:"
      cutoff_date=$(date -d "90 days ago" +"%Y-%m-%d")
      tg-show-library-documents | \
        grep -B1 "| time.*$cutoff_date" | \
        grep "| id" | \
        awk '{print "tg-remove-library-document --id " $3}'
      ;;
    "process-unprocessed")
      echo "# Commands to process documents:"
      tg-show-library-documents | \
        grep "| id" | \
        awk '{print "tg-start-library-processing -d " $3 " --id proc-" $3}'
      ;;
    *)
      echo "Unknown operation: $operation"
      echo "Available: remove-old, process-unprocessed"
      ;;
  esac
}

# Generate removal commands for old documents
generate_bulk_commands "remove-old"

Integration with Other Commands

Document Processing Workflow

# Complete document workflow
process_document_workflow() {
  echo "Document Library Workflow"
  echo "========================"
  
  # 1. List current documents
  echo "Current documents:"
  tg-show-library-documents
  
  # 2. Add new document (example)
  # tg-add-library-document --file new-doc.pdf --title "New Document"
  
  # 3. Start processing
  # tg-start-library-processing -d doc_id --id proc_id
  
  # 4. Monitor processing
  # tg-show-flows | grep processing
  
  # 5. Verify completion
  echo "Documents after processing:"
  tg-show-library-documents
}

Document Lifecycle Management

# Manage document lifecycle
lifecycle_management() {
  echo "Document Lifecycle Management"
  echo "============================"
  
  # Get all documents
  tg-show-library-documents | \
    grep "| id" | \
    awk '{print $3}' | \
    while read doc_id; do
      echo "Processing document: $doc_id"
      
      # Check if already processed
      if tg-invoke-document-rag -q "test" 2>/dev/null | grep -q "$doc_id"; then
        echo "  Already processed"
      else
        echo "  Starting processing..."
        # tg-start-library-processing -d "$doc_id" --id "proc-$doc_id"
      fi
    done
}

Error Handling

Connection Issues

Exception: Connection refused

Solution: Check API URL and ensure TrustGraph is running.

Permission Errors

Exception: Access denied

Solution: Verify user permissions for library access.

User Not Found

Exception: User not found

Solution: Check user ID spelling and ensure user exists.

Environment Variables

• TRUSTGRAPH_URL: Default API URL

Related Commands

• tg-add-library-document - Add documents to library
• tg-remove-library-document - Remove documents from library
• tg-start-library-processing - Start document processing
• tg-stop-library-processing - Stop document processing
• tg-invoke-document-rag - Query processed documents

API Integration

This command uses the Library API to retrieve document metadata and listings.

Best Practices

1. Regular Monitoring: Check library contents regularly
2. User Organization: Use different users for different document categories
3. Tag Consistency: Maintain consistent tagging schemes
4. Cleanup: Regularly remove outdated documents
5. Backup: Export document metadata for backup purposes
6. Access Control: Use appropriate user permissions
7. Documentation: Maintain good document titles and descriptions

Troubleshooting

No Documents Shown

# Check if documents exist for different users
tg-show-library-documents -U "different-user"

# Verify API connectivity
curl -s "$TRUSTGRAPH_URL/api/v1/library/documents" > /dev/null
echo "API response: $?"

Formatting Issues

# If output is garbled, check terminal width
export COLUMNS=120
tg-show-library-documents

Slow Response

# For large document libraries, consider filtering by user
tg-show-library-documents -U "specific-user"

# Check system resources
free -h
ps aux | grep trustgraph