# Knowledge Base Schema for RAG Integration with SurrealDB
# Defines document structures for best practices and extension metadata
# stored in the vector database with embeddings for semantic search

# Document types
let DocType = [
  "best_practice",
  "extension_metadata",
  "deployment_guide",
  "troubleshooting",
] | Array;

# Base document metadata (common to all knowledge documents)
let DocumentMetadata = {
  source_path | String,
  doc_type | DocType,
  category | String,
  tags | Array,
  version | String,
  created_at | String,
  updated_at | String,
};

# Best Practice document structure
let BestPracticeDoc = {
  id | String,
  title | String,
  description | String,
  category | String,      # deployment, security, reliability, operations, architecture, quality
  relevance | Number,     # 0-100 relevance score
  tags | Array,           # categorization tags
  source | String,        # source reference
  implementation_notes | Array,  # practical implementation details
  related_practices | Array,      # IDs of related best practices

  # RAG fields
  content | String,       # full text for embedding
  embedding | Array,      # vector embedding (1536-dim)
  chunk_index | Number,   # if document is chunked
  source_path | String,   # file location of source
  indexed_at | String,    # timestamp when indexed
} & DocumentMetadata;

# Extension Metadata document structure
let ExtensionMetadataDoc = {
  id | String,
  name | String,
  version | String,
  category | String,      # provider, taskserv
  description | String,
  dependencies | Array,   # names of extensions this depends on
  tags | Array,
  best_practices | Array, # IDs of best practices that apply

  # Additional metadata
  author | String,
  license | String,
  documentation_url | String,
  repository_url | String,

  # Dependency graph information
  dependency_count | Number,     # number of direct dependencies
  dependents | Array,            # extensions that depend on this
  initialization_order | Number, # position in topological sort

  # RAG fields
  content | String,       # full text for embedding
  embedding | Array,      # vector embedding (1536-dim)
  source_path | String,   # file location of metadata.ncl
  indexed_at | String,    # timestamp when indexed
} & DocumentMetadata;

# Document relationship (for graph structure)
let DocumentRelationship = {
  source_id | String,
  target_id | String,
  relationship_type | ["relates_to", "depends_on", "implements", "extends"],
  strength | Number,      # 0-1 relevance strength
  created_at | String,
};

# Knowledge base statistics (metadata about the index)
let KnowledgeBaseStats = {
  namespace | String,
  database | String,
  total_documents | Number,
  by_doc_type | {
    best_practice | Number,
    extension_metadata | Number,
    _,
  },
  embedding_dimension | Number,
  total_relationships | Number,
  last_indexed_at | String,
  vector_index_status | ["healthy", "degraded", "error"],
};

{
  DocumentMetadata,
  BestPracticeDoc,
  ExtensionMetadataDoc,
  DocumentRelationship,
  KnowledgeBaseStats,
}