gb/ALWAYS.md

# ALWAYS.md - THINK KB Keyword Documentation

## Overview

The `THINK KB` keyword provides explicit knowledge base reasoning capabilities, allowing bots to perform structured semantic searches across active knowledge bases and return detailed results for analysis and decision-making.

## Syntax

```basic
results = THINK KB "query_text"
results = THINK KB query_variable
```

## Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `query_text` | String | The question or search query to execute against active KBs |
| `query_variable` | Variable | Variable containing the search query |

## Return Value

The `THINK KB` keyword returns a structured object containing:

```basic
{
  "results": [
    {
      "content": "Relevant text content from document",
      "source": "path/to/source/document.pdf", 
      "kb_name": "knowledge_base_name",
      "relevance": 0.85,
      "tokens": 150
    }
  ],
  "summary": "Brief summary of findings",
  "confidence": 0.78,
  "total_results": 5,
  "sources": ["doc1.pdf", "doc2.md"],
  "query": "original search query",
  "kb_count": 2
}
```

### Result Fields

| Field | Type | Description |
|-------|------|-------------|
| `results` | Array | Array of search results with content and metadata |
| `summary` | String | Human-readable summary of the search findings |
| `confidence` | Number | Overall confidence score (0.0 to 1.0) |
| `total_results` | Number | Total number of results found |
| `sources` | Array | List of unique source documents |
| `query` | String | The original search query |
| `kb_count` | Number | Number of knowledge bases searched |

### Individual Result Fields

| Field | Type | Description |
|-------|------|-------------|
| `content` | String | The relevant text content from the document |
| `source` | String | Path to the source document |
| `kb_name` | String | Name of the knowledge base containing this result |
| `relevance` | Number | Relevance score (0.0 to 1.0) |
| `tokens` | Number | Estimated token count for this content |

## Examples

### Basic Knowledge Base Query

```basic
' Activate knowledge bases first
USE KB "company_policies"
USE KB "hr_handbook"

' Perform structured search
results = THINK KB "What is the remote work policy?"

' Access results
TALK results.summary
PRINT "Confidence: " + results.confidence
PRINT "Found " + results.total_results + " results"

' Process individual results
FOR i = 0 TO results.results.length - 1
  result = results.results[i]
  PRINT "Source: " + result.source
  PRINT "Relevance: " + result.relevance
  PRINT "Content: " + result.content
  PRINT "---"
NEXT i
```

### Decision Making with Confidence Thresholds

```basic
USE KB "technical_docs"
USE KB "troubleshooting"

query = "How to fix database connection errors?"
results = THINK KB query

IF results.confidence > 0.8 THEN
  TALK "I found reliable information: " + results.summary
  ' Show top result
  IF results.total_results > 0 THEN
    top_result = results.results[0]
    TALK "Best match from: " + top_result.source
    TALK top_result.content
  END IF
ELSE IF results.confidence > 0.5 THEN
  TALK "I found some relevant information, but I'm not completely certain: " + results.summary
ELSE
  TALK "I couldn't find reliable information about: " + query
  TALK "You might want to consult additional resources."
END IF
```

### Comparative Analysis

```basic
USE KB "product_specs"
USE KB "competitor_analysis"

' Compare multiple queries
queries = ["pricing strategy", "feature comparison", "market positioning"]

FOR i = 0 TO queries.length - 1
  query = queries[i]
  results = THINK KB query
  
  PRINT "=== Analysis: " + query + " ==="
  PRINT "Confidence: " + results.confidence
  PRINT "Sources: " + results.sources.length
  PRINT "Summary: " + results.summary
  PRINT ""
NEXT i
```

### Source-Based Filtering

```basic
USE KB "legal_documents"

results = THINK KB "contract termination clauses"

' Filter by source type
pdf_results = []
FOR i = 0 TO results.results.length - 1
  result = results.results[i]
  IF result.source CONTAINS ".pdf" THEN
    pdf_results.push(result)
  END IF
NEXT i

TALK "Found " + pdf_results.length + " results from PDF documents"
```

### Dynamic Query Building

```basic
USE KB "customer_support"

customer_issue = HEAR "What's your issue?"
priority = HEAR "What's the priority level?"

' Build contextual query
query = customer_issue + " priority:" + priority + " resolution steps"
results = THINK KB query

IF results.confidence > 0.7 THEN
  TALK "Here's what I found for your " + priority + " priority issue:"
  TALK results.summary
  
  ' Show most relevant result
  IF results.total_results > 0 THEN
    best_result = results.results[0]
    TALK "From " + best_result.source + ":"
    TALK best_result.content
  END IF
ELSE
  TALK "I need to escalate this issue. Let me connect you with a human agent."
END IF
```

