Rogee
3867736858
- Added data model for AI-assisted renaming including structures for prompts, responses, and policies. - Created implementation plan detailing the integration of Google Genkit into the CLI for renaming tasks. - Developed quickstart guide for setting up and using the new AI rename functionality. - Documented research decisions regarding Genkit orchestration and prompt composition. - Established tasks for phased implementation, including setup, foundational work, and user stories. - Implemented contract tests to ensure AI rename policies and ledger metadata are correctly applied. - Developed integration tests for validating AI rename flows, including preview, apply, and undo functionalities. - Added tooling to pin Genkit dependency for consistent builds.
22 lines
2.3 KiB
Markdown
22 lines
2.3 KiB
Markdown
# Research Log
|
|
|
|
## Genkit Orchestration Strategy
|
|
- **Decision**: Integrate the official Google Genkit Go SDK directly in `internal/ai/genkit`, executing workflows synchronously inside the `renamer ai` command without external services.
|
|
- **Rationale**: Satisfies the CLI-only constraint, keeps deployment as a single Go binary, and leverages Genkit guardrails, evaluators, and prompt templating.
|
|
- **Alternatives considered**: Spawning a Node.js runner (rejected—adds extra runtime and violates updated requirement); Plain REST client to foundation models (rejected—would require rebuilding Genkit safety features manually).
|
|
|
|
## Prompt Composition Template
|
|
- **Decision**: Define typed Go structs mirroring the prompt schema (scope summary, sample filenames, naming policies, banned tokens) and marshal them to JSON for Genkit inputs.
|
|
- **Rationale**: Strong typing prevents malformed prompts and aligns with Genkit Go helpers for variable interpolation and logging.
|
|
- **Alternatives considered**: Free-form natural language prompts (rejected—harder to validate); YAML serialization (rejected—JSON is the Genkit default and reduces dependency footprint).
|
|
|
|
## Response Schema & Validation
|
|
- **Decision**: Genkit workflow returns Go structs (`RenameItem`, `Warnings`) serialized as JSON; the CLI validates coverage, uniqueness, banned-term removal, and sequential numbering before building the plan.
|
|
- **Rationale**: Mirrors existing rename planner data types, enabling reuse of preview/output logic and providing transparent audit metadata.
|
|
- **Alternatives considered**: Returning only ordered filenames (rejected—insufficient context for debugging); CSV output (rejected—lossy and awkward for nested metadata).
|
|
|
|
## Offline & Failure Handling
|
|
- **Decision**: Use Genkit middleware for retry/backoff and error classification; if the workflow fails or produces invalid data, the CLI aborts gracefully, surfaces the issue, and can export the prompt/response for manual inspection.
|
|
- **Rationale**: Maintains Preview-First safety by never applying partial results and keeps error handling contained within the CLI execution.
|
|
- **Alternatives considered**: Persistent background daemon (rejected—contradicts inline execution); Automatic fallback to legacy sequential numbering (rejected—changes user intent, can be added later as an explicit option).
|