luca 3.0.0 → 3.1.0

package/docs/apis/features/agi/semantic-search.md

@@ -1,387 +0,0 @@
-# SemanticSearch (features.semanticSearch)
-
-A vector search engine backed by SQLite that indexes documents with embeddings for semantic, keyword, and hybrid search. Supports local GGUF embedding models and configurable chunking strategies for splitting documents into searchable segments.
-
-## Usage
-
-```ts
-container.feature('semanticSearch', {
-  // Path to the SQLite database file
-  dbPath,
-  // GGUF model name
-  embeddingModel,
-  // Where to generate embeddings
-  embeddingProvider,
-  // How to split documents
-  chunkStrategy,
-  // Token limit per chunk for fixed strategy
-  chunkSize,
-  // Overlap ratio for fixed strategy
-  chunkOverlap,
-})
-```
-
-## Options (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `dbPath` | `string` | Path to the SQLite database file |
-| `embeddingModel` | `string` | GGUF model name |
-| `embeddingProvider` | `string` | Where to generate embeddings |
-| `chunkStrategy` | `string` | How to split documents |
-| `chunkSize` | `number` | Token limit per chunk for fixed strategy |
-| `chunkOverlap` | `number` | Overlap ratio for fixed strategy |
-
-## Methods
-
-### initDb
-
-**Returns:** `Promise<void>`
-
-
-
-### insertDocument
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `doc` | `DocumentInput` | ✓ | Parameter doc |
-
-`DocumentInput` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `pathId` | `string` |  |
-| `model` | `string` |  |
-| `title` | `string` |  |
-| `slug` | `string` |  |
-| `meta` | `Record<string, any>` |  |
-| `content` | `string` |  |
-| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
-
-**Returns:** `void`
-
-
-
-### insertChunk
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `chunk` | `Chunk` | ✓ | Parameter chunk |
-
-`Chunk` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `pathId` | `string` |  |
-| `section` | `string` |  |
-| `headingPath` | `string` |  |
-| `seq` | `number` |  |
-| `content` | `string` |  |
-| `contentHash` | `string` |  |
-| `embedding` | `Float32Array` | ✓ | Parameter embedding |
-
-**Returns:** `void`
-
-
-
-### removeDocument
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `pathId` | `string` | ✓ | Parameter pathId |
-
-**Returns:** `void`
-
-
-
-### getStats
-
-**Returns:** `IndexStatus`
-
-
-
-### embed
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `texts` | `string[]` | ✓ | Parameter texts |
-
-**Returns:** `Promise<number[][]>`
-
-
-
-### ensureModel
-
-**Returns:** `Promise<void>`
-
-
-
-### disposeModel
-
-**Returns:** `Promise<void>`
-
-
-
-### getDimensions
-
-**Returns:** `number`
-
-
-
-### chunkDocument
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `doc` | `DocumentInput` | ✓ | Parameter doc |
-
-`DocumentInput` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `pathId` | `string` |  |
-| `model` | `string` |  |
-| `title` | `string` |  |
-| `slug` | `string` |  |
-| `meta` | `Record<string, any>` |  |
-| `content` | `string` |  |
-| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
-| `strategy` | `'section' | 'fixed' | 'document'` |  | Parameter strategy |
-
-**Returns:** `Chunk[]`
-
-
-
-### search
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `query` | `string` | ✓ | Parameter query |
-| `options` | `SearchOptions` |  | Parameter options |
-
-`SearchOptions` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `limit` | `number` |  |
-| `model` | `string` |  |
-| `where` | `Record<string, any>` |  |
-
-**Returns:** `Promise<SearchResult[]>`
-
-
-
-### vectorSearch
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `query` | `string` | ✓ | Parameter query |
-| `options` | `SearchOptions` |  | Parameter options |
-
-`SearchOptions` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `limit` | `number` |  |
-| `model` | `string` |  |
-| `where` | `Record<string, any>` |  |
-
-**Returns:** `Promise<SearchResult[]>`
-
-
-
-### hybridSearch
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `query` | `string` | ✓ | Parameter query |
-| `options` | `HybridSearchOptions` |  | Parameter options |
-
-`HybridSearchOptions` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `ftsWeight` | `number` |  |
-| `vecWeight` | `number` |  |
-
-**Returns:** `Promise<SearchResult[]>`
-
-
-
-### deepSearch
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `_query` | `string` | ✓ | Parameter _query |
-| `_options` | `SearchOptions` |  | Parameter _options |
-
-`SearchOptions` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `limit` | `number` |  |
-| `model` | `string` |  |
-| `where` | `Record<string, any>` |  |
-
-**Returns:** `Promise<SearchResult[]>`
-
-
-
-### indexDocuments
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `docs` | `DocumentInput[]` | ✓ | Parameter docs |
-
-`DocumentInput[]` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `pathId` | `string` |  |
-| `model` | `string` |  |
-| `title` | `string` |  |
-| `slug` | `string` |  |
-| `meta` | `Record<string, any>` |  |
-| `content` | `string` |  |
-| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
-
-**Returns:** `Promise<void>`
-
-
-
-### reindex
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `pathIds` | `string[]` |  | Parameter pathIds |
-
-**Returns:** `Promise<void>`
-
-
-
-### removeStale
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `currentPathIds` | `string[]` | ✓ | Parameter currentPathIds |
-
-**Returns:** `void`
-
-
-
-### needsReindex
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `doc` | `DocumentInput` | ✓ | Parameter doc |
-
-`DocumentInput` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `pathId` | `string` |  |
-| `model` | `string` |  |
-| `title` | `string` |  |
-| `slug` | `string` |  |
-| `meta` | `Record<string, any>` |  |
-| `content` | `string` |  |
-| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
-
-**Returns:** `boolean`
-
-
-
-### status
-
-**Returns:** `IndexStatus`
-
-
-
-### close
-
-**Returns:** `Promise<void>`
-
-
-
-## Getters
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `db` | `Database` |  |
-| `dimensions` | `number` |  |
-
-## Events (Zod v4 schema)
-
-### dbReady
-
-Event emitted by SemanticSearch
-
-
-
-### modelLoaded
-
-Event emitted by SemanticSearch
-
-
-
-### modelDisposed
-
-Event emitted by SemanticSearch
-
-
-
-### indexed
-
-Event emitted by SemanticSearch
-
-
-
-## State (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `enabled` | `boolean` | Whether this feature is currently enabled |
-| `indexed` | `number` | Count of indexed documents |
-| `embedded` | `number` | Count of documents with embeddings |
-| `lastIndexedAt` | `any` | ISO timestamp of last indexing |
-| `dbReady` | `boolean` | Whether SQLite is initialized |
-
-## Examples
-
-**features.semanticSearch**
-
-```ts
-const search = container.feature('semanticSearch', {
- dbPath: '.contentbase/search.sqlite',
- embeddingProvider: 'local',
-})
-await search.initDb()
-await search.indexDocuments(docs)
-const results = await search.hybridSearch('how does authentication work')
-```
-