## Advanced Usage Patterns

### Multi-Stage Reasoning

```basic
USE KB "research_papers"
USE KB "case_studies"

' Stage 1: Find general information
general_results = THINK KB "machine learning applications"

' Stage 2: Drill down based on initial findings
IF general_results.confidence > 0.6 THEN
  ' Extract key terms from top results for refined search
  specific_query = "deep learning " + general_results.results[0].content.substring(0, 50)
  specific_results = THINK KB specific_query
  
  TALK "General overview: " + general_results.summary
  TALK "Specific details: " + specific_results.summary
END IF
```

### Quality Assessment

```basic
USE KB "quality_standards"

results = THINK KB "ISO certification requirements"

' Assess result quality
high_quality_results = []
FOR i = 0 TO results.results.length - 1
  result = results.results[i]
  IF result.relevance > 0.8 AND result.tokens > 100 THEN
    high_quality_results.push(result)
  END IF
NEXT i

IF high_quality_results.length > 0 THEN
  TALK "Found " + high_quality_results.length + " high-quality matches"
ELSE
  TALK "Results may need verification from additional sources"
END IF
```

## Differences from Automatic KB Search

| Feature | Automatic (USE KB) | Explicit (THINK KB) |
|---------|-------------------|-------------------|
| **Trigger** | User questions automatically search | Explicit keyword execution |
| **Control** | Automatic, behind-the-scenes | Full programmatic control |
| **Results** | Injected into LLM context | Structured data for processing |
| **Analysis** | LLM interprets automatically | Bot can analyze before responding |
| **Confidence** | Not exposed | Explicit confidence scoring |
| **Filtering** | Not available | Full result filtering and processing |

## Performance Considerations

- **Search Time**: 100-500ms depending on KB size and query complexity
- **Memory Usage**: Results cached for session duration
- **Token Limits**: Automatically respects token limits (default: 2000 tokens)
- **Concurrent Searches**: Searches all active KBs in parallel

## Error Handling

```basic
TRY
  results = THINK KB user_query
  IF results.total_results = 0 THEN
    TALK "No information found for: " + user_query
  END IF
CATCH error
  TALK "Search failed: " + error.message
  TALK "Please try a different query or check if knowledge bases are active"
END TRY
```

## Best Practices

1. **Activate Relevant KBs First**: Use `USE KB` to activate appropriate knowledge bases
2. **Check Confidence Scores**: Use confidence thresholds for decision making
3. **Handle Empty Results**: Always check `total_results` before accessing results array
4. **Filter by Relevance**: Consider filtering results below 0.5 relevance
5. **Limit Result Processing**: Process only top N results to avoid performance issues
6. **Cache Results**: Store results in variables for multiple uses

## Integration with Other Keywords

### With LLM Keyword

```basic
results = THINK KB "technical specifications"
IF results.confidence > 0.7 THEN
  context = "Based on: " + results.summary
  response = LLM "Explain this in simple terms" WITH CONTEXT context
  TALK response
END IF
```

### With Decision Making

```basic
policy_results = THINK KB "expense policy limits"
IF policy_results.confidence > 0.8 THEN
  ' Use structured data for automated decisions
  FOR i = 0 TO policy_results.results.length - 1
    result = policy_results.results[i]
    IF result.content CONTAINS "maximum $500" THEN
      SET expense_limit = 500
      BREAK
    END IF
  NEXT i
END IF
```

## Troubleshooting

### No Results Returned

```basic
results = THINK KB query
IF results.total_results = 0 THEN
  PRINT "No active KBs: " + results.kb_count
  PRINT "Try: USE KB 'collection_name' first"
END IF
```

### Low Confidence Scores

- Refine query terms to be more specific
- Check if relevant documents are in active KBs
- Consider expanding search to additional knowledge bases
- Verify document quality and indexing

### Performance Issues

- Limit concurrent THINK KB calls
- Use more specific queries to reduce result sets
- Consider caching results for repeated queries
- Monitor token usage in results

## See Also

- [USE KB](./keyword-use-kb.md) - Activate knowledge bases for automatic search
- [CLEAR KB](./keyword-clear-kb.md) - Deactivate knowledge bases
- [KB Statistics](./keyword-kb-statistics.md) - Knowledge base metrics
- [Knowledge Base System](../03-knowledge-ai/README.md) - Technical architecture
- [Semantic Search](../03-knowledge-ai/semantic-search.md) - Search algorithms