francwa
99c95af64e
Introduce a first-class semantic layer for tool descriptions, separated
from Python signatures (which stay the source of truth for types and
required-ness).
New
- alfred/agent/tools/spec.py — ToolSpec / ParameterSpec / ReturnsSpec
dataclasses with strict YAML validation (ToolSpecError on malformed
or inconsistent specs). compile_description() builds the rich text
passed to the LLM as Tool.description, with sections for summary,
description, when_to_use, when_not_to_use, next_steps, and returns.
compile_parameter_description() injects the 'why_needed' field next
to each parameter so the LLM sees the *intent* of each argument.
- alfred/agent/tools/spec_loader.py — discovers tools/specs/*.yaml,
enforces filename ↔ spec.name match, rejects duplicates.
- alfred/agent/tools/specs/ — one YAML per tool:
* resolve_season_destination.yaml
* resolve_episode_destination.yaml
* resolve_movie_destination.yaml
* resolve_series_destination.yaml
* move_to_destination.yaml
Refactor
- alfred/agent/registry.py
* _create_tool_from_function now takes an optional ToolSpec.
When provided, the long description + per-parameter descriptions
come from the spec; types and required-ness still come from the
Python signature.
* Cross-validates spec.parameters against the function signature —
crashes on missing or extra entries.
* make_tools() loads all specs at startup and hands the right one
to each tool. Tools without a spec fall back to the old
docstring-only behaviour, so the 14 not-yet-migrated tools keep
working unchanged.
* Adds 'array' and 'object' to the Python→JSON type mapping and
handles Optional[X] / X | None annotations.
- alfred/agent/tools/filesystem.py
* Drops the '_tool' suffix on the 4 resolve_* wrappers (option 1:
alias the use-case imports as _resolve_*). Tool names exposed to
the LLM now match the underlying use case verbatim.
* Wrapper docstrings shrink to a one-liner pointing to the YAML
spec — no more duplicated when_to_use/Args/Returns in Python.
Verified
- make_tools() loads 19 tools (5 with YAML spec, 14 doc-only).
- Compiled descriptions render cleanly with all sections.
78 lines
2.6 KiB
YAML
78 lines
2.6 KiB
YAML
name: resolve_series_destination
|
|
|
|
summary: >
|
|
Compute the destination path for a complete multi-season series pack (folder move).
|
|
|
|
description: |
|
|
Resolves the target series folder for a pack that contains multiple seasons
|
|
(e.g. S01-S05 in a single release). Returns only the series folder — the
|
|
whole source folder is moved as-is into the library, no per-season
|
|
restructuring. If a folder with a different name already exists for this
|
|
show, returns needs_clarification.
|
|
|
|
when_to_use: |
|
|
Use after analyze_release has identified the release as a complete-series
|
|
pack (media_type=tv_complete, or multi-season indicators). TMDB must
|
|
already be queried for canonical title/year.
|
|
|
|
when_not_to_use: |
|
|
- Single-season packs: use resolve_season_destination.
|
|
- Single episodes: use resolve_episode_destination.
|
|
- Movies: use resolve_movie_destination.
|
|
|
|
next_steps: |
|
|
- On status=ok: call move_to_destination with source=<download folder> and
|
|
destination=series_folder.
|
|
- On status=needs_clarification: ask the user, re-call with
|
|
confirmed_folder set.
|
|
- On status=error: surface the message; do not move.
|
|
|
|
parameters:
|
|
release_name:
|
|
description: Raw release folder name as it appears on disk.
|
|
why_needed: |
|
|
Drives extraction of quality/source/codec/group tokens for the target
|
|
folder name, even though the multi-season structure inside is kept
|
|
as-is.
|
|
example: The.Wire.S01-S05.1080p.BluRay.x265-GROUP
|
|
|
|
tmdb_title:
|
|
description: Canonical show title from TMDB.
|
|
why_needed: |
|
|
Title prefix of the series folder; comes from TMDB to avoid raw
|
|
release-name spellings.
|
|
example: The Wire
|
|
|
|
tmdb_year:
|
|
description: Show start year from TMDB.
|
|
why_needed: |
|
|
Disambiguates shows that share a title across eras and locks the
|
|
folder identity.
|
|
example: "2002"
|
|
|
|
confirmed_folder:
|
|
description: Folder name chosen by the user after needs_clarification.
|
|
why_needed: |
|
|
Forces the use case to use this exact folder name and skip detection.
|
|
example: The.Wire.2002.1080p.BluRay.x265-GROUP
|
|
|
|
returns:
|
|
ok:
|
|
description: Path resolved; ready to move the pack.
|
|
fields:
|
|
series_folder: Absolute path to the destination series folder.
|
|
series_folder_name: Folder name for display.
|
|
is_new_series_folder: True if the folder doesn't exist yet.
|
|
|
|
needs_clarification:
|
|
description: A folder exists with a different name; ask the user.
|
|
fields:
|
|
question: Human-readable question.
|
|
options: List of folder names to pick from.
|
|
|
|
error:
|
|
description: Resolution failed.
|
|
fields:
|
|
error: Short error code.
|
|
message: Human-readable explanation.
|