okb 1.1.0a0__tar.gz → 1.1.2__tar.gz

{okb-1.1.0a0 → okb-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: okb
-Version: 1.1.0a0
+Version: 1.1.2
 Summary: Personal knowledge base with semantic search for LLMs
 Requires-Python: >=3.11
 Classifier: Programming Language :: Python :: 3
@@ -85,6 +85,8 @@ okb ingest ~/notes ~/docs
 | `okb db start` | Start pgvector database container |
 | `okb db stop` | Stop database container |
 | `okb db status` | Show database status |
+| `okb db migrate [name]` | Apply pending migrations (optionally for specific db) |
+| `okb db list` | List configured databases |
 | `okb db destroy` | Remove container and volume (destructive) |
 | `okb ingest <paths>` | Ingest documents into knowledge base |
 | `okb ingest <paths> --local` | Ingest using local GPU/CPU embedding (no Modal) |
@@ -93,10 +95,11 @@ okb ingest ~/notes ~/docs
 | `okb watch <paths>` | Watch directories for changes |
 | `okb config init` | Create default config file |
 | `okb config show` | Show current configuration |
+| `okb config path` | Print config file path |
 | `okb modal deploy` | Deploy GPU embedder to Modal |
 | `okb token create` | Create API token for HTTP server |
 | `okb token list` | List tokens for a database |
-| `okb token revoke` | Revoke an API token |
+| `okb token revoke [TOKEN] --id <n>` | Revoke token by full value or ID |
 | `okb sync list` | List available API sources (plugins) |
 | `okb sync list-projects <source>` | List projects from source (for config) |
 | `okb sync run <sources>` | Sync data from external APIs |
@@ -108,6 +111,18 @@ okb ingest ~/notes ~/docs
 | `okb llm status` | Show LLM config and connectivity |
 | `okb llm deploy` | Deploy Modal LLM for open model inference |
 | `okb llm clear-cache` | Clear LLM response cache |
+| `okb enrich run` | Extract TODOs and entities from documents |
+| `okb enrich run --dry-run` | Show what would be enriched |
+| `okb enrich pending` | List entities awaiting review |
+| `okb enrich approve <id>` | Approve a pending entity |
+| `okb enrich reject <id>` | Reject a pending entity |
+| `okb enrich analyze` | Analyze database and update description/topics |
+| `okb enrich consolidate` | Run entity consolidation (duplicates, clusters) |
+| `okb enrich merge-proposals` | List pending merge proposals |
+| `okb enrich approve-merge <id>` | Approve an entity merge |
+| `okb enrich reject-merge <id>` | Reject an entity merge |
+| `okb enrich clusters` | List topic clusters |
+| `okb enrich relationships` | List entity relationships |
 
 
 ## Configuration
@@ -142,7 +157,7 @@ chunking:
 Use `--db <name>` to target a specific database with any command.
 
 Environment variables override config file settings:
-- `KB_DATABASE_URL` - Database connection string
+- `OKB_DATABASE_URL` - Database connection string
 - `OKB_DOCKER_PORT` - Docker port mapping
 - `OKB_CONTAINER_NAME` - Docker container name
 
@@ -163,7 +178,7 @@ Merge: scalars replace, lists extend, dicts deep-merge.
 
 ### LLM Integration (Optional)
 
-Enable LLM-based document classification and filtering:
+Enable LLM-based document classification, filtering, and enrichment:
 
 ```yaml
 llm:
@@ -179,11 +194,25 @@ llm:
 | `claude` | `export ANTHROPIC_API_KEY=...` | ~$0.25/1M tokens |
 | `modal` | `okb llm deploy` | ~$0.02/min GPU |
 
-For Modal (no API key needed):
+**Modal LLM Setup** (no API key needed, runs on Modal's GPUs):
+
 ```yaml
 llm:
   provider: modal
-  model: meta-llama/Llama-3.2-3B-Instruct
+  model: microsoft/Phi-3-mini-4k-instruct  # Recommended: no gating
+```
+
+Non-gated models (work immediately):
+- `microsoft/Phi-3-mini-4k-instruct` - Good quality, 4K context
+- `Qwen/Qwen2-1.5B-Instruct` - Smaller/faster
+
+Gated models (require HuggingFace approval + token):
+- `meta-llama/Llama-3.2-3B-Instruct` - Requires accepting license at HuggingFace
+- Setup: `modal secret create huggingface HF_TOKEN=hf_...`
+
+Deploy after configuring:
+```bash
+okb llm deploy
 ```
 
 **Pre-ingest filtering** - skip low-value content during sync:
@@ -197,6 +226,36 @@ plugins:
         action_on_skip: discard  # or "archive"
 ```
 
+### Document Enrichment
+
+Extract TODOs and entities (people, projects, technologies) from documents using LLM:
+
+```bash
+okb enrich run                      # Enrich un-enriched documents
+okb enrich run --dry-run            # Preview what would be enriched
+okb enrich run --source-type markdown  # Only markdown files
+okb enrich run --query "meeting"    # Filter by semantic search
+```
+
+Entities are created as pending suggestions for review:
+```bash
+okb enrich pending                  # List pending entities
+okb enrich approve <id>             # Approve → creates entity document
+okb enrich reject <id>              # Reject → hidden from future suggestions
+```
+
+Configure enrichment behavior:
+```yaml
+enrichment:
+  enabled: true
+  extract_todos: true
+  extract_entities: true
+  auto_create_todos: true       # TODOs created immediately
+  auto_create_entities: false   # Entities go to pending review
+  min_confidence_todo: 0.7
+  min_confidence_entity: 0.8
+```
+
 CLI commands:
 ```bash
 okb llm status              # Show config and connectivity
@@ -234,14 +293,20 @@ okb token create --db default -d "Claude Code"
 okb serve --http --host 0.0.0.0 --port 8080
 ```
 
-Then configure Claude Code to connect via SSE:
+The server uses Streamable HTTP transport (RFC 9728 compliant):
+- `POST /mcp` - Send JSON-RPC messages, receive SSE response
+- `GET /mcp` - Establish SSE connection for server notifications
+- `DELETE /mcp` - Terminate session
+- `/sse` is an alias for `/mcp` for backward compatibility
+
+Configure your MCP client to connect:
 
 ```json
 {
   "mcpServers": {
     "knowledge-base": {
       "type": "sse",
-      "url": "http://localhost:8080/sse",
+      "url": "http://localhost:8080/mcp",
       "headers": {
         "Authorization": "Bearer okb_default_rw_a1b2c3d4e5f6g7h8"
       }
@@ -269,6 +334,20 @@ Then configure Claude Code to connect via SSE:
 | `add_todo` | Create a TODO item in the knowledge base |
 | `trigger_sync` | Sync API sources (Todoist, GitHub, Dropbox Paper) |
 | `trigger_rescan` | Check indexed files for changes and re-ingest |
+| `list_sync_sources` | List available API sync sources with status |
+| `enrich_document` | Run LLM enrichment to extract TODOs/entities |
+| `list_pending_entities` | List entities awaiting review |
+| `approve_entity` | Approve a pending entity |
+| `reject_entity` | Reject a pending entity |
+| `analyze_knowledge_base` | Analyze content and generate description/topics |
+| `find_entity_duplicates` | Find potential duplicate entities |
+| `merge_entities` | Merge duplicate entities |
+| `list_pending_merges` | List pending merge proposals |
+| `approve_merge` | Approve a merge proposal |
+| `reject_merge` | Reject a merge proposal |
+| `get_topic_clusters` | Get topic clusters from consolidation |
+| `get_entity_relationships` | Get relationships between entities |
+| `run_consolidation` | Run full entity consolidation pipeline |
 
 ## Contextual Chunking
 
@@ -291,6 +370,10 @@ project: student-app
 category: backend
 ---
 
+# Your Document Title
+
+Content here...
+```
 
 ## Plugin System
 

{okb-1.1.0a0 → okb-1.1.2}/README.md

@@ -36,6 +36,8 @@ okb ingest ~/notes ~/docs
 | `okb db start` | Start pgvector database container |
 | `okb db stop` | Stop database container |
 | `okb db status` | Show database status |
+| `okb db migrate [name]` | Apply pending migrations (optionally for specific db) |
+| `okb db list` | List configured databases |
 | `okb db destroy` | Remove container and volume (destructive) |
 | `okb ingest <paths>` | Ingest documents into knowledge base |
 | `okb ingest <paths> --local` | Ingest using local GPU/CPU embedding (no Modal) |
@@ -44,10 +46,11 @@ okb ingest ~/notes ~/docs
 | `okb watch <paths>` | Watch directories for changes |
 | `okb config init` | Create default config file |
 | `okb config show` | Show current configuration |
+| `okb config path` | Print config file path |
 | `okb modal deploy` | Deploy GPU embedder to Modal |
 | `okb token create` | Create API token for HTTP server |
 | `okb token list` | List tokens for a database |
-| `okb token revoke` | Revoke an API token |
+| `okb token revoke [TOKEN] --id <n>` | Revoke token by full value or ID |
 | `okb sync list` | List available API sources (plugins) |
 | `okb sync list-projects <source>` | List projects from source (for config) |
 | `okb sync run <sources>` | Sync data from external APIs |
@@ -59,6 +62,18 @@ okb ingest ~/notes ~/docs
 | `okb llm status` | Show LLM config and connectivity |
 | `okb llm deploy` | Deploy Modal LLM for open model inference |
 | `okb llm clear-cache` | Clear LLM response cache |
+| `okb enrich run` | Extract TODOs and entities from documents |
+| `okb enrich run --dry-run` | Show what would be enriched |
+| `okb enrich pending` | List entities awaiting review |
+| `okb enrich approve <id>` | Approve a pending entity |
+| `okb enrich reject <id>` | Reject a pending entity |
+| `okb enrich analyze` | Analyze database and update description/topics |
+| `okb enrich consolidate` | Run entity consolidation (duplicates, clusters) |
+| `okb enrich merge-proposals` | List pending merge proposals |
+| `okb enrich approve-merge <id>` | Approve an entity merge |
+| `okb enrich reject-merge <id>` | Reject an entity merge |
+| `okb enrich clusters` | List topic clusters |
+| `okb enrich relationships` | List entity relationships |
 
 
 ## Configuration
@@ -93,7 +108,7 @@ chunking:
 Use `--db <name>` to target a specific database with any command.
 
 Environment variables override config file settings:
-- `KB_DATABASE_URL` - Database connection string
+- `OKB_DATABASE_URL` - Database connection string
 - `OKB_DOCKER_PORT` - Docker port mapping
 - `OKB_CONTAINER_NAME` - Docker container name
 
@@ -114,7 +129,7 @@ Merge: scalars replace, lists extend, dicts deep-merge.
 
 ### LLM Integration (Optional)
 
-Enable LLM-based document classification and filtering:
+Enable LLM-based document classification, filtering, and enrichment:
 
 ```yaml
 llm:
@@ -130,11 +145,25 @@ llm:
 | `claude` | `export ANTHROPIC_API_KEY=...` | ~$0.25/1M tokens |
 | `modal` | `okb llm deploy` | ~$0.02/min GPU |
 
-For Modal (no API key needed):
+**Modal LLM Setup** (no API key needed, runs on Modal's GPUs):
+
 ```yaml
 llm:
   provider: modal
-  model: meta-llama/Llama-3.2-3B-Instruct
+  model: microsoft/Phi-3-mini-4k-instruct  # Recommended: no gating
+```
+
+Non-gated models (work immediately):
+- `microsoft/Phi-3-mini-4k-instruct` - Good quality, 4K context
+- `Qwen/Qwen2-1.5B-Instruct` - Smaller/faster
+
+Gated models (require HuggingFace approval + token):
+- `meta-llama/Llama-3.2-3B-Instruct` - Requires accepting license at HuggingFace
+- Setup: `modal secret create huggingface HF_TOKEN=hf_...`
+
+Deploy after configuring:
+```bash
+okb llm deploy
 ```
 
 **Pre-ingest filtering** - skip low-value content during sync:
@@ -148,6 +177,36 @@ plugins:
         action_on_skip: discard  # or "archive"
 ```
 
+### Document Enrichment
+
+Extract TODOs and entities (people, projects, technologies) from documents using LLM:
+
+```bash
+okb enrich run                      # Enrich un-enriched documents
+okb enrich run --dry-run            # Preview what would be enriched
+okb enrich run --source-type markdown  # Only markdown files
+okb enrich run --query "meeting"    # Filter by semantic search
+```
+
+Entities are created as pending suggestions for review:
+```bash
+okb enrich pending                  # List pending entities
+okb enrich approve <id>             # Approve → creates entity document
+okb enrich reject <id>              # Reject → hidden from future suggestions
+```
+
+Configure enrichment behavior:
+```yaml
+enrichment:
+  enabled: true
+  extract_todos: true
+  extract_entities: true
+  auto_create_todos: true       # TODOs created immediately
+  auto_create_entities: false   # Entities go to pending review
+  min_confidence_todo: 0.7
+  min_confidence_entity: 0.8
+```
+
 CLI commands:
 ```bash
 okb llm status              # Show config and connectivity
@@ -185,14 +244,20 @@ okb token create --db default -d "Claude Code"
 okb serve --http --host 0.0.0.0 --port 8080
 ```
 
-Then configure Claude Code to connect via SSE:
+The server uses Streamable HTTP transport (RFC 9728 compliant):
+- `POST /mcp` - Send JSON-RPC messages, receive SSE response
+- `GET /mcp` - Establish SSE connection for server notifications
+- `DELETE /mcp` - Terminate session
+- `/sse` is an alias for `/mcp` for backward compatibility
+
+Configure your MCP client to connect:
 
 ```json
 {
   "mcpServers": {
     "knowledge-base": {
       "type": "sse",
-      "url": "http://localhost:8080/sse",
+      "url": "http://localhost:8080/mcp",
       "headers": {
         "Authorization": "Bearer okb_default_rw_a1b2c3d4e5f6g7h8"
       }
@@ -220,6 +285,20 @@ Then configure Claude Code to connect via SSE:
 | `add_todo` | Create a TODO item in the knowledge base |
 | `trigger_sync` | Sync API sources (Todoist, GitHub, Dropbox Paper) |
 | `trigger_rescan` | Check indexed files for changes and re-ingest |
+| `list_sync_sources` | List available API sync sources with status |
+| `enrich_document` | Run LLM enrichment to extract TODOs/entities |
+| `list_pending_entities` | List entities awaiting review |
+| `approve_entity` | Approve a pending entity |
+| `reject_entity` | Reject a pending entity |
+| `analyze_knowledge_base` | Analyze content and generate description/topics |
+| `find_entity_duplicates` | Find potential duplicate entities |
+| `merge_entities` | Merge duplicate entities |
+| `list_pending_merges` | List pending merge proposals |
+| `approve_merge` | Approve a merge proposal |
+| `reject_merge` | Reject a merge proposal |
+| `get_topic_clusters` | Get topic clusters from consolidation |
+| `get_entity_relationships` | Get relationships between entities |
+| `run_consolidation` | Run full entity consolidation pipeline |
 
 ## Contextual Chunking
 
@@ -242,6 +321,10 @@ project: student-app
 category: backend
 ---
 
+# Your Document Title
+
+Content here...
+```
 
 ## Plugin System