@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/libraries/weaviate/docs/QUICK_START.md

@@ -0,0 +1,443 @@
+# Weaviate - Quick Start Guide
+
+Get up and running with the Weaviate Vector Search Framework in minutes!
+
+## 🚀 Basic Usage
+
+```typescript
+import Weaviate, { WeaviateConfigService, WeaviateError, WeaviateErrorCode } from "./lib/weaviate";
+import { schemas } from "./config/schemas";
+
+// 1. Initialize Weaviate client (once at app startup)
+await WeaviateConfigService.initializeClient();
+
+// 2. Create Weaviate instance
+const weaviate = new Weaviate();
+
+// 3. Initialize schemas (once at app startup)
+await weaviate.initializeSchemas(schemas);
+
+// 4. Search with the new discriminated union pattern
+const people = await weaviate.search("Person", {
+  method: "hybrid",
+  options: {
+    hybrid: { query: "software engineer", alpha: 0.5 },
+    limit: 10
+  }
+});
+
+// 5. Use convenience methods for simpler syntax
+const results = await weaviate.hybridSearch("Person", "AI researcher");
+```
+
+## 🏗️ Constructor & Configuration
+
+### Default Initialization
+
+```typescript
+// Auto-initializes with default plugins
+const weaviate = new Weaviate();
+```
+
+### Custom Configuration
+
+```typescript
+import { WeaviateOptions } from "./lib/weaviate";
+
+// With custom registry
+const weaviate = new Weaviate({
+  registry: myCustomRegistry
+});
+
+// With custom plugins
+const weaviate = new Weaviate({
+  plugins: [new MyCustomPlugin()]
+});
+```
+
+## 🔍 Search Methods
+
+### Type-Safe Search (Recommended)
+
+The new discriminated union pattern provides compile-time type safety:
+
+```typescript
+// Vector search - TypeScript knows options must include nearText
+const vectorResults = await weaviate.search("Person", {
+  method: "vector",
+  options: {
+    nearText: { concepts: ["engineer"], certainty: 0.7 },
+    limit: 10
+  }
+});
+
+// BM25 search - TypeScript knows options must include bm25
+const keywordResults = await weaviate.search("Person", {
+  method: "bm25",
+  options: {
+    bm25: { query: "John Smith" },
+    limit: 10
+  }
+});
+
+// Hybrid search - TypeScript knows options must include hybrid
+const hybridResults = await weaviate.search("Person", {
+  method: "hybrid",
+  options: {
+    hybrid: { query: "AI expert", alpha: 0.5 },
+    limit: 10
+  }
+});
+```
+
+### Convenience Methods (Simpler)
+
+For common use cases, use convenience methods:
+
+```typescript
+// Vector search with concepts
+await weaviate.vectorSearch("Person", ["machine learning expert"]);
+
+// BM25 keyword search
+await weaviate.textSearch("Person", "John Smith");
+
+// Hybrid search
+await weaviate.hybridSearch("Person", "AI researcher", { alpha: 0.5 });
+
+// Smart search (auto-selects method)
+await weaviate.smartSearch("Person", "software engineer");
+```
+
+## 🚨 Error Handling
+
+All operations now throw structured `WeaviateError` instances:
+
+```typescript
+import { WeaviateError, WeaviateErrorCode } from "./lib/weaviate";
+
+try {
+  await weaviate.createObject({
+    class: "Person",
+    properties: { name: "John Doe", email: "john@example.com" }
+  });
+} catch (error) {
+  if (error instanceof WeaviateError) {
+    console.log(`Error Code: ${error.code}`);
+    console.log(`Message: ${error.message}`);
+    console.log(`Details:`, error.details);
+    
+    // Handle specific error types
+    if (error.is(WeaviateErrorCode.OBJECT_CREATION_ERROR)) {
+      // Retry logic
+    }
+  }
+}
+```
+
+See [Error Handling Guide](./ERROR_HANDLING.md) for complete documentation.
+
+## 🔧 Query Builder
+
+Build complex queries with a fluent API:
+
+```typescript
+import { QueryPatterns } from "./lib/weaviate";
+
+// Fluent query building
+const query = weaviate
+  .queryBuilder("Person")
+  .limit(10)
+  .whereField("city", "Equal", "San Francisco")
+  .sort("createdAt", "desc");
+
+const results = await weaviate.search(
+  "Person",
+  {
+    method: "hybrid",
+    options: query.buildHybridSearch("engineer", { alpha: 0.5 })
+  }
+);
+
+// Pre-built patterns
+const dateQuery = QueryPatterns.dateRange("createdAt", startDate, endDate);
+const textQuery = QueryPatterns.textContains("headline", "senior");
+const inQuery = QueryPatterns.inValues("city", ["SF", "NY", "LA"]);
+```
+
+## 🌐 Universal Search
+
+Search across multiple schemas simultaneously:
+
+```typescript
+const allResults = await weaviate.searchAll(
+  ["Person", "Organization", "Conversation"],
+  {
+    method: "hybrid",
+    options: {
+      hybrid: { query: "AI", alpha: 0.6 },
+      limit: 5
+    }
+  }
+);
+
+// Returns: { Person: SearchResult, Organization: SearchResult, Conversation: SearchResult }
+```
+
+## 🏢 Multi-Tenancy
+
+### Setup Multi-Tenant Schema
+
+```typescript
+const schema = {
+  name: "UserDocuments",
+  description: "User-specific documents",
+  multiTenancy: {
+    enabled: true,
+    autoTenantCreation: true,
+    autoTenantActivation: true,
+  },
+  properties: [
+    { name: "title", dataType: ["string"] },
+    { name: "content", dataType: ["text"] }
+  ]
+};
+
+await weaviate.initializeSchemas([schema]);
+```
+
+### Create and Manage Tenants
+
+```typescript
+// Create tenant (validates name automatically)
+await weaviate.createTenant("UserDocuments", { 
+  name: "acme-corp",  // Must be lowercase alphanumeric with hyphens
+  activityStatus: "HOT"
+});
+
+// List tenants
+const tenants = await weaviate.listTenants("UserDocuments");
+
+// Get tenant stats
+const stats = await weaviate.getTenantStats("UserDocuments");
+```
+
+### Tenant-Aware Search
+
+```typescript
+// Search within specific tenant
+const results = await weaviate.searchWithTenant(
+  "UserDocuments",
+  {
+    method: "hybrid",
+    options: {
+      hybrid: { query: "machine learning", alpha: 0.5 },
+      limit: 10
+    }
+  },
+  "acme-corp"
+);
+
+// Smart search with tenant
+const smartResults = await weaviate.smartSearchWithTenant(
+  "UserDocuments",
+  "AI expert",
+  "acme-corp"
+);
+```
+
+See [Multi-Tenancy Guide](./MULTI_TENANCY.md) for comprehensive documentation.
+
+## 📊 Search Method Comparison
+
+| Method | Speed | Accuracy | Best For | Alpha Value |
+|--------|-------|----------|----------|-------------|
+| **Vector** | Medium | High (semantic) | Natural language queries | N/A |
+| **BM25** | Fast | High (keyword) | Exact term matching | N/A |
+| **Hybrid** | Medium | **Highest** | General purpose ✨ | 0.0 - 1.0 |
+
+### Alpha Parameter (Hybrid Search)
+
+- `0.0` = Pure BM25 (keyword-only)
+- `0.5` = Balanced (default, recommended)
+- `1.0` = Pure vector (semantic-only)
+
+## 🔌 Built-In Plugins
+
+The plugin system allows you to enhance your data during operations. Custom plugins can be registered during initialization:
+
+```typescript
+// Register custom plugins
+const weaviate = new Weaviate({
+  plugins: [new MyCustomPlugin()]
+});
+```
+
+See [Plugin Development Guide](./PLUGIN_DEVELOPMENT.md) for creating custom plugins.
+
+## 💾 CRUD Operations
+
+```typescript
+// Create object
+const id = await weaviate.createObject({
+  class: "Person",
+  properties: {
+    fullName: "John Doe",
+    email: "john@example.com"
+  }
+});
+
+// Create batch
+const ids = await weaviate.createObjectsBatch([
+  { class: "Person", properties: { fullName: "Alice" } },
+  { class: "Person", properties: { fullName: "Bob" } }
+]);
+
+// Get object
+const person = await weaviate.getObject("Person", id);
+
+// Update object
+await weaviate.updateObject("Person", id, {
+  email: "newemail@example.com"
+});
+
+// Delete object
+await weaviate.deleteObject("Person", id);
+```
+
+## 🧪 Testing Your Integration
+
+```typescript
+import { describe, it, expect } from "vitest";
+
+describe("Weaviate Integration", () => {
+  it("should search for people", async () => {
+    const results = await weaviate.search("Person", {
+      method: "hybrid",
+      options: {
+        hybrid: { query: "engineer" },
+        limit: 10
+      }
+    });
+    
+    expect(results.objects).toBeDefined();
+    expect(results.total).toBeGreaterThan(0);
+  });
+  
+  it("should handle errors", async () => {
+    await expect(
+      weaviate.search("NonExistent", {
+        method: "vector",
+        options: { nearText: { concepts: ["test"] } }
+      })
+    ).rejects.toThrow(WeaviateError);
+  });
+});
+```
+
+## 📈 Performance Tips
+
+1. **Use Hybrid Search** for best overall results
+2. **Batch Operations** when creating multiple objects
+3. **Limit Results** to what you actually need
+4. **Index Strategically** - not all fields need to be searchable
+5. **Use Multi-Tenancy** for natural data isolation
+6. **Implement Error Handling** for resilient applications
+
+## ✅ Common Patterns
+
+### Pattern 1: Initialize Once
+
+```typescript
+// In your app initialization file
+let weaviate: Weaviate;
+
+export async function initializeWeaviate() {
+  await WeaviateConfigService.initializeClient();
+  weaviate = new Weaviate();
+  await weaviate.initializeSchemas(schemas);
+  return weaviate;
+}
+
+export function getWeaviate() {
+  if (!weaviate) {
+    throw new Error("Weaviate not initialized");
+  }
+  return weaviate;
+}
+```
+
+### Pattern 2: Error Handling Wrapper
+
+```typescript
+async function safeSearch<T>(params: SearchParams): Promise<SearchResult<T> | null> {
+  try {
+    return await weaviate.search(params.schema, params.request);
+  } catch (error) {
+    if (error instanceof WeaviateError) {
+      logger.error(`Search failed: ${error.code}`, error.details);
+    }
+    return null;
+  }
+}
+```
+
+### Pattern 3: Tenant-Scoped Service
+
+```typescript
+class TenantService {
+  constructor(
+    private weaviate: Weaviate,
+    private tenantId: string
+  ) {}
+  
+  async search(schema: string, query: string) {
+    return this.weaviate.searchWithTenant(
+      schema,
+      {
+        method: "hybrid",
+        options: { hybrid: { query }, limit: 10 }
+      },
+      this.tenantId
+    );
+  }
+}
+```
+
+## 📚 Next Steps
+
+1. **Explore Examples**: See [Weaviate.example.ts](../Weaviate.example.ts) for comprehensive examples
+2. **Read API Reference**: Check [API_REFERENCE.md](./API_REFERENCE.md) for all methods
+3. **Schema Guide**: Learn schema patterns in [SCHEMA_GUIDE.md](./SCHEMA_GUIDE.md)
+4. **Error Handling**: Master errors in [ERROR_HANDLING.md](./ERROR_HANDLING.md)
+5. **Performance**: Optimize with [PERFORMANCE.md](./PERFORMANCE.md)
+
+## 🆘 Troubleshooting
+
+### "Schema not found in registry"
+```typescript
+// Make sure schema is initialized before searching
+await weaviate.initializeSchemas([yourSchema]);
+```
+
+### "Invalid tenant name"
+```typescript
+// Tenant names must be lowercase alphanumeric with hyphens
+// ✅ Good: "acme-corp", "tenant-123"
+// ❌ Bad: "Acme Corp", "tenant_123"
+```
+
+### TypeScript errors with search
+```typescript
+// Make sure method and options match
+// ✅ Correct:
+{ method: "hybrid", options: { hybrid: { query: "test" } } }
+
+// ❌ Incorrect:
+{ method: "hybrid", options: { nearText: { concepts: ["test"] } } }
+```
+
+---
+
+**Ready to get started?** Copy the basic usage example and start searching! 🚀
+
+For more advanced usage, check out the [complete documentation](./README.md).

