# Script to Tool Migration Complete
**Date:** 2026-01-23
**Status:** ✅ Complete
**Related:** [UNIFIED_TOOLS_IMPLEMENTATION_PLAN.md](./UNIFIED_TOOLS_IMPLEMENTATION_PLAN.md)
---
## Summary
The deprecated `'script'` item type has been fully removed from the vector embeddings schema and documentation. The unified tools architecture now uses `'tool'` as the single item type for all executable items.
---
## Database Changes
### Migration Applied
**Table:** `item_embeddings`
**Database:** Agent Kiwi (mrecfyfjpwzrzxoiooew.supabase.co)
**Migration:** `add_vector_embeddings_support`
**Schema created:**
```sql
CREATE TABLE item_embeddings (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
item_id TEXT UNIQUE NOT NULL,
item_type TEXT NOT NULL CHECK (item_type IN ('directive', 'tool', 'knowledge')),
embedding vector(384),
content TEXT NOT NULL,
metadata JSONB DEFAULT '{}',
signature TEXT,
validated_at TIMESTAMPTZ DEFAULT NOW(),
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
```
**Key change:** Removed `'script'` from the CHECK constraint.
### Verification Queries
```sql
-- Verify constraint
SELECT conname, pg_get_constraintdef(oid) AS constraint_def
FROM pg_constraint
WHERE conname LIKE '%item_embeddings%' AND contype = 'c';
-- Result:
-- item_embeddings_item_type_check: CHECK ((item_type = ANY (ARRAY['directive'::text, 'tool'::text, 'knowledge'::text])))
```
**✅ Verified:** Only `('directive', 'tool', 'knowledge')` allowed.
### Indexes Created
1. **Primary Key:** `item_embeddings_pkey` on `id`
2. **Unique:** `item_embeddings_item_id_key` on `item_id`
3. **Vector Search:** `item_embeddings_embedding_idx` using IVFFlat
4. **Type Filter:** `idx_item_embeddings_type` on `item_type`
5. **Item Lookup:** `idx_item_embeddings_item_id` on `item_id`
### Functions Created
- **`search_embeddings()`** - Vector similarity search with cosine distance
- **`update_updated_at_column()`** - Trigger function for `updated_at`
### RLS Policy
- **Policy:** "Users can manage their own embeddings"
- **Condition:** `auth.uid() IS NOT NULL`
- **Applies to:** All operations (SELECT, INSERT, UPDATE, DELETE)
---
## Documentation Updates
### Core Files Updated
| File | Changes |
|------|---------|
| `docs/migrations/supabase_vector_embeddings.sql` | Removed 'script' from CHECK constraint |
| `docs/RAG_INTEGRATION_COMPLETE.md` | Updated schema references |
| `docs/RAG_IMPLEMENTATION_SUMMARY.md` | Updated schema references |
| `AGENTS.md` | Updated item_type definitions and examples |
| `README.md` | Updated all item_type references and examples |
### AGENTS.md Changes
**Item Types Table:**
```markdown
| Type | Description |
| ----------- | ----------------------------------------------- |
| `directive` | Workflow instructions (HOW to accomplish tasks) |
| `tool` | Executable tools (Python scripts, APIs, etc.) |
| `knowledge` | Domain information, patterns, learnings |
```
**Tool Parameters:**
- `search`: `item_type: "directive" | "tool" | "knowledge"`
- `load`: `item_type: "directive" | "tool" | "knowledge"`
- `execute`: `item_type: "directive" | "tool" | "knowledge"`
**Examples:**
- Changed `item_type="script"` to `item_type="tool"`
- Updated comments: "Search for tools" instead of "Search for scripts"
### README.md Changes
**All occurrences updated:**
- Parameter documentation: `"directive"`, `"tool"`, or `"knowledge"`
- Example JSON: `"item_type": "tool"`
- Python examples: `item_type="tool"`
---
## Backward Compatibility
### Natural Language Support
The command dispatch table in AGENTS.md still supports natural language:
- `"search scripts X"` → Maps to `search_scripts` directive
- `"load script X"` → Maps to `load_script` directive
- `"run script X"` → Maps to `run_script` directive
These are **directive names**, not item types. They internally use `item_type="tool"`.
### Test Files
Test files (`tests/unit/test_handlers.py`, etc.) that reference `item_type="script"` are intentionally left unchanged to verify backward compatibility at the handler level. The ToolHandler may internally support `"script"` as an alias to `"tool"`.
---
## Architecture Alignment
This change aligns with the **Unified Tools Architecture** where:
1. **Single Item Type:** `tool` covers all executable items
2. **Tool Subtypes:** Defined by `tool_type` field:
- `primitive` - Core subprocess/HTTP executors
- `runtime` - Dynamic executors (MCP, API)
- `mcp_server` - MCP server instances
- `mcp_tool` - Tools from MCP servers
- `api` - REST API wrappers
3. **No Script/Tool Distinction:** Everything is a "tool" in storage and search
---
## Validation
### Database Verification
✅ Table created successfully
✅ CHECK constraint enforces `('directive', 'tool', 'knowledge')`
✅ Vector indexes created
✅ Search function operational
✅ RLS policy applied
### Documentation Verification
✅ AGENTS.md updated (system prompt)
✅ README.md updated (user documentation)
✅ RAG documentation updated
✅ Migration SQL file updated
### Code Verification
✅ Python files compile successfully
✅ No linter errors introduced
✅ Backward compatibility tests preserved
---
## Impact Summary
### Breaking Changes
⚠️ **Vector embeddings table:** Will reject `item_type='script'` inserts
⚠️ **Documentation:** All examples now use `item_type='tool'`
### Non-Breaking
✅ **Handler layer:** May still support 'script' as alias internally
✅ **Natural language:** "search scripts" still works via directives
✅ **Existing tests:** Preserved for backward compatibility verification
---
## Next Steps
1. ✅ **Database migration applied** - Agent Kiwi database updated
2. ✅ **Documentation updated** - AGENTS.md, README.md, and RAG docs
3. ⚠️ **Handler verification** - Test that ToolHandler works with new schema
4. ⚠️ **Embedding pipeline test** - Verify automatic embedding works
5. ⚠️ **Search integration test** - Verify vector search finds tools correctly
---
## Related Documents
- [UNIFIED_TOOLS_IMPLEMENTATION_PLAN.md](./UNIFIED_TOOLS_IMPLEMENTATION_PLAN.md) - Overall tools architecture
- [RAG_INTEGRATION_COMPLETE.md](./RAG_INTEGRATION_COMPLETE.md) - RAG implementation status
- [PHASE_6_STATUS_REPORT.md](./PHASE_6_STATUS_REPORT.md) - Implementation status
- [TOOLS_EVOLUTION_PROPOSAL.md](./TOOLS_EVOLUTION_PROPOSAL.md) - Original proposal
---
## Database Connection Details
**Project:** Agent Kiwi
**Project ID:** mrecfyfjpwzrzxoiooew
**URL:** https://mrecfyfjpwzrzxoiooew.supabase.co
**Region:** ap-northeast-2
**PostgreSQL:** 17.6.1.054
**Tables Created:**
- `item_embeddings` (with vector support via pgvector extension)
**Migration Name:** `add_vector_embeddings_support`
**Applied:** 2026-01-23
**Status:** ✅ Success