package/docs/apis/features/agi/skills-library.md

@@ -1,239 +0,0 @@
-# SkillsLibrary (features.skillsLibrary)
-
-Manages a registry of skill locations — folders containing SKILL.md files. Persists known locations to ~/.luca/skills.json and scans them on start. Each skill folder can be opened as a DocsReader for AI-assisted Q&A. Exposes tools for assistant integration via assistant.use(skillsLibrary).
-
-## Usage
-
-```ts
-container.feature('skillsLibrary', {
-  // Override path for skills.json (defaults to ~/.luca/skills.json)
-  configPath,
-})
-```
-
-## Options (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `configPath` | `string` | Override path for skills.json (defaults to ~/.luca/skills.json) |
-
-## Methods
-
-### setupToolsConsumer
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `assistant` | `Feature` | ✓ | Parameter assistant |
-
-**Returns:** `void`
-
-
-
-### start
-
-Start the skills library: read config, scan all locations.
-
-**Returns:** `Promise<SkillsLibrary>`
-
-
-
-### addLocation
-
-Add a new skill location folder and scan it for skills.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `locationPath` | `string` | ✓ | Path to a directory containing skill subfolders with SKILL.md |
-
-**Returns:** `Promise<void>`
-
-
-
-### removeLocation
-
-Remove a skill location and its skills from the library.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `locationPath` | `string` | ✓ | The location path to remove |
-
-**Returns:** `Promise<void>`
-
-
-
-### scanLocation
-
-Scan a location folder for skill subfolders containing SKILL.md.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `locationPath` | `string` | ✓ | Absolute path to scan |
-
-**Returns:** `Promise<void>`
-
-
-
-### list
-
-Return all discovered skills.
-
-**Returns:** `SkillInfo[]`
-
-
-
-### find
-
-Find a skill by name.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `skillName` | `string` | ✓ | Parameter skillName |
-
-**Returns:** `SkillInfo | undefined`
-
-
-
-### createSkillReader
-
-Create a DocsReader for a skill's folder, enabling AI-assisted Q&A.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `skillName` | `string` | ✓ | Name of the skill to create a reader for |
-
-**Returns:** `DocsReader`
-
-
-
-### ensureFolderCreatedWithSkillsByName
-
-Create a tmp directory containing symlinked/copied skill folders by name, suitable for passing to claude --add-dir.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `skillNames` | `string[]` | ✓ | Array of skill names to include |
-
-**Returns:** `string`
-
-
-
-### searchAvailableSkills
-
-Search available skills, optionally filtered by a query string.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `{ query }` | `{ query?: string }` |  | Parameter { query } |
-
-**Returns:** `Promise<string>`
-
-
-
-### loadSkill
-
-Load a skill's full SKILL.md content and metadata.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `{ skillName }` | `{ skillName: string }` | ✓ | Parameter { skillName } |
-
-**Returns:** `Promise<string>`
-
-
-
-### askSkillBasedQuestion
-
-Ask a question about a specific skill using a DocsReader.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `{ skillName, question }` | `{ skillName: string; question: string }` | ✓ | Parameter { skillName, question } |
-
-**Returns:** `Promise<string>`
-
-
-
-## Getters
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `skills` | `Record<string, SkillInfo>` | Discovered skills keyed by name. |
-| `availableSkills` | `any` |  |
-| `skillsTable` | `Record<string, string>` |  |
-| `configPath` | `string` | Resolved path to the skills.json config file. |
-| `isStarted` | `boolean` | Whether the library has been loaded. |
-
-## Events (Zod v4 schema)
-
-### started
-
-Fired after all skill locations have been scanned
-
-
-
-### locationAdded
-
-Fired when a new skill location is registered
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | The absolute path of the added location |
-
-
-
-### skillDiscovered
-
-Fired when a skill is discovered during scanning
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `any` | The SkillInfo object |
-
-
-
-## State (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `enabled` | `boolean` | Whether this feature is currently enabled |
-| `loaded` | `boolean` | Whether skill locations have been scanned |
-| `locations` | `array` | Tracked skill location folder paths |
-| `skillCount` | `number` | Total number of discovered skills |
-| `skills` | `object` | Discovered skills keyed by name |
-
-## Examples
-
-**features.skillsLibrary**
-
-```ts
-const lib = container.feature('skillsLibrary')
-await lib.start()
-await lib.addLocation('~/.claude/skills')
-lib.list() // => SkillInfo[]
-const reader = lib.createSkillReader('my-skill')
-```
-