package/lib/libraries/weaviate/docs/README.md

@@ -0,0 +1,269 @@
+# Weaviate Documentation Hub
+
+Welcome to the comprehensive documentation for the Weaviate Vector Search Framework!
+
+## 📚 Documentation Structure
+
+### 🚀 Getting Started
+
+Perfect for newcomers to the framework:
+
+1. **[Quick Start Guide](./QUICK_START.md)** - Get up and running in 5 minutes
+2. **[Configuration Guide](./CONFIGURATION.md)** - Environment setup and initialization
+3. **[Complete Framework Guide](./WEAVIATE_README.md)** - In-depth framework documentation
+
+### 📖 Core Documentation
+
+Essential references for daily use:
+
+- **[API Reference](./API_REFERENCE.md)** - Complete method documentation with examples
+- **[Schema Guide](./SCHEMA_GUIDE.md)** - Creating and managing schemas
+- **[Multi-Tenancy Guide](./MULTI_TENANCY.md)** - Tenant isolation and management
+- **[Plugin Development](./PLUGIN_DEVELOPMENT.md)** - Creating custom plugins
+- **[Performance Guide](./PERFORMANCE.md)** - Optimization tips and best practices
+
+### 🔧 Technical Guides
+
+Advanced topics and patterns:
+
+- **[Error Handling](./ERROR_HANDLING.md)** - Comprehensive error handling with `WeaviateError`
+- **[Working Examples](../Weaviate.example.ts)** - Comprehensive code examples
+
+## 🎯 Quick Navigation
+
+### For First-Time Users
+
+1. Start with this **README** for an overview
+2. Follow **[Quick Start](./QUICK_START.md)** to build your first integration
+3. Review **[Working Examples](../Weaviate.example.ts)** for common patterns
+4. Check **[API Reference](./API_REFERENCE.md)** when you need specific methods
+
+### For Experienced Users
+
+1. **[API Reference](./API_REFERENCE.md)** - Quick method lookup
+2. **[Schema Guide](./SCHEMA_GUIDE.md)** - Advanced schema patterns
+3. **[Plugin Development](./PLUGIN_DEVELOPMENT.md)** - Extending functionality
+4. **[Performance Guide](./PERFORMANCE.md)** - Optimization techniques
+
+### For Technical Leads
+
+1. **[Complete Framework Guide](./WEAVIATE_README.md)** - Full feature documentation
+2. **[Performance Guide](./PERFORMANCE.md)** - Optimization strategies
+3. **[Error Handling](./ERROR_HANDLING.md)** - Error handling patterns
+
+## 🔍 Search This Documentation
+
+### By Topic
+
+**Search Operations**
+- [API Reference - Search Methods](./API_REFERENCE.md#search-methods)
+- [Quick Start - Basic Search](./QUICK_START.md)
+- [Performance - Search Optimization](./PERFORMANCE.md)
+
+**Schema Management**
+- [Schema Guide](./SCHEMA_GUIDE.md)
+- [API Reference - Schema Operations](./API_REFERENCE.md#schema-operations)
+
+**Error Handling**
+- [Error Handling Guide](./ERROR_HANDLING.md)
+- [API Reference - WeaviateError](./API_REFERENCE.md)
+
+**Multi-Tenancy**
+- [Multi-Tenancy Guide](./MULTI_TENANCY.md)
+- [API Reference - Tenant Methods](./API_REFERENCE.md#multi-tenancy)
+
+**Plugins**
+- [Plugin Development](./PLUGIN_DEVELOPMENT.md)
+- [Built-in Plugins](./WEAVIATE_README.md#plugins)
+
+## 📦 Framework Components
+
+### Core Classes
+
+- **`Weaviate`** - Main framework class ([API Reference](./API_REFERENCE.md))
+- **`WeaviateConfigService`** - Connection management ([Configuration](./CONFIGURATION.md))
+- **`SchemaRegistry`** - Schema management ([Schema Guide](./SCHEMA_GUIDE.md))
+- **`QueryBuilder`** - Fluent query API ([API Reference](./API_REFERENCE.md#query-builder))
+
+### Error Handling
+
+- **`WeaviateError`** - Structured error class ([Error Handling](./ERROR_HANDLING.md))
+- **`WeaviateErrorCode`** - Error code enum ([Error Handling](./ERROR_HANDLING.md))
+
+### Types
+
+- **`SearchRequest`** - Discriminated union for search ([API Reference](./API_REFERENCE.md))
+- **`SchemaConfig`** - Schema configuration ([Schema Guide](./SCHEMA_GUIDE.md))
+- **`Plugin`** - Plugin interface ([Plugin Development](./PLUGIN_DEVELOPMENT.md))
+
+### Utilities
+
+- **`TenantContextManager`** - Tenant validation ([Multi-Tenancy](./MULTI_TENANCY.md))
+- **`QueryPatterns`** - Common query patterns ([API Reference](./API_REFERENCE.md#query-patterns))
+
+## 🎨 Common Use Cases
+
+### 1. Basic Search
+
+```typescript
+const results = await weaviate.search("Person", {
+  method: "hybrid",
+  options: {
+    hybrid: { query: "engineer" },
+    limit: 10
+  }
+});
+```
+
+📖 See: [Quick Start](./QUICK_START.md), [API Reference - Search](./API_REFERENCE.md#search-methods)
+
+### 2. Multi-Tenant Search
+
+```typescript
+const results = await weaviate.searchWithTenant("Person", {
+  method: "hybrid",
+  options: { hybrid: { query: "engineer" } }
+}, "tenant-123");
+```
+
+📖 See: [Multi-Tenancy Guide](./MULTI_TENANCY.md)
+
+### 3. Custom Schema
+
+```typescript
+const schema: SchemaConfig = {
+  name: "Product",
+  description: "Product catalog",
+  properties: [
+    { name: "name", dataType: ["string"] },
+    { name: "price", dataType: ["number"] }
+  ]
+};
+```
+
+📖 See: [Schema Guide](./SCHEMA_GUIDE.md)
+
+### 4. Error Handling
+
+```typescript
+try {
+  await weaviate.createObject({ ... });
+} catch (error) {
+  if (error instanceof WeaviateError) {
+    console.log(`Error ${error.code}: ${error.message}`);
+  }
+}
+```
+
+📖 See: [Error Handling](./ERROR_HANDLING.md)
+
+### 5. Custom Plugin
+
+```typescript
+class MyPlugin implements Plugin {
+  name = "my-plugin";
+  version = "1.0.0";
+  hooks = {
+    beforeSearch: (schema, options) => {
+      // Custom logic
+      return options;
+    }
+  };
+}
+```
+
+📖 See: [Plugin Development](./PLUGIN_DEVELOPMENT.md)
+
+## 🚨 Error Codes Reference
+
+Quick reference for common error codes:
+
+| Code | Description | Guide |
+|------|-------------|-------|
+| `SEARCH_ERROR` | Search operation failed | [Error Handling](./ERROR_HANDLING.md) |
+| `OBJECT_CREATION_ERROR` | Failed to create object | [Error Handling](./ERROR_HANDLING.md) |
+| `SCHEMA_VALIDATION_ERROR` | Schema validation failed | [Schema Guide](./SCHEMA_GUIDE.md) |
+| `TENANT_VALIDATION_ERROR` | Invalid tenant name | [Multi-Tenancy](./MULTI_TENANCY.md) |
+
+See complete list in [Error Handling Guide](./ERROR_HANDLING.md#error-codes).
+
+## 📊 Performance Comparison
+
+| Method | Speed | Accuracy | Best For |
+|--------|-------|----------|----------|
+| Vector | Medium | High (semantic) | Natural language |
+| BM25 | Fast | High (keyword) | Exact matches |
+| Hybrid | Medium | **Highest** | General purpose ✨ |
+
+📖 See: [Performance Guide](./PERFORMANCE.md)
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run Weaviate tests only
+npm test -- src/lib/weaviate/
+
+# Run with coverage
+npm test -- --coverage
+```
+
+Current test coverage: **Comprehensive test suite** ✅
+
+## 🔄 Recent Updates
+
+### Version 2.0.0 - Major Improvements
+
+- ✅ Discriminated union search API
+- ✅ Structured error handling with `WeaviateError`
+- ✅ Configurable plugin initialization
+- ✅ Fail-fast schema validation
+- ✅ Tenant name validation
+- ✅ Simplified architecture
+- ✅ Pure instance-based registry pattern
+- ✅ Removed unused default plugins
+
+## 🤝 Contributing
+
+When contributing to the framework:
+
+1. Follow established patterns and conventions
+2. Add comprehensive tests for new functionality
+3. Update relevant documentation
+4. Use structured error handling with proper error codes
+5. Ensure all tests pass before submitting
+
+## 💡 Tips and Best Practices
+
+1. **Use hybrid search** for general-purpose queries (best accuracy)
+2. **Implement error handling** for all async operations
+3. **Validate schemas** at registration time (fail-fast)
+4. **Use plugins** to extend functionality without modifying core
+5. **Enable multi-tenancy** for data isolation requirements
+6. **Batch operations** when creating multiple objects
+7. **Check error codes** for programmatic error handling
+
+## 🔗 External Resources
+
+- [Weaviate Official Documentation](https://weaviate.io/developers/weaviate)
+- [Vector Search Concepts](https://weaviate.io/developers/weaviate/concepts)
+- [BM25 Algorithm](https://en.wikipedia.org/wiki/Okapi_BM25)
+
+## 📞 Support
+
+- **Bug Reports**: Check documentation for known patterns
+- **Feature Requests**: Review existing patterns in documentation
+- **Questions**: Start with [Quick Start Guide](./QUICK_START.md)
+- **Examples**: See [Weaviate.example.ts](../Weaviate.example.ts)
+
+---
+
+**Framework Version**: 2.0.0
+
+**Documentation Last Updated**: 2025
+
+**Status**: ✅ Production Ready
+
+**Next Steps**: Start with [Quick Start Guide](./QUICK_START.md) →