bluera-knowledge 0.9.21

package/tests/fixtures/documentation/api-reference.md

@@ -0,0 +1,412 @@
+# API Reference
+
+## Overview
+
+This document provides a comprehensive reference for the REST API endpoints, including request/response formats, authentication requirements, and error handling.
+
+## Base URL
+
+```
+Production: https://api.example.com/v1
+Staging: https://staging-api.example.com/v1
+Local: http://localhost:3000/v1
+```
+
+## Authentication
+
+### Bearer Token Authentication
+
+Most endpoints require authentication using JWT bearer tokens.
+
+```http
+Authorization: Bearer <access_token>
+```
+
+### Obtaining Tokens
+
+#### POST /auth/login
+
+Authenticate with email and password to receive tokens.
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "securepassword123"
+}
+```
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "data": {
+    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
+    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
+    "expiresIn": 900,
+    "tokenType": "Bearer"
+  }
+}
+```
+
+#### POST /auth/refresh
+
+Refresh an expired access token.
+
+**Request:**
+```json
+{
+  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
+}
+```
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "data": {
+    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
+    "expiresIn": 900
+  }
+}
+```
+
+## Knowledge Store Endpoints
+
+### Documents
+
+#### GET /documents
+
+List all indexed documents with pagination.
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| page | integer | 1 | Page number |
+| limit | integer | 20 | Items per page (max 100) |
+| sortBy | string | createdAt | Sort field |
+| sortOrder | string | desc | Sort direction (asc/desc) |
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "doc-123",
+      "filename": "readme.md",
+      "path": "/projects/myapp/readme.md",
+      "chunks": 15,
+      "createdAt": "2024-01-15T10:30:00Z",
+      "updatedAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 150,
+    "totalPages": 8,
+    "hasNext": true,
+    "hasPrev": false
+  }
+}
+```
+
+#### POST /documents
+
+Index a new document.
+
+**Request:**
+```json
+{
+  "content": "# My Document\n\nDocument content here...",
+  "metadata": {
+    "filename": "readme.md",
+    "path": "/projects/myapp/readme.md",
+    "tags": ["documentation", "readme"]
+  }
+}
+```
+
+**Response (201 Created):**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "doc-123",
+    "chunks": 15,
+    "message": "Document indexed successfully"
+  }
+}
+```
+
+#### GET /documents/:id
+
+Get a specific document by ID.
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "doc-123",
+    "filename": "readme.md",
+    "content": "# My Document...",
+    "chunks": [
+      {
+        "id": "chunk-1",
+        "content": "# My Document",
+        "index": 0
+      }
+    ],
+    "metadata": {
+      "path": "/projects/myapp/readme.md",
+      "tags": ["documentation"]
+    }
+  }
+}
+```
+
+#### DELETE /documents/:id
+
+Delete a document and its chunks.
+
+**Response (204 No Content)**
+
+### Search
+
+#### POST /search
+
+Search across indexed documents.
+
+**Request:**
+```json
+{
+  "query": "authentication middleware implementation",
+  "options": {
+    "mode": "hybrid",
+    "limit": 10,
+    "threshold": 0.5,
+    "filters": {
+      "tags": ["api", "auth"]
+    }
+  }
+}
+```
+
+**Search Modes:**
+| Mode | Description |
+|------|-------------|
+| vector | Semantic similarity search using embeddings |
+| fts | Full-text keyword search |
+| hybrid | Combined vector and FTS with RRF fusion |
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "data": {
+    "results": [
+      {
+        "documentId": "doc-123",
+        "chunkId": "chunk-5",
+        "content": "The authentication middleware validates JWT tokens...",
+        "score": 0.89,
+        "metadata": {
+          "filename": "auth.ts",
+          "path": "/src/middleware/auth.ts"
+        }
+      }
+    ],
+    "query": "authentication middleware implementation",
+    "mode": "hybrid",
+    "totalResults": 25,
+    "searchTime": 45
+  }
+}
+```
+
+## User Management
+
+### GET /users
+
+List all users (admin only).
+
+**Required Role:** admin
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "user-123",
+      "email": "user@example.com",
+      "name": "John Doe",
+      "role": "user",
+      "createdAt": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "pagination": {...}
+}
+```
+
+### POST /users
+
+Create a new user (admin only).
+
+**Required Role:** admin
+
+**Request:**
+```json
+{
+  "email": "newuser@example.com",
+  "name": "Jane Smith",
+  "password": "securepassword123",
+  "role": "user"
+}
+```
+
+### GET /users/:id
+
+Get user by ID.
+
+### PUT /users/:id
+
+Update user information.
+
+### DELETE /users/:id
+
+Delete a user (admin only).
+
+## Error Responses
+
+All errors follow a consistent format:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed",
+    "statusCode": 422,
+    "timestamp": "2024-01-15T10:30:00Z",
+    "path": "/v1/documents",
+    "requestId": "req-abc123",
+    "details": {
+      "validationErrors": [
+        {
+          "field": "content",
+          "message": "Content is required"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Error Codes
+
+| Code | Status | Description |
+|------|--------|-------------|
+| BAD_REQUEST | 400 | Invalid request parameters |
+| UNAUTHORIZED | 401 | Authentication required |
+| FORBIDDEN | 403 | Insufficient permissions |
+| NOT_FOUND | 404 | Resource not found |
+| CONFLICT | 409 | Resource conflict |
+| VALIDATION_ERROR | 422 | Validation failed |
+| RATE_LIMIT_EXCEEDED | 429 | Too many requests |
+| INTERNAL_ERROR | 500 | Server error |
+
+## Rate Limiting
+
+API requests are rate limited per user:
+
+| Tier | Requests/minute | Burst |
+|------|-----------------|-------|
+| Free | 60 | 10 |
+| Pro | 300 | 50 |
+| Enterprise | 1000 | 100 |
+
+Rate limit headers are included in responses:
+
+```http
+X-RateLimit-Limit: 60
+X-RateLimit-Remaining: 45
+X-RateLimit-Reset: 1705315800
+```
+
+## Webhooks
+
+Configure webhooks to receive real-time notifications.
+
+### Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| document.indexed | Document successfully indexed |
+| document.deleted | Document deleted |
+| search.completed | Search query completed |
+
+### Webhook Payload
+
+```json
+{
+  "event": "document.indexed",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "data": {
+    "documentId": "doc-123",
+    "chunks": 15
+  }
+}
+```
+
+## SDK Examples
+
+### JavaScript/TypeScript
+
+```typescript
+import { KnowledgeClient } from '@example/knowledge-sdk';
+
+const client = new KnowledgeClient({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.example.com/v1'
+});
+
+// Index a document
+const doc = await client.documents.create({
+  content: 'Document content...',
+  metadata: { filename: 'readme.md' }
+});
+
+// Search
+const results = await client.search({
+  query: 'authentication',
+  mode: 'hybrid',
+  limit: 10
+});
+```
+
+### Python
+
+```python
+from knowledge_sdk import KnowledgeClient
+
+client = KnowledgeClient(
+    api_key='your-api-key',
+    base_url='https://api.example.com/v1'
+)
+
+# Index a document
+doc = client.documents.create(
+    content='Document content...',
+    metadata={'filename': 'readme.md'}
+)
+
+# Search
+results = client.search(
+    query='authentication',
+    mode='hybrid',
+    limit=10
+)
+```

package/tests/fixtures/documentation/architecture.md

@@ -0,0 +1,214 @@
+# System Architecture
+
+## Overview
+
+This document describes the high-level architecture of the application, including its core components, data flow, and integration patterns.
+
+## Architecture Principles
+
+### 1. Separation of Concerns
+
+The system follows a clean architecture approach with distinct layers:
+
+- **Presentation Layer**: Handles user interface and API endpoints
+- **Application Layer**: Contains business logic and use cases
+- **Domain Layer**: Core business entities and rules
+- **Infrastructure Layer**: External services, databases, and frameworks
+
+### 2. Dependency Inversion
+
+All dependencies point inward toward the domain layer. External concerns (databases, APIs, frameworks) depend on abstractions defined in the domain.
+
+## Core Components
+
+### API Gateway
+
+The API Gateway serves as the single entry point for all client requests.
+
+**Responsibilities:**
+- Request routing and load balancing
+- Authentication and authorization
+- Rate limiting and throttling
+- Request/response transformation
+- API versioning
+
+**Technology:** Express.js with custom middleware stack
+
+### Authentication Service
+
+Handles all authentication and authorization concerns.
+
+**Features:**
+- JWT-based authentication with refresh tokens
+- OAuth 2.0 integration (Google, GitHub)
+- Role-based access control (RBAC)
+- Session management
+
+**Security Measures:**
+- Password hashing with bcrypt (cost factor 12)
+- Token rotation on refresh
+- Secure HTTP-only cookies
+- CSRF protection
+
+### Knowledge Store
+
+The core component for managing semantic search capabilities.
+
+**Architecture:**
+```
+┌─────────────────┐     ┌──────────────────┐
+│   CLI Client    │────▶│  Knowledge API   │
+└─────────────────┘     └──────────────────┘
+                               │
+                    ┌──────────┴──────────┐
+                    ▼                      ▼
+            ┌──────────────┐      ┌──────────────┐
+            │ Vector Store │      │   FTS Index  │
+            └──────────────┘      └──────────────┘
+```
+
+**Components:**
+- **Document Processor**: Chunks and embeds documents
+- **Vector Store**: SQLite with vec0 extension for similarity search
+- **FTS Index**: Full-text search using SQLite FTS5
+- **Query Engine**: Hybrid search combining vector and FTS results
+
+### Event Bus
+
+Asynchronous communication between services using an event-driven architecture.
+
+**Event Types:**
+- Domain Events: Business state changes
+- Integration Events: Cross-service communication
+- System Events: Health, metrics, logging
+
+## Data Flow
+
+### Document Indexing Flow
+
+1. User submits document via CLI or API
+2. Document processor validates and chunks content
+3. Embedding service generates vector representations
+4. Vectors stored in vector database
+5. Text indexed in FTS for keyword search
+6. Metadata stored in SQLite
+
+### Search Query Flow
+
+1. User submits search query
+2. Query preprocessor normalizes input
+3. Parallel execution:
+   - Vector similarity search
+   - Full-text keyword search
+4. Result fusion with RRF algorithm
+5. Re-ranking based on relevance scores
+6. Results returned with snippets
+
+## Integration Patterns
+
+### Database Access
+
+Using the Repository pattern for data access abstraction:
+
+```typescript
+interface IRepository<T extends Entity> {
+  findById(id: string): Promise<T | null>;
+  findMany(options?: QueryOptions<T>): Promise<T[]>;
+  create(data: Omit<T, 'id'>): Promise<T>;
+  update(id: string, data: Partial<T>): Promise<T>;
+  delete(id: string): Promise<void>;
+}
+```
+
+### External API Integration
+
+Circuit breaker pattern for resilience:
+
+- **Closed State**: Normal operation
+- **Open State**: Fail fast when service is down
+- **Half-Open State**: Test if service recovered
+
+### Caching Strategy
+
+Multi-level caching approach:
+
+1. **L1 Cache**: In-memory LRU cache (hot data)
+2. **L2 Cache**: Redis distributed cache
+3. **L3 Cache**: Database query cache
+
+## Scalability Considerations
+
+### Horizontal Scaling
+
+- Stateless services enable horizontal scaling
+- Load balancer distributes traffic
+- Shared-nothing architecture
+
+### Database Scaling
+
+- Read replicas for query workloads
+- Connection pooling
+- Query optimization and indexing
+
+### Performance Targets
+
+| Metric | Target | P99 |
+|--------|--------|-----|
+| API Response Time | < 200ms | < 500ms |
+| Search Latency | < 300ms | < 800ms |
+| Indexing Throughput | > 100 docs/sec | - |
+
+## Monitoring and Observability
+
+### Metrics
+
+- Request rate and latency
+- Error rates and types
+- Resource utilization
+- Business metrics
+
+### Logging
+
+Structured JSON logging with correlation IDs:
+
+```json
+{
+  "timestamp": "2024-01-15T10:30:00Z",
+  "level": "info",
+  "correlationId": "abc-123",
+  "service": "knowledge-store",
+  "message": "Document indexed successfully",
+  "metadata": {
+    "documentId": "doc-456",
+    "chunks": 15,
+    "duration": 234
+  }
+}
+```
+
+### Distributed Tracing
+
+OpenTelemetry integration for end-to-end request tracing across services.
+
+## Security Architecture
+
+### Defense in Depth
+
+Multiple layers of security controls:
+
+1. **Network**: Firewall rules, VPC isolation
+2. **Transport**: TLS 1.3, certificate pinning
+3. **Application**: Input validation, output encoding
+4. **Data**: Encryption at rest, field-level encryption
+
+### Authentication Flow
+
+```
+Client → API Gateway → Auth Service → Token Validation → Protected Resource
+```
+
+### Secrets Management
+
+- Environment variables for configuration
+- Secrets manager for sensitive data
+- Key rotation policies