[!ABSTRACT] Epigraf
"Narzędzia LM Studio do operacji CRUD na rekordach — insert, select, update, delete. Główny interfejs modelu LLM do manipulacji danymi."
Pole Wartość Nazwa CRUD Tools Moduł src/tools/crud.tool.tsWersja 1.0.0 Status Draft Zależny od CSV Engine, Schema Manager, Index Manager Używany przez LM Studio (model LLM wywołuje narzędzia)
§2. 🎯 Cel i Odpowiedzialność
§2.1 Cel
Udostępnienie modelowi LLM pełnego CRUD-a na rekordach w tabelach CSV — dodawanie, odczyt, aktualizacja, usuwanie pojedynczych i wielu wierszy.
§2.2 Odpowiedzialności
Insert pojedynczego i wielu wierszy (batch)
Select z opcjonalnym filtrem, limitem i offsetem
Update wiersza po ID
Delete wiersza po ID
Generowanie UUID dla nowych rekordĂłw
Walidacja danych względem schematu przed zapisem
§3. 🛠️ Specyfikacja API/Funkcji
Pole Wartość Nazwa insert_rowOpis Dodaje pojedynczy wiersz do tabeli. Generuje UUID jeśli brak id Wywołuje CSV Engine.appendToCSV, Schema.validateRowAgainstSchema, IndexManager.updateIndex
Parametry:
Parametr Typ Wymagany Opis databasestringâś… Nazwa bazy tablestringâś… Nazwa tabeli dataRecord<string, any>âś… Dane wiersza
Zwraca:
Pole Typ Opis successbooleanCzy operacja się powiodła idstringID utworzonego rekordu tablestringNazwa tabeli
Błędy: TABLE_NOT_FOUND, VALIDATION_ERROR
Pole Wartość Nazwa insert_rowsOpis Dodaje wiele wierszy w batch — jeden zapis do pliku Wywołuje CSV Engine.appendRowsToCSV, Schema.validateRowsAgainstSchema
Parametry:
Parametr Typ Wymagany Opis databasestringâś… Nazwa bazy tablestringâś… Nazwa tabeli rowsRecord<string, any>[]âś… Tablica wierszy (max 1000)
Zwraca: { success, inserted: number, ids: string[] }
Pole Wartość Nazwa select_rowsOpis Pobiera wiersze z opcjonalnym filtrowaniem po kluczach Wywołuje CSV Engine.parseCSV + filtr in-memory
Parametry:
Parametr Typ Wymagany Opis databasestring✅ Nazwa bazy tablestring✅ Nazwa tabeli filterRecord<string, any>❌ Filtrowanie po wartościach (AND) limitnumber❌ Max wierszy (domyślnie 100, max 1000) offsetnumber❌ Pomija N pierwszych wierszy
Zwraca: { rows: Record[]; total: number; filteredTotal: number }
Pole Wartość Nazwa update_rowOpis Aktualizuje istniejący wiersz po ID — merge danych Wywołuje CSV Engine.parseCSV → merge → writeCSV
Parametry:
Parametr Typ Wymagany Opis databasestringâś… Nazwa bazy tablestringâś… Nazwa tabeli idstringâś… ID rekordu do update dataPartial<Record<string, any>>âś… Pola do aktualizacji
Zwraca: { success: boolean; id: string; updated: string[] } (lista zaktualizowanych pĂłl)
Pole Wartość Nazwa delete_rowOpis Usuwa wiersz po ID Wywołuje CSV Engine.parseCSV → filter → writeCSV
Parametry:
Parametr Typ Wymagany Opis databasestring✅ Nazwa bazy tablestring✅ Nazwa tabeli idstring✅ ID rekordu do usunięcia
Zwraca: { success: boolean; id: string }
Pole Wartość Nazwa get_rowOpis Pobiera pojedynczy wiersz po ID Wywołuje CSV Engine.parseCSV + find
Parametry: { database, table, id }
Zwraca: { row: Record<string, any> | null }
§4. 🏗️ Struktura Danych
§5. 🔗 Zależności
§5.1 Wewnętrzne
Komponent Funkcja UĹĽycie engine/csv-engineparseCSV, appendToCSV, appendRowsToCSV, writeCSVWszystkie operacje CRUD engine/schemavalidateRowAgainstSchema, validateRowsAgainstSchemaWalidacja przed insert engine/index-managertableExists, updateIndexWalidacja i indeksowanie
§5.2 Zewnętrzne
Biblioteka Wersja Użycie @lmstudio/sdk^1.x Rejestracja narzędzi uuid^10.x Generowanie ID dla nowych rekordów
§6. 💻 Przykładowe Użycie
§7. Stany i Cykl Życia
§8. Obsługa Błędów
Scenariusz Kod Komunikat Tabela nie istnieje TABLE_NOT_FOUND"Table '{table}' not found in '{database}'"Walidacja nie przeszła VALIDATION_ERRORLista błędów walidacji Rekord nie znaleziony (update) ROW_NOT_FOUND"Row with id '{id}' not found"Batch zbyt duży BATCH_TOO_LARGE"Max 1000 rows per batch"Zduplikowane ID DUPLICATE_ID"Row with id '{id}' already exists"
§9. 🧪 Testy
Jednostkowe
Given When Then Istniejąca tabela, valid data insertRowTool.handler(...)Dopisuje wiersz, zwraca id Brak id w danych insertRowTool.handler(...)Generuje UUID Niezgodność typu insertRowTool.handler(...)Zwraca VALIDATION_ERROR Istniejąca tabela, bez filtra selectRowsTool.handler(...)Zwraca wszystkie wiersze Filtr pasujący selectRowsTool.handler(...)Zwraca tylko pasujące wiersze Filtr niepasujący selectRowsTool.handler(...)rows: [], filteredTotal: 0Istniejący rekord updateRowTool.handler(...)Merge danych, zapis Nieistniejący rekord updateRowTool.handler(...)Zwraca ROW_NOT_FOUND Istniejący rekord deleteRowTool.handler(...)
Mocki / Fixtures
Mock CSV Engine (parseCSV, appendToCSV, writeCSV)
Mock Schema Manager (validateRowAgainstSchema)
Przykładowy plik CSV z 5 wierszami
§10. Powiązane Dokumenty
TDD : ../../TDD.md — §5.2 CRUD Tools, §4 Data Flow
CSV Engine : csv-engine.md — warstwa dostępu do danych
Schema Manager : schema-manager.md — walidacja typów
Query Tools : — zaawansowane zapytania