feat: implemented declarative schema-based settings system

2026-01-06 04:55:52 +01:00
405 changed files with 12700 additions and 41619 deletions
@@ -1,80 +0,0 @@
 # --- IMPORTANT ---
 # Settings are split across multiple files for clarity.
 # Files (loaded in this order, last wins):
 #   .env.alfred   — app config and service addresses (safe to commit)
 #   .env.secrets  — generated secrets, passwords, URIs and API keys (DO NOT COMMIT)
 #   .env.make     — build metadata synced from pyproject.toml (safe to commit)
 #
 # To customize: edit .env.alfred for config, .env.secrets for secrets.
 # --- Alfred ---
 MAX_HISTORY_MESSAGES=10
 MAX_TOOL_ITERATIONS=10
 REQUEST_TIMEOUT=30
 # LLM Settings
 LLM_TEMPERATURE=0.2
 # Persistence
 DATA_STORAGE_DIR=data
 # Network
 HOST=0.0.0.0
 PORT=3080
 # --- DATABASES ---
 # Passwords and connection URIs are auto-generated in .env.secrets.
 # Edit host/port/user/dbname here if needed.
 # MongoDB (Application Data)
 MONGO_HOST=mongodb
 MONGO_PORT=27017
 MONGO_USER=alfred
 MONGO_DB_NAME=alfred
 # PostgreSQL (Vector Database / RAG)
 POSTGRES_HOST=vectordb
 POSTGRES_PORT=5432
 POSTGRES_USER=alfred
 POSTGRES_DB_NAME=alfred
 # --- EXTERNAL SERVICES ---
 # TMDB — Media metadata (required). Get your key at https://www.themoviedb.org/
 # → TMDB_API_KEY goes in .env.secrets
 TMDB_BASE_URL=https://api.themoviedb.org/3
 # qBittorrent
 # → QBITTORRENT_PASSWORD goes in .env.secrets
 QBITTORRENT_URL=https://qb.lan.anustart.top
 QBITTORRENT_USERNAME=letmein
 QBITTORRENT_PORT=16140
 # Path translation: host-side prefix → container-side prefix
 QBITTORRENT_HOST_PATH=/mnt/testipool
 QBITTORRENT_CONTAINER_PATH=/mnt/data
 # Meilisearch
 # → MEILI_MASTER_KEY goes in .env.secrets
 # MEILI_ENABLED=false # KEY DOESN'T EXISTS => SEARCH IS THE PROPER KEY
 SEARCH=false
 MEILI_NO_ANALYTICS=true
 MEILI_HOST=http://meilisearch:7700
 # --- LLM CONFIGURATION ---
 # Providers: local, openai, anthropic, deepseek, google, kimi
 # → API keys go in .env.secrets
 DEFAULT_LLM_PROVIDER=deepseek
 # Local LLM (Ollama)
 #OLLAMA_BASE_URL=http://ollama:11434
 #OLLAMA_MODEL=llama3.3:latest
 OLLAMA_BASE_URL=http://10.0.0.11:11434
 OLLAMA_MODEL=glm-4.7-flash:latest
 # --- RAG ENGINE ---
 RAG_ENABLED=TRUE
 RAG_API_URL=http://rag_api:8000
 RAG_API_PORT=8000
 EMBEDDINGS_PROVIDER=ollama
 EMBEDDINGS_MODEL=nomic-embed-text
@@ -1,13 +1,3 @@
 # --- IMPORTANT ---
 # Settings are split across multiple files for clarity.
 # Files (loaded in this order, last wins):
 #   .env.alfred   — app config and service addresses (safe to commit)
 #   .env.secrets  — generated secrets, passwords, URIs and API keys (DO NOT COMMIT)
 #   .env.make     — build metadata synced from pyproject.toml (safe to commit)
 #
 # To customize: edit .env.alfred for config, .env.secrets for secrets.
 # --- Alfred ---
 MAX_HISTORY_MESSAGES=10
 MAX_TOOL_ITERATIONS=10
 REQUEST_TIMEOUT=30
@@ -18,54 +8,84 @@ LLM_TEMPERATURE=0.2
 # Persistence
 DATA_STORAGE_DIR=data
-# Network
+# Network configuration
 HOST=0.0.0.0
 PORT=3080
-# --- DATABASES ---
+# Build informations (Synced with pyproject.toml via bootstrap)
-# Passwords and connection URIs are auto-generated in .env.secrets.
+ALFRED_VERSION=
-# Edit host/port/user/dbname here if needed.
+IMAGE_NAME=
 LIBRECHAT_VERSION=
 PYTHON_VERSION=
 PYTHON_VERSION_SHORT=
 RAG_VERSION=
 RUNNER=
 SERVICE_NAME=
 # --- SECURITY KEYS (CRITICAL) ---
 # These are used for session tokens and encrypting sensitive data in MongoDB.
 # If you lose these, you lose access to encrypted stored credentials.
 JWT_SECRET=
 JWT_REFRESH_SECRET=
 CREDS_KEY=
 CREDS_IV=
 # --- DATABASES (AUTO-SECURED) ---
 # Alfred uses MongoDB for application state and PostgreSQL for Vector RAG.
 # Passwords will be generated as 24-character secure tokens if left blank.
 # MongoDB (Application Data)
 MONGO_URI=
 MONGO_HOST=mongodb
 MONGO_PORT=27017
 MONGO_USER=alfred
 MONGO_PASSWORD=
 MONGO_DB_NAME=LibreChat
 # PostgreSQL (Vector Database / RAG)
 POSTGRES_URI=
 POSTGRES_HOST=vectordb
 POSTGRES_PORT=5432
 POSTGRES_USER=alfred
 POSTGRES_PASSWORD=
 POSTGRES_DB_NAME=alfred
 # --- EXTERNAL SERVICES ---
-
+# Media Metadata (Required)
-# TMDB — Media metadata (required). Get your key at https://www.themoviedb.org/
+# Get your key at https://www.themoviedb.org/
-# → TMDB_API_KEY goes in .env.secrets
+TMDB_API_KEY=
 TMDB_BASE_URL=https://api.themoviedb.org/3
-# qBittorrent
+# qBittorrent integration
 # → QBITTORRENT_PASSWORD goes in .env.secrets
 QBITTORRENT_URL=http://qbittorrent:16140
 QBITTORRENT_USERNAME=admin
 QBITTORRENT_PASSWORD=
 QBITTORRENT_PORT=16140
 # Meilisearch
 # → MEILI_MASTER_KEY goes in .env.secrets
 MEILI_ENABLED=FALSE
 MEILI_NO_ANALYTICS=TRUE
 MEILI_HOST=http://meilisearch:7700
 MEILI_MASTER_KEY=
 # --- LLM CONFIGURATION ---
-# Providers: local, openai, anthropic, deepseek, google, kimi
+# Providers: 'local', 'openai', 'anthropic', 'deepseek', 'google', 'kimi'
 # → API keys go in .env.secrets
 DEFAULT_LLM_PROVIDER=local
 # Local LLM (Ollama)
 OLLAMA_BASE_URL=http://ollama:11434
 OLLAMA_MODEL=llama3.3:latest
 # --- API KEYS (OPTIONAL) ---
 # Fill only the ones you intend to use.
 ANTHROPIC_API_KEY=
 DEEPSEEK_API_KEY=
 GOOGLE_API_KEY=
 KIMI_API_KEY=
 OPENAI_API_KEY=
 # --- RAG ENGINE ---
 # Enable/Disable the Retrieval Augmented Generation system
 RAG_ENABLED=TRUE
 RAG_API_URL=http://rag_api:8000
 RAG_API_PORT=8000
@@ -1,878 +0,0 @@
 #=====================================================================#
 #                       LibreChat Configuration                       #
 #=====================================================================#
 # Please refer to the reference documentation for assistance          #
 # with configuring your LibreChat environment.                        #
 #                                                                     #
 # https://www.librechat.ai/docs/configuration/dotenv                  #
 #=====================================================================#
 #==================================================#
 #               Server Configuration               #
 #==================================================#
 HOST=localhost
 PORT=3080
 MONGO_URI=mongodb://127.0.0.1:27017/LibreChat
 #The maximum number of connections in the connection pool. */
 MONGO_MAX_POOL_SIZE=
 #The minimum number of connections in the connection pool. */
 MONGO_MIN_POOL_SIZE=
 #The maximum number of connections that may be in the process of being established concurrently by the connection pool. */
 MONGO_MAX_CONNECTING=
 #The maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed. */
 MONGO_MAX_IDLE_TIME_MS=
 #The maximum time in milliseconds that a thread can wait for a connection to become available. */
 MONGO_WAIT_QUEUE_TIMEOUT_MS=
 # Set to false to disable automatic index creation for all models associated with this connection. */
 MONGO_AUTO_INDEX=
 # Set to `false` to disable Mongoose automatically calling `createCollection()` on every model created on this connection. */
 MONGO_AUTO_CREATE=
 DOMAIN_CLIENT=http://localhost:3080
 DOMAIN_SERVER=http://localhost:3080
 NO_INDEX=true
 # Use the address that is at most n number of hops away from the Express application.
 # req.socket.remoteAddress is the first hop, and the rest are looked for in the X-Forwarded-For header from right to left.
 # A value of 0 means that the first untrusted address would be req.socket.remoteAddress, i.e. there is no reverse proxy.
 # Defaulted to 1.
 TRUST_PROXY=1
 # Minimum password length for user authentication
 # Default: 8
 # Note: When using LDAP authentication, you may want to set this to 1 
 # to bypass local password validation, as LDAP servers handle their own
 # password policies.
 # MIN_PASSWORD_LENGTH=8
 # When enabled, the app will continue running after encountering uncaught exceptions
 # instead of exiting the process. Not recommended for production unless necessary.
 # CONTINUE_ON_UNCAUGHT_EXCEPTION=false
 #===============#
 # JSON Logging  #
 #===============#
 # Use when process console logs in cloud deployment like GCP/AWS
 CONSOLE_JSON=false
 #===============#
 # Debug Logging #
 #===============#
 DEBUG_LOGGING=true
 DEBUG_CONSOLE=false
 # Set to true to enable agent debug logging
 AGENT_DEBUG_LOGGING=false
 # Enable memory diagnostics (logs heap/RSS snapshots every 60s, auto-enabled with --inspect)
 # MEM_DIAG=true
 #=============#
 # Permissions #
 #=============#
 # UID=1000
 # GID=1000
 #==============#
 # Node Options #
 #==============#
 # NOTE: NODE_MAX_OLD_SPACE_SIZE is NOT recognized by Node.js directly.
 # This variable is used as a build argument for Docker or CI/CD workflows,
 # and is NOT used by Node.js to set the heap size at runtime.
 # To configure Node.js memory, use NODE_OPTIONS, e.g.:
 # NODE_OPTIONS="--max-old-space-size=6144"
 # See: https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-mib
 NODE_MAX_OLD_SPACE_SIZE=6144
 #===============#
 # Configuration #
 #===============#
 # Use an absolute path, a relative path, or a URL
 # CONFIG_PATH="/alternative/path/to/librechat.yaml"
 #==================#
 # Langfuse Tracing #
 #==================#
 # Get Langfuse API keys for your project from the project settings page: https://cloud.langfuse.com
 # LANGFUSE_PUBLIC_KEY=
 # LANGFUSE_SECRET_KEY=
 # LANGFUSE_BASE_URL=
 #===================================================#
 #                     Endpoints                     #
 #===================================================#
 # ENDPOINTS=openAI,assistants,azureOpenAI,google,anthropic
 PROXY=
 #===================================#
 # Known Endpoints - librechat.yaml  #
 #===================================#
 # https://www.librechat.ai/docs/configuration/librechat_yaml/ai_endpoints
 # ANYSCALE_API_KEY=
 # APIPIE_API_KEY=
 # COHERE_API_KEY=
 # DEEPSEEK_API_KEY=
 # DATABRICKS_API_KEY=
 # FIREWORKS_API_KEY=
 # GROQ_API_KEY=
 # HUGGINGFACE_TOKEN=
 # MISTRAL_API_KEY=
 # OPENROUTER_KEY=
 # PERPLEXITY_API_KEY=
 # SHUTTLEAI_API_KEY=
 # TOGETHERAI_API_KEY=
 # UNIFY_API_KEY=
 # XAI_API_KEY=
 #============#
 # Anthropic  #
 #============#
 ANTHROPIC_API_KEY=user_provided
 # ANTHROPIC_MODELS=claude-sonnet-4-6,claude-opus-4-6,claude-opus-4-20250514,claude-sonnet-4-20250514,claude-3-7-sonnet-20250219,claude-3-5-sonnet-20241022,claude-3-5-haiku-20241022,claude-3-opus-20240229,claude-3-sonnet-20240229,claude-3-haiku-20240307
 # ANTHROPIC_REVERSE_PROXY=
 # Set to true to use Anthropic models through Google Vertex AI instead of direct API
 # ANTHROPIC_USE_VERTEX=
 # ANTHROPIC_VERTEX_REGION=us-east5
 #============#
 # Azure      #
 #============#
 # Note: these variables are DEPRECATED
 # Use the `librechat.yaml` configuration for `azureOpenAI` instead
 # You may also continue to use them if you opt out of using the `librechat.yaml` configuration
 # AZURE_OPENAI_DEFAULT_MODEL=gpt-3.5-turbo # Deprecated
 # AZURE_OPENAI_MODELS=gpt-3.5-turbo,gpt-4 # Deprecated
 # AZURE_USE_MODEL_AS_DEPLOYMENT_NAME=TRUE # Deprecated
 # AZURE_API_KEY= # Deprecated
 # AZURE_OPENAI_API_INSTANCE_NAME= # Deprecated
 # AZURE_OPENAI_API_DEPLOYMENT_NAME= # Deprecated
 # AZURE_OPENAI_API_VERSION= # Deprecated
 # AZURE_OPENAI_API_COMPLETIONS_DEPLOYMENT_NAME= # Deprecated
 # AZURE_OPENAI_API_EMBEDDINGS_DEPLOYMENT_NAME= # Deprecated
 #=================#
 #   AWS Bedrock   #
 #=================#
 # BEDROCK_AWS_DEFAULT_REGION=us-east-1 # A default region must be provided
 # BEDROCK_AWS_ACCESS_KEY_ID=someAccessKey
 # BEDROCK_AWS_SECRET_ACCESS_KEY=someSecretAccessKey
 # BEDROCK_AWS_SESSION_TOKEN=someSessionToken
 # Note: This example list is not meant to be exhaustive. If omitted, all known, supported model IDs will be included for you.
 # BEDROCK_AWS_MODELS=anthropic.claude-sonnet-4-6,anthropic.claude-opus-4-6-v1,anthropic.claude-3-5-sonnet-20240620-v1:0,meta.llama3-1-8b-instruct-v1:0
 # Cross-region inference model IDs: us.anthropic.claude-sonnet-4-6,us.anthropic.claude-opus-4-6-v1,global.anthropic.claude-opus-4-6-v1
 # See all Bedrock model IDs here: https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html#model-ids-arns
 # Notes on specific models:
 # The following models are not support due to not supporting streaming:
 # ai21.j2-mid-v1
 # The following models are not support due to not supporting conversation history:
 # ai21.j2-ultra-v1, cohere.command-text-v14, cohere.command-light-text-v14
 #============#
 # Google     #
 #============#
 GOOGLE_KEY=user_provided
 # GOOGLE_REVERSE_PROXY=
 # Some reverse proxies do not support the X-goog-api-key header, uncomment to pass the API key in Authorization header instead.
 # GOOGLE_AUTH_HEADER=true
 # Gemini API (AI Studio)
 # GOOGLE_MODELS=gemini-3.1-pro-preview,gemini-3.1-pro-preview-customtools,gemini-3.1-flash-lite-preview,gemini-2.5-pro,gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.0-flash,gemini-2.0-flash-lite
 # Vertex AI
 # GOOGLE_MODELS=gemini-3.1-pro-preview,gemini-3.1-pro-preview-customtools,gemini-3.1-flash-lite-preview,gemini-2.5-pro,gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.0-flash-001,gemini-2.0-flash-lite-001
 # GOOGLE_TITLE_MODEL=gemini-2.0-flash-lite-001
 # Google Cloud region for Vertex AI (used by both chat and image generation)
 # GOOGLE_LOC=us-central1
 # Alternative region env var for Gemini Image Generation
 # GOOGLE_CLOUD_LOCATION=global
 # Vertex AI Service Account Configuration
 # Path to your Google Cloud service account JSON file
 # GOOGLE_SERVICE_KEY_FILE=/path/to/service-account.json
 # Google Safety Settings
 # NOTE: These settings apply to both Vertex AI and Gemini API (AI Studio)
 #
 # For Vertex AI:
 # To use the BLOCK_NONE setting, you need either:
 # (a) Access through an allowlist via your Google account team, or
 # (b) Switch to monthly invoiced billing: https://cloud.google.com/billing/docs/how-to/invoiced-billing
 #
 # For Gemini API (AI Studio):
 # BLOCK_NONE is available by default, no special account requirements.
 #
 # Available options: BLOCK_NONE, BLOCK_ONLY_HIGH, BLOCK_MEDIUM_AND_ABOVE, BLOCK_LOW_AND_ABOVE
 #
 # GOOGLE_SAFETY_SEXUALLY_EXPLICIT=BLOCK_ONLY_HIGH
 # GOOGLE_SAFETY_HATE_SPEECH=BLOCK_ONLY_HIGH
 # GOOGLE_SAFETY_HARASSMENT=BLOCK_ONLY_HIGH
 # GOOGLE_SAFETY_DANGEROUS_CONTENT=BLOCK_ONLY_HIGH
 # GOOGLE_SAFETY_CIVIC_INTEGRITY=BLOCK_ONLY_HIGH
 #========================#
 # Gemini Image Generation #
 #========================#
 # Gemini Image Generation Tool (for Agents)
 # Supports multiple authentication methods in priority order:
 # 1. User-provided API key (via GUI)
 # 2. GEMINI_API_KEY env var (admin-configured)
 # 3. GOOGLE_KEY env var (shared with Google chat endpoint)
 # 4. Vertex AI service account (via GOOGLE_SERVICE_KEY_FILE)
 # Option A: Use dedicated Gemini API key for image generation
 # GEMINI_API_KEY=your-gemini-api-key
 # Vertex AI model for image generation (defaults to gemini-2.5-flash-image)
 # GEMINI_IMAGE_MODEL=gemini-2.5-flash-image
 #============#
 # OpenAI     #
 #============#
 OPENAI_API_KEY=user_provided
 # OPENAI_MODELS=gpt-5,gpt-5-codex,gpt-5-mini,gpt-5-nano,o3-pro,o3,o4-mini,gpt-4.1,gpt-4.1-mini,gpt-4.1-nano,o3-mini,o1-pro,o1,gpt-4o,gpt-4o-mini
 DEBUG_OPENAI=false
 # TITLE_CONVO=false
 # OPENAI_TITLE_MODEL=gpt-4o-mini
 # OPENAI_SUMMARIZE=true
 # OPENAI_SUMMARY_MODEL=gpt-4o-mini
 # OPENAI_FORCE_PROMPT=true
 # OPENAI_REVERSE_PROXY=
 # OPENAI_ORGANIZATION=
 #====================#
 #   Assistants API   #
 #====================#
 ASSISTANTS_API_KEY=user_provided
 # ASSISTANTS_BASE_URL=
 # ASSISTANTS_MODELS=gpt-4o,gpt-4o-mini,gpt-3.5-turbo-0125,gpt-3.5-turbo-16k-0613,gpt-3.5-turbo-16k,gpt-3.5-turbo,gpt-4,gpt-4-0314,gpt-4-32k-0314,gpt-4-0613,gpt-3.5-turbo-0613,gpt-3.5-turbo-1106,gpt-4-0125-preview,gpt-4-turbo-preview,gpt-4-1106-preview
 #==========================#
 #   Azure Assistants API   #
 #==========================#
 # Note: You should map your credentials with custom variables according to your Azure OpenAI Configuration
 # The models for Azure Assistants are also determined by your Azure OpenAI configuration.
 # More info, including how to enable use of Assistants with Azure here:
 # https://www.librechat.ai/docs/configuration/librechat_yaml/ai_endpoints/azure#using-assistants-with-azure
 CREDS_KEY=f34be427ebb29de8d88c107a71546019685ed8b241d8f2ed00c3df97ad2566f0
 CREDS_IV=e2341419ec3dd3d19b13a1a87fafcbfb
 # Azure AI Search
 #-----------------
 AZURE_AI_SEARCH_SERVICE_ENDPOINT=
 AZURE_AI_SEARCH_INDEX_NAME=
 AZURE_AI_SEARCH_API_KEY=
 AZURE_AI_SEARCH_API_VERSION=
 AZURE_AI_SEARCH_SEARCH_OPTION_QUERY_TYPE=
 AZURE_AI_SEARCH_SEARCH_OPTION_TOP=
 AZURE_AI_SEARCH_SEARCH_OPTION_SELECT=
 # OpenAI Image Tools Customization
 #----------------
 # IMAGE_GEN_OAI_API_KEY= # Create or reuse OpenAI API key for image generation tool
 # IMAGE_GEN_OAI_BASEURL= # Custom OpenAI base URL for image generation tool
 # IMAGE_GEN_OAI_AZURE_API_VERSION= # Custom Azure OpenAI deployments
 # IMAGE_GEN_OAI_MODEL=gpt-image-1 # OpenAI image model (e.g., gpt-image-1, gpt-image-1.5)
 # IMAGE_GEN_OAI_DESCRIPTION=
 # IMAGE_GEN_OAI_DESCRIPTION_WITH_FILES=Custom description for image generation tool when files are present
 # IMAGE_GEN_OAI_DESCRIPTION_NO_FILES=Custom description for image generation tool when no files are present
 # IMAGE_EDIT_OAI_DESCRIPTION=Custom description for image editing tool
 # IMAGE_GEN_OAI_PROMPT_DESCRIPTION=Custom prompt description for image generation tool
 # IMAGE_EDIT_OAI_PROMPT_DESCRIPTION=Custom prompt description for image editing tool
 # DALL·E
 #----------------
 # DALLE_API_KEY=
 # DALLE3_API_KEY=
 # DALLE2_API_KEY=
 # DALLE3_SYSTEM_PROMPT=
 # DALLE2_SYSTEM_PROMPT=
 # DALLE_REVERSE_PROXY=
 # DALLE3_BASEURL=
 # DALLE2_BASEURL=
 # DALL·E (via Azure OpenAI)
 # Note: requires some of the variables above to be set
 #----------------
 # DALLE3_AZURE_API_VERSION=
 # DALLE2_AZURE_API_VERSION=
 # Flux
 #-----------------
 FLUX_API_BASE_URL=https://api.us1.bfl.ai
 # FLUX_API_BASE_URL = 'https://api.bfl.ml';
 # Get your API key at https://api.us1.bfl.ai/auth/profile
 # FLUX_API_KEY=
 # Google
 #-----------------
 GOOGLE_SEARCH_API_KEY=
 GOOGLE_CSE_ID=
 # Stable Diffusion
 #-----------------
 SD_WEBUI_URL=http://host.docker.internal:7860
 # Tavily
 #-----------------
 TAVILY_API_KEY=
 # Traversaal
 #-----------------
 TRAVERSAAL_API_KEY=
 # WolframAlpha
 #-----------------
 WOLFRAM_APP_ID=
 # Zapier
 #-----------------
 ZAPIER_NLA_API_KEY=
 #==================================================#
 #                      Search                      #
 #==================================================#
 SEARCH=true
 MEILI_NO_ANALYTICS=true
 MEILI_HOST=http://0.0.0.0:7700
 MEILI_MASTER_KEY=DrhYf7zENyR6AlUCKmnz0eYASOQdl6zxH7s7MKFSfFCt
 # Optional: Disable indexing, useful in a multi-node setup
 # where only one instance should perform an index sync.
 # MEILI_NO_SYNC=true
 #==================================================#
 #          Speech to Text & Text to Speech         #
 #==================================================#
 STT_API_KEY=
 TTS_API_KEY=
 #==================================================#
 #                        RAG                       #
 #==================================================#
 # More info: https://www.librechat.ai/docs/configuration/rag_api
 # RAG_OPENAI_BASEURL=
 # RAG_OPENAI_API_KEY=
 # RAG_USE_FULL_CONTEXT=
 # EMBEDDINGS_PROVIDER=openai
 # EMBEDDINGS_MODEL=text-embedding-3-small
 #===================================================#
 #                    User System                    #
 #===================================================#
 #========================#
 # Moderation             #
 #========================#
 OPENAI_MODERATION=false
 OPENAI_MODERATION_API_KEY=
 # OPENAI_MODERATION_REVERSE_PROXY=
 BAN_VIOLATIONS=true
 BAN_DURATION=1000 * 60 * 60 * 2
 BAN_INTERVAL=20
 LOGIN_VIOLATION_SCORE=1
 REGISTRATION_VIOLATION_SCORE=1
 CONCURRENT_VIOLATION_SCORE=1
 MESSAGE_VIOLATION_SCORE=1
 NON_BROWSER_VIOLATION_SCORE=20
 TTS_VIOLATION_SCORE=0
 STT_VIOLATION_SCORE=0
 FORK_VIOLATION_SCORE=0
 IMPORT_VIOLATION_SCORE=0
 FILE_UPLOAD_VIOLATION_SCORE=0
 LOGIN_MAX=7
 LOGIN_WINDOW=5
 REGISTER_MAX=5
 REGISTER_WINDOW=60
 LIMIT_CONCURRENT_MESSAGES=true
 CONCURRENT_MESSAGE_MAX=2
 LIMIT_MESSAGE_IP=true
 MESSAGE_IP_MAX=40
 MESSAGE_IP_WINDOW=1
 LIMIT_MESSAGE_USER=false
 MESSAGE_USER_MAX=40
 MESSAGE_USER_WINDOW=1
 ILLEGAL_MODEL_REQ_SCORE=5
 #========================#
 # Balance                #
 #========================#
 # CHECK_BALANCE=false
 # START_BALANCE=20000 # note: the number of tokens that will be credited after registration.
 #========================#
 # Registration and Login #
 #========================#
 ALLOW_EMAIL_LOGIN=true
 ALLOW_REGISTRATION=true
 ALLOW_SOCIAL_LOGIN=false
 ALLOW_SOCIAL_REGISTRATION=false
 ALLOW_PASSWORD_RESET=false
 # ALLOW_ACCOUNT_DELETION=true # note: enabled by default if omitted/commented out
 ALLOW_UNVERIFIED_EMAIL_LOGIN=true
 SESSION_EXPIRY=1000 * 60 * 15
 REFRESH_TOKEN_EXPIRY=(1000 * 60 * 60 * 24) * 7
 JWT_SECRET=16f8c0ef4a5d391b26034086c628469d3f9f497f08163ab9b40137092f2909ef
 JWT_REFRESH_SECRET=eaa5191f2914e30b9387fd84e254e4ba6fc51b4654968a9b0803b456a54b8418
 # Discord
 DISCORD_CLIENT_ID=
 DISCORD_CLIENT_SECRET=
 DISCORD_CALLBACK_URL=/oauth/discord/callback
 # Facebook
 FACEBOOK_CLIENT_ID=
 FACEBOOK_CLIENT_SECRET=
 FACEBOOK_CALLBACK_URL=/oauth/facebook/callback
 # GitHub
 GITHUB_CLIENT_ID=
 GITHUB_CLIENT_SECRET=
 GITHUB_CALLBACK_URL=/oauth/github/callback
 # GitHub Enterprise
 # GITHUB_ENTERPRISE_BASE_URL=
 # GITHUB_ENTERPRISE_USER_AGENT=
 # Google
 GOOGLE_CLIENT_ID=
 GOOGLE_CLIENT_SECRET=
 GOOGLE_CALLBACK_URL=/oauth/google/callback
 # Apple
 APPLE_CLIENT_ID=
 APPLE_TEAM_ID=
 APPLE_KEY_ID=
 APPLE_PRIVATE_KEY_PATH=
 APPLE_CALLBACK_URL=/oauth/apple/callback
 # OpenID
 OPENID_CLIENT_ID=
 OPENID_CLIENT_SECRET=
 OPENID_ISSUER=
 OPENID_SESSION_SECRET=
 OPENID_SCOPE="openid profile email"
 OPENID_CALLBACK_URL=/oauth/openid/callback
 OPENID_REQUIRED_ROLE=
 OPENID_REQUIRED_ROLE_TOKEN_KIND=
 OPENID_REQUIRED_ROLE_PARAMETER_PATH=
 OPENID_ADMIN_ROLE=
 OPENID_ADMIN_ROLE_PARAMETER_PATH=
 OPENID_ADMIN_ROLE_TOKEN_KIND=
 # Set to determine which user info property returned from OpenID Provider to store as the User's username
 OPENID_USERNAME_CLAIM=
 # Set to determine which user info property returned from OpenID Provider to store as the User's name
 OPENID_NAME_CLAIM=
 # Set to determine which user info claim to use as the email/identifier for user matching (e.g., "upn" for Entra ID)
 # When not set, defaults to: email -> preferred_username -> upn
 OPENID_EMAIL_CLAIM=
 # Optional audience parameter for OpenID authorization requests
 OPENID_AUDIENCE=
 OPENID_BUTTON_LABEL=
 OPENID_IMAGE_URL=
 # Set to true to automatically redirect to the OpenID provider when a user visits the login page
 # This will bypass the login form completely for users, only use this if OpenID is your only authentication method
 OPENID_AUTO_REDIRECT=false
 # Set to true to use PKCE (Proof Key for Code Exchange) for OpenID authentication
 OPENID_USE_PKCE=false
 #Set to true to reuse openid tokens for authentication management instead of using the mongodb session and the custom refresh token.
 OPENID_REUSE_TOKENS=
 #By default, signing key verification results are cached in order to prevent excessive HTTP requests to the JWKS endpoint.
 #If a signing key matching the kid is found, this will be cached and the next time this kid is requested the signing key will be served from the cache.
 #Default is true.
 OPENID_JWKS_URL_CACHE_ENABLED=
 OPENID_JWKS_URL_CACHE_TIME= # 600000 ms eq to 10 minutes leave empty to disable caching
 #Set to true to trigger token exchange flow to acquire access token for the userinfo endpoint.
 OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=
 OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE="user.read" # example for Scope Needed for Microsoft Graph API
 # Set to true to use the OpenID Connect end session endpoint for logout
 OPENID_USE_END_SESSION_ENDPOINT=
 # URL to redirect to after OpenID logout (defaults to ${DOMAIN_CLIENT}/login)
 OPENID_POST_LOGOUT_REDIRECT_URI=
 # Maximum logout URL length before using logout_hint instead of id_token_hint (default: 2000)
 OPENID_MAX_LOGOUT_URL_LENGTH=
 #========================#
 # SharePoint Integration #
 #========================#
 # Requires Entra ID (OpenID) authentication to be configured
 # Enable SharePoint file picker in chat and agent panels
 # ENABLE_SHAREPOINT_FILEPICKER=true
 # SharePoint tenant base URL (e.g., https://yourtenant.sharepoint.com)
 # SHAREPOINT_BASE_URL=https://yourtenant.sharepoint.com
 # Microsoft Graph API And SharePoint scopes for file picker
 # SHAREPOINT_PICKER_SHAREPOINT_SCOPE==https://yourtenant.sharepoint.com/AllSites.Read
 # SHAREPOINT_PICKER_GRAPH_SCOPE=Files.Read.All
 #========================#
 # SAML
 # Note: If OpenID is enabled, SAML authentication will be automatically disabled.
 SAML_ENTRY_POINT=
 SAML_ISSUER=
 SAML_CERT=
 SAML_CALLBACK_URL=/oauth/saml/callback
 SAML_SESSION_SECRET=
 # Attribute mappings (optional)
 SAML_EMAIL_CLAIM=
 SAML_USERNAME_CLAIM=
 SAML_GIVEN_NAME_CLAIM=
 SAML_FAMILY_NAME_CLAIM=
 SAML_PICTURE_CLAIM=
 SAML_NAME_CLAIM=
 # Logint buttion settings (optional)
 SAML_BUTTON_LABEL=
 SAML_IMAGE_URL=
 # Whether the SAML Response should be signed.
 # - If "true", the entire `SAML Response` will be signed.
 # - If "false" or unset, only the `SAML Assertion` will be signed (default behavior).
 # SAML_USE_AUTHN_RESPONSE_SIGNED=
 #===============================================#
 # Microsoft Graph API / Entra ID Integration  #
 #===============================================#
 # Enable Entra ID people search integration in permissions/sharing system
 # When enabled, the people picker will search both local database and Entra ID
 USE_ENTRA_ID_FOR_PEOPLE_SEARCH=false
 # When enabled, entra id groups owners will be considered as members of the group
 ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS=false
 # Microsoft Graph API scopes needed for people/group search
 # Default scopes provide access to user profiles and group memberships
 OPENID_GRAPH_SCOPES=User.Read,People.Read,GroupMember.Read.All
 # LDAP
 LDAP_URL=
 LDAP_BIND_DN=
 LDAP_BIND_CREDENTIALS=
 LDAP_USER_SEARCH_BASE=
 #LDAP_SEARCH_FILTER="mail="
 LDAP_CA_CERT_PATH=
 # LDAP_TLS_REJECT_UNAUTHORIZED=
 # LDAP_STARTTLS=
 # LDAP_LOGIN_USES_USERNAME=true
 # LDAP_ID=
 # LDAP_USERNAME=
 # LDAP_EMAIL=
 # LDAP_FULL_NAME=
 #========================#
 # Email Password Reset   #
 #========================#
 EMAIL_SERVICE=
 EMAIL_HOST=
 EMAIL_PORT=25
 EMAIL_ENCRYPTION=
 EMAIL_ENCRYPTION_HOSTNAME=
 EMAIL_ALLOW_SELFSIGNED=
 # Leave both empty for SMTP servers that do not require authentication
 EMAIL_USERNAME=
 EMAIL_PASSWORD=
 EMAIL_FROM_NAME=
 EMAIL_FROM=noreply@librechat.ai
 #========================#
 #      Mailgun API       #
 #========================#
 # MAILGUN_API_KEY=your-mailgun-api-key
 # MAILGUN_DOMAIN=mg.yourdomain.com
 # EMAIL_FROM=noreply@yourdomain.com
 # EMAIL_FROM_NAME="LibreChat"
 # # Optional: For EU region
 # MAILGUN_HOST=https://api.eu.mailgun.net
 #========================#
 # Firebase CDN           #
 #========================#
 FIREBASE_API_KEY=
 FIREBASE_AUTH_DOMAIN=
 FIREBASE_PROJECT_ID=
 FIREBASE_STORAGE_BUCKET=
 FIREBASE_MESSAGING_SENDER_ID=
 FIREBASE_APP_ID=
 #========================#
 # S3 AWS Bucket          #
 #========================#
 AWS_ENDPOINT_URL=
 AWS_ACCESS_KEY_ID=
 AWS_SECRET_ACCESS_KEY=
 AWS_REGION=
 AWS_BUCKET_NAME=
 # Required for path-style S3-compatible providers (MinIO, Hetzner, Backblaze B2, etc.)
 # that don't support virtual-hosted-style URLs (bucket.endpoint). Not needed for AWS S3.
 # AWS_FORCE_PATH_STYLE=false
 #========================#
 # Azure Blob Storage     #
 #========================#
 AZURE_STORAGE_CONNECTION_STRING=
 AZURE_STORAGE_PUBLIC_ACCESS=false
 AZURE_CONTAINER_NAME=files
 #========================#
 # Shared Links           #
 #========================#
 ALLOW_SHARED_LINKS=true
 # Allows unauthenticated access to shared links. Defaults to false (auth required) if not set.
 ALLOW_SHARED_LINKS_PUBLIC=false
 #==============================#
 # Static File Cache Control    #
 #==============================#
 # Leave commented out to use defaults: 1 day (86400 seconds) for s-maxage and 2 days (172800 seconds) for max-age
 # NODE_ENV must be set to production for these to take effect
 # STATIC_CACHE_MAX_AGE=172800
 # STATIC_CACHE_S_MAX_AGE=86400
 # If you have another service in front of your LibreChat doing compression, disable express based compression here
 # DISABLE_COMPRESSION=true
 # If you have gzipped version of uploaded image images in the same folder, this will enable gzip scan and serving of these images
 # Note: The images folder will be scanned on startup and a ma kept in memory. Be careful for large number of images.
 # ENABLE_IMAGE_OUTPUT_GZIP_SCAN=true
 #===================================================#
 #                        UI                         #
 #===================================================#
 APP_TITLE=LibreChat
 # CUSTOM_FOOTER="My custom footer"
 HELP_AND_FAQ_URL=https://librechat.ai
 # SHOW_BIRTHDAY_ICON=true
 # Google tag manager id
 #ANALYTICS_GTM_ID=user provided google tag manager id
 # limit conversation file imports to a certain number of bytes in size to avoid the container
 # maxing out memory limitations by unremarking this line and supplying a file size in bytes
 # such as the below example of 250 mib
 # CONVERSATION_IMPORT_MAX_FILE_SIZE_BYTES=262144000
 #===============#
 # REDIS Options #
 #===============#
 # Enable Redis for caching and session storage
 # USE_REDIS=true
 # Enable Redis for resumable LLM streams (defaults to USE_REDIS value if not set)
 # Set to false to use in-memory storage for streams while keeping Redis for other caches
 # USE_REDIS_STREAMS=true
 # Single Redis instance
 # REDIS_URI=redis://127.0.0.1:6379
 # Redis cluster (multiple nodes)
 # REDIS_URI=redis://127.0.0.1:7001,redis://127.0.0.1:7002,redis://127.0.0.1:7003
 # Redis with TLS/SSL encryption and CA certificate
 # REDIS_URI=rediss://127.0.0.1:6380
 # REDIS_CA=/path/to/ca-cert.pem
 # Elasticache may need to use an alternate dnsLookup for TLS connections.  see "Special Note: Aws Elasticache Clusters with TLS" on this webpage: https://www.npmjs.com/package/ioredis
 # Enable alternative dnsLookup for redis
 # REDIS_USE_ALTERNATIVE_DNS_LOOKUP=true
 # Redis authentication (if required)
 # REDIS_USERNAME=your_redis_username
 # REDIS_PASSWORD=your_redis_password
 # Redis key prefix configuration
 # Use environment variable name for dynamic prefix (recommended for cloud deployments)
 # REDIS_KEY_PREFIX_VAR=K_REVISION
 # Or use static prefix directly
 # REDIS_KEY_PREFIX=librechat
 # Redis connection limits
 # REDIS_MAX_LISTENERS=40
 # Redis ping interval in seconds (0 = disabled, >0 = enabled)
 # When set to a positive integer, Redis clients will ping the server at this interval to keep connections alive
 # When unset or 0, no pinging is performed (recommended for most use cases)
 # REDIS_PING_INTERVAL=300
 # Force specific cache namespaces to use in-memory storage even when Redis is enabled
 # Comma-separated list of CacheKeys
 # Defaults to CONFIG_STORE,APP_CONFIG so YAML-derived config stays per-container (safe for blue/green deployments)
 # Set to empty string to force all namespaces through Redis: FORCED_IN_MEMORY_CACHE_NAMESPACES=
 # FORCED_IN_MEMORY_CACHE_NAMESPACES=CONFIG_STORE,APP_CONFIG
 # Leader Election Configuration (for multi-instance deployments with Redis)
 # Duration in seconds that the leader lease is valid before it expires (default: 25)
 # LEADER_LEASE_DURATION=25
 # Interval in seconds at which the leader renews its lease (default: 10)
 # LEADER_RENEW_INTERVAL=10
 # Maximum number of retry attempts when renewing the lease fails (default: 3)
 # LEADER_RENEW_ATTEMPTS=3
 # Delay in seconds between retry attempts when renewing the lease (default: 0.5)
 # LEADER_RENEW_RETRY_DELAY=0.5
 #==================================================#
 #                      Others                      #
 #==================================================#
 #   You should leave the following commented out   #
 # NODE_ENV=
 # E2E_USER_EMAIL=
 # E2E_USER_PASSWORD=
 #=====================================================#
 #                  Cache Headers                      #
 #=====================================================#
 #   Headers that control caching of the index.html    #
 #   Default configuration prevents caching to ensure  #
 #   users always get the latest version. Customize    #
 #   only if you understand caching implications.      #
 # INDEX_CACHE_CONTROL=no-cache, no-store, must-revalidate
 # INDEX_PRAGMA=no-cache
 # INDEX_EXPIRES=0
 # no-cache: Forces validation with server before using cached version
 # no-store: Prevents storing the response entirely
 # must-revalidate: Prevents using stale content when offline
 #=====================================================#
 #                  OpenWeather                        #
 #=====================================================#
 OPENWEATHER_API_KEY=
 #====================================#
 # LibreChat Code Interpreter API     #
 #====================================#
 # https://code.librechat.ai
 # LIBRECHAT_CODE_API_KEY=your-key
 #======================#
 # Web Search           #
 #======================#
 # Note: All of the following variable names can be customized.
 # Omit values to allow user to provide them.
 # For more information on configuration values, see:
 # https://librechat.ai/docs/features/web_search
 # Search Provider (Required)
 # SERPER_API_KEY=your_serper_api_key
 # Scraper (Required)
 # FIRECRAWL_API_KEY=your_firecrawl_api_key
 # Optional: Custom Firecrawl API URL
 # FIRECRAWL_API_URL=your_firecrawl_api_url
 # Reranker (Required)
 # JINA_API_KEY=your_jina_api_key
 # or
 # COHERE_API_KEY=your_cohere_api_key
 #======================#
 # MCP Configuration    #
 #======================#
 # Treat 401/403 responses as OAuth requirement when no oauth metadata found
 # MCP_OAUTH_ON_AUTH_ERROR=true
 # Timeout for OAuth detection requests in milliseconds
 # MCP_OAUTH_DETECTION_TIMEOUT=5000
 # Cache connection status checks for this many milliseconds to avoid expensive verification
 # MCP_CONNECTION_CHECK_TTL=60000
 # Skip code challenge method validation (e.g., for AWS Cognito that supports S256 but doesn't advertise it)
 # When set to true, forces S256 code challenge even if not advertised in .well-known/openid-configuration
 # MCP_SKIP_CODE_CHALLENGE_CHECK=false
 # Circuit breaker: max connect/disconnect cycles before tripping (per server)
 # MCP_CB_MAX_CYCLES=7
 # Circuit breaker: sliding window (ms) for counting cycles
 # MCP_CB_CYCLE_WINDOW_MS=45000
 # Circuit breaker: cooldown (ms) after the cycle breaker trips
 # MCP_CB_CYCLE_COOLDOWN_MS=15000
 # Circuit breaker: max consecutive failed connection rounds before backoff
 # MCP_CB_MAX_FAILED_ROUNDS=3
 # Circuit breaker: sliding window (ms) for counting failed rounds
 # MCP_CB_FAILED_WINDOW_MS=120000
 # Circuit breaker: base backoff (ms) after failed round threshold is reached
 # MCP_CB_BASE_BACKOFF_MS=30000
 # Circuit breaker: max backoff cap (ms) for exponential backoff
 # MCP_CB_MAX_BACKOFF_MS=300000
@@ -1,8 +0,0 @@
 # Auto-generated from pyproject.toml — do not edit manually
 ALFRED_VERSION=0.1.7
 PYTHON_VERSION=3.14.3
 IMAGE_NAME=alfred_media_organizer
 SERVICE_NAME=alfred
 LIBRECHAT_VERSION=v0.8.4
 RAG_VERSION=v0.7.3
 UV_VERSION=0.11.6
@@ -55,30 +55,13 @@ coverage.xml
 Thumbs.db
 # Secrets
-.env.secrets
+.env
 # Backup files
 *.backup
 *.bak
 env_backup/
 # Application data dir
 data/*
 # Application logs
 logs/*
 # Documentation folder
 docs/
 # .md files (project-level Markdown is brol-y; allow-list the ones we track)
 *.md
 !CHANGELOG.md
 !/README.md
 !specs/
 !specs/**/*.md
 # Private dev docs (separate git repo inside; see .claude/CLAUDE.md)
 /.claude/
 #
@@ -0,0 +1,261 @@
 # Contributing to Alfred
 ## Settings Management System
 Alfred uses a **declarative, schema-based configuration system** that ensures type safety, validation, and maintainability.
 ### Architecture Overview
 ```
 settings.toml          # Schema definitions (single source of truth)
    ↓
 settings_schema.py     # Parser & validation
    ↓
 settings_bootstrap.py  # Generation & resolution
    ↓
 .env                   # Runtime configuration
 .env.make              # Build variables for Makefile
    ↓
 settings.py            # Pydantic Settings (runtime validation)
 ```
 ### Key Files
 - **`settings.toml`** — Declarative schema for all settings
 - **`alfred/settings_schema.py`** — Schema parser and validation logic
 - **`alfred/settings_bootstrap.py`** — Bootstrap logic (generates `.env` and `.env.make`)
 - **`alfred/settings.py`** — Pydantic Settings class (runtime)
 - **`.env`** — Generated configuration file (gitignored)
 - **`.env.make`** — Build variables for Makefile (gitignored)
 ### Setting Sources
 Settings can come from different sources:
 | Source | Description | Example |
 |--------|-------------|---------|
 | `toml` | From `pyproject.toml` | Version numbers, build config |
 | `env` | From `.env` file | User-provided values, API keys |
 | `generated` | Auto-generated secrets | JWT secrets, passwords |
 | `computed` | Calculated from other settings | Database URIs |
 ### How to Add a New Setting
 #### 1. Define in `settings.toml`
 ```toml
 [tool.alfred.settings_schema.MY_NEW_SETTING]
 type = "string"                    # string, integer, float, boolean, secret, computed
 source = "env"                     # env, toml, generated, computed
 default = "default_value"          # Optional: default value
 description = "Description here"   # Required: clear description
 category = "app"                   # app, api, database, security, build
 required = true                    # Optional: default is true
 validator = "range:1:100"          # Optional: validation rule
 export_to_env_make = false         # Optional: export to .env.make for Makefile
 ```
 #### 2. Regenerate Configuration
 ```bash
 make bootstrap
 ```
 This will:
 - Read the schema from `settings.toml`
 - Generate/update `.env` with the new setting
 - Generate/update `.env.make` if `export_to_env_make = true`
 - Preserve existing secrets
 #### 3. Validate
 ```bash
 make validate
 ```
 This ensures all settings are valid according to the schema.
 #### 4. Use in Code
 The setting is automatically available in `settings.py`:
 ```python
 from alfred.settings import settings
 print(settings.my_new_setting)
 ```
 ### Setting Types
 #### String Setting
 ```toml
 [tool.alfred.settings_schema.API_URL]
 type = "string"
 source = "env"
 default = "https://api.example.com"
 description = "API base URL"
 category = "api"
 ```
 #### Integer Setting with Validation
 ```toml
 [tool.alfred.settings_schema.MAX_RETRIES]
 type = "integer"
 source = "env"
 default = 3
 description = "Maximum retry attempts"
 category = "app"
 validator = "range:1:10"
 ```
 #### Secret (Auto-generated)
 ```toml
 [tool.alfred.settings_schema.API_SECRET]
 type = "secret"
 source = "generated"
 secret_rule = "32:b64"  # 32 bytes, base64 encoded
 description = "API secret key"
 category = "security"
 ```
 Secret rules:
 - `"32:b64"` — 32 bytes, URL-safe base64
 - `"16:hex"` — 16 bytes, hexadecimal
 #### Computed Setting
 ```toml
 [tool.alfred.settings_schema.DATABASE_URL]
 type = "computed"
 source = "computed"
 compute_from = ["DB_HOST", "DB_PORT", "DB_NAME"]
 compute_template = "postgresql://{DB_HOST}:{DB_PORT}/{DB_NAME}"
 description = "Database connection URL"
 category = "database"
 ```
 #### From TOML (Build Variables)
 ```toml
 [tool.alfred.settings_schema.APP_VERSION]
 type = "string"
 source = "toml"
 toml_path = "tool.poetry.version"
 description = "Application version"
 category = "build"
 export_to_env_make = true  # Available in Makefile
 ```
 ### Validators
 Available validators:
 - **`range:min:max`** — Numeric range validation
  ```toml
  validator = "range:0.0:2.0"  # For floats
  validator = "range:1:100"    # For integers
  ```
 ### Categories
 Organize settings by category:
 - **`app`** — Application settings
 - **`api`** — API keys and external services
 - **`database`** — Database configuration
 - **`security`** — Secrets and security keys
 - **`build`** — Build-time configuration
 ### Best Practices
 1. **Always add a description** — Make it clear what the setting does
 2. **Use appropriate types** — Don't use strings for numbers
 3. **Add validation** — Use validators for numeric ranges
 4. **Categorize properly** — Helps with organization
 5. **Use computed settings** — For values derived from others (e.g., URIs)
 6. **Mark secrets as generated** — Let the system handle secret generation
 7. **Export build vars** — Set `export_to_env_make = true` for Makefile variables
 ### Workflow Example
 ```bash
 # 1. Edit settings.toml
 vim settings.toml
 # 2. Regenerate configuration
 make bootstrap
 # 3. Validate
 make validate
 # 4. Test
 python -c "from alfred.settings import settings; print(settings.my_new_setting)"
 # 5. Commit (settings.toml only, not .env)
 git add settings.toml
 git commit -m "Add MY_NEW_SETTING"
 ```
 ### Commands
 ```bash
 make bootstrap  # Generate .env and .env.make from schema
 make validate   # Validate all settings against schema
 make help       # Show all available commands
 ```
 ### Troubleshooting
 **Setting not found in schema:**
 ```
 KeyError: Missing [tool.alfred.settings_schema] section
 ```
 → Check that `settings.toml` exists and has the correct structure
 **Validation error:**
 ```
 ValueError: MY_SETTING must be between 1 and 100, got 150
 ```
 → Check the validator in `settings.toml` and adjust the value in `.env`
 **Secret not preserved:**
 → Secrets are automatically preserved during `make bootstrap`. If lost, they were never in `.env` (check `.env` exists before running bootstrap)
 ### Testing
 When adding a new setting, consider adding tests:
 ```python
 # tests/test_settings_schema.py
 def test_my_new_setting(self, create_schema_file):
    """Test MY_NEW_SETTING definition."""
    schema_toml = """
 [tool.alfred.settings_schema.MY_NEW_SETTING]
 type = "string"
 source = "env"
 default = "test"
 """
    base_dir = create_schema_file(schema_toml)
    schema = load_schema(base_dir)
    definition = schema.get("MY_NEW_SETTING")
    assert definition.default == "test"
 ```
 ### Migration from Old System
 If you're migrating from the old system:
 1. Settings are now in `settings.toml` instead of scattered across files
 2. No more `.env.example` — schema is the source of truth
 3. Secrets are auto-generated and preserved
 4. Validation happens at bootstrap time, not just runtime
 ---
 ## Questions?
 Open an issue or check the existing settings in `settings.toml` for examples.
@@ -2,49 +2,68 @@
 # check=skip=InvalidDefaultArgInFrom
 ARG PYTHON_VERSION
-ARG UV_VERSION
+ARG PYTHON_VERSION_SHORT
-
+ARG RUNNER
 # Stage 0: uv binary (workaround — --from doesn't support ARG expansion)
 FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv-bin
 # ===========================================
 # Stage 1: Builder
 # ===========================================
 FROM python:${PYTHON_VERSION}-slim-bookworm AS builder
 # Re-declare ARGs after FROM to make them available in this stage
 ARG RUNNER
 # STFU - No need - Write logs asap
 ENV DEBIAN_FRONTEND=noninteractive \
    PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONUNBUFFERED=1 \
+    PYTHONUNBUFFERED=1
    UV_PROJECT_ENVIRONMENT=/venv
-# Install build dependencies
+# Install build dependencies (needs root)
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+RUN apt-get update && apt-get install -y --no-install-recommends \
-    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    build-essential \
-    apt-get update \
+    && rm -rf /var/lib/apt/lists/*
    && apt-get install -y --no-install-recommends build-essential
-# Install uv globally
+# Install runner globally (needs root) - Save cache for future
-COPY --from=uv-bin /uv /usr/local/bin/uv
+RUN --mount=type=cache,target=/root/.cache/pip \
    pip install $RUNNER
-WORKDIR /tmp
+# Set working directory for dependency installation
 WORKDIR /app
-COPY pyproject.toml uv.lock Makefile ./
+# Copy dependency files
 COPY pyproject.toml poetry.lock* uv.lock* Makefile ./
-# Install dependencies into /venv
+# Install dependencies as root (to avoid permission issues with system packages)
-RUN --mount=type=cache,target=/root/.cache/uv uv sync
+RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=cache,target=/root/.cache/pypoetry \
    --mount=type=cache,target=/root/.cache/uv \
    if [ "$RUNNER" = "poetry" ]; then \
        poetry config virtualenvs.create false && \
        poetry install --only main --no-root; \
    elif [ "$RUNNER" = "uv" ]; then \
        uv pip install --system -r pyproject.toml; \
    fi
 COPY alfred/ ./alfred/
 COPY scripts/ ./scripts/
 COPY .env.example ./
 COPY settings.toml ./
 # ===========================================
 # Stage 2: Testing
 # ===========================================
 FROM builder AS test
-RUN --mount=type=cache,target=/root/.cache/uv uv sync --group dev
+ARG RUNNER
 RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=cache,target=/root/.cache/pypoetry \
    --mount=type=cache,target=/root/.cache/uv \
    if [ "$RUNNER" = "poetry" ]; then \
        poetry install --no-root; \
    elif [ "$RUNNER" = "uv" ]; then \
        uv pip install --system -e .[dev]; \
    fi
 COPY alfred/ ./alfred
 COPY scripts ./scripts
 COPY tests/  ./tests
 # ===========================================
@@ -52,39 +71,52 @@ COPY tests/  ./tests
 # ===========================================
 FROM python:${PYTHON_VERSION}-slim-bookworm AS runtime
-ENV PYTHONDONTWRITEBYTECODE=1 \
+ARG PYTHON_VERSION_SHORT
    PYTHONUNBUFFERED=1 \
    PYTHONPATH=/home/appuser \
    PATH="/venv/bin:$PATH"
-# Install runtime dependencies
+# TODO: A-t-on encore besoin de toutes les clés  ?
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+ENV LLM_PROVIDER=deepseek \
-    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    MEMORY_STORAGE_DIR=/data/memory \
-    apt-get update \
+    PYTHONDONTWRITEBYTECODE=1 \
-    && apt-get install -y --no-install-recommends ca-certificates
+    PYTHONPATH=/home/appuser \
    PYTHONUNBUFFERED=1
 # Install runtime dependencies (needs root)
 RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/* \
    && apt-get clean
 # Create non-root user
 RUN useradd -m -u 1000 -s /bin/bash appuser
-# Create data directories
+# Create data directories (needs root for /data)
 RUN mkdir -p /data /logs \
    && chown -R appuser:appuser /data /logs
 # Switch to non-root user
 USER appuser
 # Set working directory (owned by appuser)
 WORKDIR /home/appuser
-# Copy venv from builder stage
+# Copy Python packages from builder stage
-COPY --from=builder /venv /venv
+COPY --from=builder /usr/local/lib/python${PYTHON_VERSION_SHORT}/site-packages /usr/local/lib/python${PYTHON_VERSION_SHORT}/site-packages
 COPY --from=builder /usr/local/bin /usr/local/bin
-# Copy application code
+# Copy application code (already owned by appuser)
 COPY --chown=appuser:appuser alfred/ ./alfred
 COPY --chown=appuser:appuser scripts/ ./scripts
 COPY --chown=appuser:appuser .env.example ./
 COPY --chown=appuser:appuser pyproject.toml ./
 COPY --chown=appuser:appuser settings.toml ./
 # Create volumes for persistent data
 VOLUME ["/data", "/logs"]
 # Expose port
 EXPOSE 8000
 # Health check
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import requests; requests.get('http://localhost:8000/health', timeout=5).raise_for_status()" || exit 1
@@ -1,7 +1,6 @@
 .DEFAULT_GOAL := help
 # --- Load Config from pyproject.toml ---
 export
 -include .env.make
 # --- Profiles management ---
@@ -10,29 +9,36 @@ p ?= full
 PROFILES_PARAM	:= COMPOSE_PROFILES=$(p)
 # --- Commands ---
-DOCKER_COMPOSE	:= docker compose \
+DOCKER_COMPOSE	:= docker compose
-					--env-file .env.alfred \
+DOCKER_BUILD	:= docker build --no-cache \
 					--env-file .env.secrets \
 					--env-file .env.make
 DOCKER_BUILD	:= DOCKER_BUILDKIT=1 docker build \
 					--build-arg PYTHON_VERSION=$(PYTHON_VERSION) \
-					--build-arg UV_VERSION=$(UV_VERSION)
+					--build-arg PYTHON_VERSION_SHORT=$(PYTHON_VERSION_SHORT) \
 					--build-arg RUNNER=$(RUNNER)
 # --- Phony ---
-.PHONY: bootstrap up down restart logs ps shell build build-test install \
+.PHONY: .env bootstrap validate up down restart logs ps shell build build-test install \
 	update install-hooks test coverage lint format clean major minor patch help
 # --- Setup ---
-.env.alfred .env.librechat .env.secrets .env.make:
+.env:
 	@echo "Initializing environment..."
-	@uv run python scripts/bootstrap.py \
+	@python scripts/bootstrap.py \
 		&& echo "✓ Environment ready" \
 		|| (echo "✗ Environment setup failed" && exit 1)
-bootstrap: .env.alfred .env.librechat .env.secrets .env.make
+# .env.make is automatically generated by bootstrap.py when .env is created
 .env.make: .env
 bootstrap: .env
 validate:
 	@echo "Validating settings..."
 	@python scripts/validate_settings.py \
 		&& echo "✓ Settings valid" \
 		|| (echo "✗ Settings validation failed" && exit 1)
 # --- Docker ---
-up: .env.alfred .env.secrets
+up: .env
 	@echo "Starting containers with profiles: [full]..."
 	@$(PROFILES_PARAM) $(DOCKER_COMPOSE) up -d --remove-orphans \
 		&& echo "✓ Containers started" \
@@ -77,45 +83,45 @@ build-test: .env.make
 # --- Dependencies ---
 install:
-	@echo "Installing dependencies with uv..."
+	@echo "Installing dependencies with $(RUNNER)..."
-	@uv install \
+	@$(RUNNER) install \
 		&& echo "✓ Dependencies installed" \
 		|| (echo "✗ Installation failed" && exit 1)
 install-hooks:
 	@echo "Installing pre-commit hooks..."
-	@uv run pre-commit install \
+	@$(RUNNER) run pre-commit install \
 		&& echo "✓ Hooks installed" \
 		|| (echo "✗ Hook installation failed" && exit 1)
 update:
-	@echo "Updating dependencies with uv..."
+	@echo "Updating dependencies with $(RUNNER)..."
-	@uv update \
+	@$(RUNNER) update \
 		&& echo "✓ Dependencies updated" \
 		|| (echo "✗ Update failed" && exit 1)
 # --- Quality ---
 test:
 	@echo "Running tests..."
-	@uv run pytest \
+	@$(RUNNER) run pytest \
 		&& echo "✓ Tests passed" \
 		|| (echo "✗ Tests failed" && exit 1)
 coverage:
 	@echo "Running tests with coverage..."
-	@uv run pytest --cov=. --cov-report=html --cov-report=term \
+	@$(RUNNER) run pytest --cov=. --cov-report=html --cov-report=term \
 		&& echo "✓ Coverage report generated" \
 		|| (echo "✗ Coverage failed" && exit 1)
 lint:
 	@echo "Linting code..."
-	@uv run ruff check --fix . \
+	@$(RUNNER) run ruff check --fix . \
 		&& echo "✓ Linting complete" \
 		|| (echo "✗ Linting failed" && exit 1)
 format:
 	@echo "Formatting code..."
-	@uv run ruff format . && uv run ruff check --fix . \
+	@$(RUNNER) run ruff format . && $(RUNNER) run ruff check --fix . \
 		&& echo "✓ Code formatted" \
 		|| (echo "✗ Formatting failed" && exit 1)
@@ -128,7 +134,7 @@ clean:
 # --- Versioning ---
 major minor patch: _check-main
 	@echo "Bumping $@ version..."
-	@uv run bump-my-version bump $@ \
+	@$(RUNNER) run bump-my-version bump $@ \
 		&& echo "✓ Version bumped" \
 		|| (echo "✗ Version bump failed" && exit 1)
@@ -141,7 +147,8 @@ major minor patch: _check-main
 _ci-dump-config:
 	@echo "image_name=$(IMAGE_NAME)"
 	@echo "python_version=$(PYTHON_VERSION)"
-	@echo "uv_version=$(UV_VERSION)"
+	@echo "python_version_short=$(PYTHON_VERSION_SHORT)"
 	@echo "runner=$(RUNNER)"
 	@echo "service_name=$(SERVICE_NAME)"
 _ci-run-tests:build-test
@@ -164,10 +171,11 @@ help:
 	@echo "Usage: make [target] [p=profile1,profile2]"
 	@echo ""
 	@echo "Setup:"
-	@echo "  bootstrap   Generate .env.alfred, .env.librechat, .env.secrets and .env.make"
+	@echo "  bootstrap   Generate .env and .env.make from schema"
 	@echo "  validate    Validate settings against schema"
 	@echo ""
 	@echo "Docker:"
-	@echo "  up          Start containers (default profile: core)"
+	@echo "  up          Start containers (default profile: full)"
 	@echo "              Example: make up p=rag,meili"
 	@echo "  down        Stop all containers"
 	@echo "  restart     Restart containers (supports p=...)"
@@ -177,8 +185,7 @@ help:
 	@echo "  build       Build the production Docker image"
 	@echo ""
 	@echo "Dev & Quality:"
-	@echo "  setup       Bootstrap .env and security keys"
+	@echo "  install     Install dependencies via $(RUNNER)"
 	@echo "  install     Install dependencies via uv"
 	@echo "  test        Run pytest suite"
 	@echo "  coverage    Run tests and generate HTML report"
 	@echo "  lint/format Quality and style checks"
@@ -3,7 +3,7 @@
 An AI-powered agent for managing your local media library with natural language. Search, download, and organize movies and TV shows effortlessly through a conversational interface.
 [![Python 3.14](https://img.shields.io/badge/python-3.14-blue.svg)](https://www.python.org/downloads/)
-[![uv](https://img.shields.io/badge/dependency%20manager-uv-purple)](https://github.com/astral-sh/uv)
+[![Poetry](https://img.shields.io/badge/dependency%20manager-poetry-blue)](https://python-poetry.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
@@ -13,10 +13,9 @@ An AI-powered agent for managing your local media library with natural language.
 - 🔍 **Smart Search** — Find movies and TV shows via TMDB with rich metadata
 - 📥 **Torrent Integration** — Search and download via qBittorrent
 - 🧠 **Contextual Memory** — Remembers your preferences and conversation history
- 📁 **Auto-Organization** — Moves and renames media files, resolves destinations, handles subtitles
+- 📁 **Auto-Organization** — Keeps your media library tidy and well-structured
- 🎞️ **Subtitle Pipeline** — Identifies, matches, and places subtitle tracks automatically
+- 🌐 **OpenAI-Compatible API** — Works with any OpenAI-compatible client
- 🔄 **Workflow Engine** — YAML-defined multi-step workflows (e.g. `organize_media`)
+- 🖥️ **LibreChat Frontend** — Beautiful web UI included out of the box
 - 🌐 **OpenAI-Compatible API** — Works with any OpenAI-compatible client (LibreChat, OpenWebUI, etc.)
 - 🔒 **Secure by Default** — Auto-generated secrets and encrypted credentials
 ## 🏗️ Architecture
@@ -27,50 +26,33 @@ Built with **Domain-Driven Design (DDD)** principles for clean separation of con
 alfred/
 ├── agent/              # AI agent orchestration
 │   ├── llm/            # LLM clients (Ollama, DeepSeek)
-│   ├── tools/          # Tool implementations (api, filesystem, language)
+│   └── tools/          # Tool implementations
 │   └── workflows/      # YAML-defined multi-step workflows
 ├── application/        # Use cases & DTOs
-│   ├── movies/         # Movie search
+│   ├── movies/         # Movie search use cases
 │   ├── torrents/       # Torrent management
-│   └── filesystem/     # File operations (move, list, subtitles, seed links)
+│   └── filesystem/     # File operations
 ├── domain/             # Business logic & entities
 │   ├── media/          # Release parsing
 │   ├── movies/         # Movie entities
-│   ├── tv_shows/       # TV show entities & value objects
+│   ├── tv_shows/       # TV show entities
-│   ├── subtitles/      # Subtitle scanner, services, knowledge base
+│   └── subtitles/      # Subtitle entities
 │   └── shared/         # Common value objects (ImdbId, FilePath, FileSize)
 └── infrastructure/     # External services & persistence
-    ├── api/            # External API clients (TMDB, qBittorrent, Knaben)
+    ├── api/            # External API clients (TMDB, qBittorrent)
-    ├── filesystem/     # File manager (hard-link based, path-traversal safe)
+    ├── filesystem/     # File system operations
-    ├── persistence/    # Three-tier memory (LTM/STM/Episodic) + JSON repositories
+    └── persistence/    # Memory & repositories
    └── subtitle/       # Subtitle infrastructure
 ```
-### Key flows
+See [docs/architecture_diagram.md](docs/architecture_diagram.md) for detailed architectural diagrams.
 **Agent execution:** `agent.step(user_input)` → LLM call → if tool_calls, execute each via registry → loop until no tool calls or `max_tool_iterations` → return final response.
 **Media organization workflow:**
 1. `resolve_destination` — Determines target folder/filename from release name
 2. `move_media` — Hard-links file to library, deletes source
 3. `manage_subtitles` — Scans, classifies, and places subtitle tracks
 4. `create_seed_links` — Hard-links library file back to torrents/ for continued seeding
 **Memory tiers:**
 - **LTM** (`data/memory/ltm.json`) — Persisted config, media library, watchlist
 - **STM** — Conversation history (capped at `MAX_HISTORY_MESSAGES`)
 - **Episodic** — Transient search results, active downloads, recent errors
 ## 🚀 Quick Start
 ### Prerequisites
- **Python 3.14+**
+- **Python 3.14+** (required)
- **uv** (dependency manager)
+- **Poetry** (dependency manager)
 - **Docker & Docker Compose** (recommended for full stack)
 - **API Keys:**
  - TMDB API key ([get one here](https://www.themoviedb.org/settings/api))
-  - Optional: DeepSeek or other LLM provider keys
+  - Optional: DeepSeek, OpenAI, Anthropic, or other LLM provider keys
 ### Installation
@@ -82,15 +64,9 @@ cd alfred_media_organizer
 # Install dependencies
 make install
 # Install pre-commit hooks
 make install-hooks
 # Bootstrap environment (generates .env with secure secrets)
 make bootstrap
 # Validate your .env against the schema
 make validate
 # Edit .env with your API keys
 nano .env
 ```
@@ -118,95 +94,162 @@ The web interface will be available at **http://localhost:3080**
 ### Running Locally (Development)
 ```bash
-uv run uvicorn alfred.app:app --reload --port 8000
+# Install dependencies
 poetry install
 # Start the API server
 poetry run uvicorn alfred.app:app --reload --port 8000
 ```
 ## ⚙️ Configuration
-### Settings system
+### Environment Bootstrap
-`settings.toml` is the single source of truth. The schema flows:
+Alfred uses a smart bootstrap system that:
-```
+1. **Generates secure secrets** automatically (JWT tokens, database passwords, encryption keys)
-settings.toml → settings_schema.py → settings_bootstrap.py → .env + .env.make → settings.py
+2. **Syncs build variables** from `pyproject.toml` (versions, image names)
-```
+3. **Preserves existing secrets** when re-running (never overwrites your API keys)
-
+4. **Computes database URIs** automatically from individual components
 To add a setting: define it in `settings.toml`, run `make bootstrap`, then access via `settings.my_new_setting`.
 ```bash
 # First time setup
 make bootstrap
-# Validate existing .env against schema
+# Re-run after updating pyproject.toml (secrets are preserved)
 make validate
 # Re-run after settings.toml changes (existing secrets preserved)
 make bootstrap
 ```
-**Never commit `.env` or `.env.make`** — both are gitignored and auto-generated.
+### Configuration File (.env)
-### Key settings (.env)
+The `.env` file is generated from `.env.example` with secure defaults:
 ```bash
-# --- CORE ---
+# --- CORE SETTINGS ---
 HOST=0.0.0.0
 PORT=3080
 MAX_HISTORY_MESSAGES=10
 MAX_TOOL_ITERATIONS=10
-# --- LLM ---
+# --- LLM CONFIGURATION ---
-DEFAULT_LLM_PROVIDER=local     # local (Ollama) | deepseek
+# Providers: 'local' (Ollama), 'deepseek', 'openai', 'anthropic', 'google'
 DEFAULT_LLM_PROVIDER=local
 # Local LLM (Ollama - included in Docker stack)
 OLLAMA_BASE_URL=http://ollama:11434
 OLLAMA_MODEL=llama3.3:latest
 LLM_TEMPERATURE=0.2
-# --- API KEYS ---
+# --- API KEYS (fill only what you need) ---
-TMDB_API_KEY=your-tmdb-key     # Required for movie/show search
+TMDB_API_KEY=your-tmdb-key-here        # Required for movie search
-DEEPSEEK_API_KEY=              # Optional
+DEEPSEEK_API_KEY=                       # Optional
 OPENAI_API_KEY=                         # Optional
 ANTHROPIC_API_KEY=                      # Optional
-# --- SECURITY (auto-generated) ---
+# --- SECURITY (auto-generated, don't modify) ---
-JWT_SECRET=<auto>
+JWT_SECRET=<auto-generated>
-CREDS_KEY=<auto>
+JWT_REFRESH_SECRET=<auto-generated>
-MONGO_PASSWORD=<auto>
+CREDS_KEY=<auto-generated>
 CREDS_IV=<auto-generated>
 # --- DATABASES (auto-generated passwords) ---
 MONGO_PASSWORD=<auto-generated>
 POSTGRES_PASSWORD=<auto-generated>
 ```
 ### Security Keys
 Security keys are defined in `pyproject.toml` and generated automatically:
 ```toml
 [tool.alfred.security]
 jwt_secret = "32:b64"           # 32 bytes, base64 URL-safe
 jwt_refresh_secret = "32:b64"
 creds_key = "32:hex"            # 32 bytes, hexadecimal (AES-256)
 creds_iv = "16:hex"             # 16 bytes, hexadecimal (AES IV)
 mongo_password = "16:hex"
 postgres_password = "16:hex"
 ```
 **Formats:**
 - `b64` — Base64 URL-safe (for JWT tokens)
 - `hex` — Hexadecimal (for encryption keys, passwords)
 ## 🐳 Docker Services
 ### Service Architecture
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                     alfred-net (bridge)                      │
 ├─────────────────────────────────────────────────────────────┤
 │                                                              │
 │  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
 │  │  LibreChat   │───▶│    Alfred    │───▶│   MongoDB    │  │
 │  │   :3080      │    │   (core)     │    │   :27017     │  │
 │  └──────────────┘    └──────────────┘    └──────────────┘  │
 │         │                   │                               │
 │         │                   ▼                               │
 │         │            ┌──────────────┐                       │
 │         │            │    Ollama    │                       │
 │         │            │   (local)    │                       │
 │         │            └──────────────┘                       │
 │         │                                                   │
 │  ┌──────┴───────────────────────────────────────────────┐  │
 │  │              Optional Services (profiles)             │  │
 │  ├──────────────┬──────────────┬──────────────┬─────────┤  │
 │  │ Meilisearch  │  RAG API     │  VectorDB    │qBittor- │  │
 │  │   :7700      │   :8000      │   :5432      │  rent   │  │
 │  │  [meili]     │   [rag]      │   [rag]      │[qbit..] │  │
 │  └──────────────┴──────────────┴──────────────┴─────────┘  │
 │                                                              │
 └─────────────────────────────────────────────────────────────┘
 ```
 ### Docker Profiles
-| Profile | Extra services | Use case |
+| Profile | Services | Use Case |
-|---------|---------------|----------|
+|---------|----------|----------|
-| (default) | — | LibreChat + Alfred + MongoDB + Ollama |
+| (default) | LibreChat, Alfred, MongoDB, Ollama | Basic setup |
-| `meili` | Meilisearch | Fast full-text search |
+| `meili` | + Meilisearch | Fast search |
-| `rag` | RAG API + VectorDB (PostgreSQL) | Document retrieval |
+| `rag` | + RAG API, VectorDB | Document retrieval |
-| `qbittorrent` | qBittorrent | Torrent downloads |
+| `qbittorrent` | + qBittorrent | Torrent downloads |
-| `full` | All of the above | Complete setup |
+| `full` | All services | Complete setup |
 ```bash
-make up              # Start (default profile)
+# Start with specific profiles
 make up p=rag,meili
 make up p=full
 ```
 ### Docker Commands
 ```bash
 make up              # Start containers (default profile)
 make up p=full       # Start with all services
-make down            # Stop
+make down            # Stop all containers
-make restart         # Restart
+make restart         # Restart containers
 make logs            # Follow logs
-make ps              # Container status
+make ps              # Show container status
 make shell           # Open bash in Alfred container
 make build           # Build production image
 make build-test      # Build test image
 ```
 ## 🛠️ Available Tools
 The agent has access to these tools for interacting with your media library:
 | Tool | Description |
 |------|-------------|
 | `find_media_imdb_id` | Search for movies/TV shows on TMDB by title |
 | `find_torrent` | Search for torrents across multiple indexers |
-| `get_torrent_by_index` | Get detailed info about a specific result |
+| `get_torrent_by_index` | Get detailed info about a specific torrent result |
-| `add_torrent_by_index` | Download a torrent from search results |
+| `add_torrent_by_index` | Download a torrent by its index in search results |
 | `add_torrent_to_qbittorrent` | Add a torrent via magnet link directly |
-| `resolve_destination` | Compute the target library path for a release |
+| `set_path_for_folder` | Configure folder paths for media organization |
-| `move_media` | Hard-link a file to its library destination |
+| `list_folder` | List contents of a folder |
-| `manage_subtitles` | Scan, classify, and place subtitle tracks |
+| `set_language` | Set preferred language for searches |
 | `create_seed_links` | Prepare torrent folder so qBittorrent keeps seeding |
 | `learn` | Teach Alfred a new pattern (release group, naming convention) |
 | `set_path_for_folder` | Configure folder paths |
 | `list_folder` | List contents of a configured folder |
 | `set_language` | Set preferred language for the session |
 ## 💬 Usage Examples
@@ -223,12 +266,11 @@ Alfred: I found 3 torrents for Inception (2010):
 You: Download the first one
 Alfred: ✓ Added to qBittorrent! Download started.
        Saving to: /downloads/Movies/Inception (2010)/
-You: Organize the Breaking Bad S01 download
+You: What's downloading right now?
-Alfred: ✓ Resolved destination: /tv_shows/Breaking.Bad/Season 01/
+Alfred: You have 1 active download:
-        ✓ Moved 6 episode files
+        - Inception.2010.1080p.BluRay.x264 (45% complete, ETA: 12 min)
        ✓ Placed 6 subtitle tracks (fr, en)
        ✓ Seed links created in /torrents/
 ```
 ### Via API
@@ -237,147 +279,219 @@ Alfred: ✓ Resolved destination: /tv_shows/Breaking.Bad/Season 01/
 # Health check
 curl http://localhost:8000/health
-# Chat (OpenAI-compatible)
+# Chat with the agent (OpenAI-compatible)
 curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "alfred",
-    "messages": [{"role": "user", "content": "Find The Matrix 4K"}]
+    "messages": [
      {"role": "user", "content": "Find The Matrix 4K"}
    ]
  }'
-# List models
+# List available models
 curl http://localhost:8000/v1/models
-# View memory state
+# View memory state (debug)
 curl http://localhost:8000/memory/state
 # Clear session memory
 curl -X POST http://localhost:8000/memory/clear-session
 ```
-Alfred is compatible with any OpenAI-compatible client. Point it at `http://localhost:8000/v1`, model `alfred`.
+### Via OpenWebUI or Other Clients
 Alfred is compatible with any OpenAI-compatible client:
 1. Add as OpenAI-compatible endpoint: `http://localhost:8000/v1`
 2. Model name: `alfred`
 3. No API key required (or use any placeholder)
 ## 🧠 Memory System
-Alfred uses a three-tier memory system:
+Alfred uses a three-tier memory system for context management:
-| Tier | Storage | Contents | Lifetime |
+### Long-Term Memory (LTM)
-|------|---------|----------|----------|
+- **Persistent** — Saved to JSON files
-| **LTM** | JSON file (`data/memory/ltm.json`) | Config, library, watchlist, learned patterns | Permanent |
+- **Contents:** Configuration, user preferences, media library state
-| **STM** | RAM | Conversation history (capped) | Session |
+- **Survives:** Application restarts
-| **Episodic** | RAM | Search results, active downloads, errors | Short-lived |
+
 ### Short-Term Memory (STM)
 - **Session-based** — Stored in RAM
 - **Contents:** Conversation history, current workflow state
 - **Cleared:** On session end or restart
 ### Episodic Memory
 - **Transient** — Stored in RAM
 - **Contents:** Search results, active downloads, recent errors
 - **Cleared:** Frequently, after task completion
 ## 🧪 Development
 ### Project Setup
 ```bash
 # Install all dependencies (including dev)
 poetry install
 # Install pre-commit hooks
 make install-hooks
 # Run the development server
 poetry run uvicorn alfred.app:app --reload
 ```
 ### Running Tests
 ```bash
-# Run full suite (parallel)
+# Run all tests (parallel execution)
 make test
 # Run with coverage report
 make coverage
-# Run a single file
+# Run specific test file
-uv run pytest tests/test_agent.py -v
+poetry run pytest tests/test_agent.py -v
-# Run a single class
+# Run specific test
-uv run pytest tests/test_agent.py::TestAgentInit -v
+poetry run pytest tests/test_config_loader.py::TestBootstrapEnv -v
 # Skip slow tests
 uv run pytest -m "not slow"
 ```
 ### Test coverage
 The suite covers:
 - **Agent loop** — tool execution, history, max iterations, error handling
 - **Tool registry** — OpenAI schema format, parameter extraction
 - **Prompts** — system prompt building, tool inclusion
 - **Memory** — LTM/STM/Episodic operations, persistence
 - **Filesystem tools** — path traversal security, folder listing
 - **File manager** — hard-link, move, seed links (real filesystem, no mocks)
 - **Application use cases** — `resolve_destination`, `create_seed_links`, `list_folder`, `move_media`
 - **Domain** — TV show/movie entities, shared value objects (`ImdbId`, `FilePath`, `FileSize`), subtitle scanner
 - **Repositories** — JSON-backed movie, TV show, subtitle repos
 - **Bootstrap** — secret generation, idempotency, URI construction
 - **Workflows** — YAML loading, structure validation
 - **Configuration** — boundary validation for all settings
 ### Code Quality
 ```bash
-make lint        # Ruff check --fix
+# Lint and auto-fix
-make format      # Ruff format + check --fix
+make lint
 # Format code
 make format
 # Clean build artifacts
 make clean
 ```
 ### Adding a New Tool
-1. Implement the function in `alfred/agent/tools/`:
+1. **Create the tool function** in `alfred/agent/tools/`:
 ```python
 # alfred/agent/tools/api.py
 def my_new_tool(param: str) -> dict[str, Any]:
-    """Short description shown to the LLM to decide when to call this tool."""
+    """
    Short description of what this tool does.
    This will be shown to the LLM to help it decide when to use this tool.
    """
    memory = get_memory()
-    # ...
+    
-    return {"status": "ok", "data": result}
+    # Your implementation here
    result = do_something(param)
    return {
        "status": "success",
        "data": result
    }
 ```
-2. Register it in `alfred/agent/registry.py`:
+2. **Register in the registry** (`alfred/agent/registry.py`):
 ```python
 tool_functions = [
    # ... existing tools ...
-    api_tools.my_new_tool,
+    api_tools.my_new_tool,  # Add your tool here
 ]
 ```
-The registry auto-generates the JSON schema from the function signature and docstring.
+The tool will be automatically registered with its parameters extracted from the function signature.
 ### Adding a Workflow
 Create a YAML file in `alfred/agent/workflows/`:
 ```yaml
 name: my_workflow
 description: What this workflow does
 steps:
  - tool: resolve_destination
    description: Find where the file should go
  - tool: move_media
    description: Move the file
 ```
 Workflows are loaded automatically at startup.
 ### Version Management
 ```bash
-# Must be on main branch
+# Bump version (must be on main branch)
-make patch    # 0.1.7 → 0.1.8
+make patch    # 0.1.7 -> 0.1.8
-make minor    # 0.1.7 → 0.2.0
+make minor    # 0.1.7 -> 0.2.0
-make major    # 0.1.7 → 1.0.0
+make major    # 0.1.7 -> 1.0.0
 ```
 ## 📚 API Reference
 ### Endpoints
-| Method | Path | Description |
+#### `GET /health`
-|--------|------|-------------|
+Health check endpoint.
-| `GET` | `/health` | Health check |
+
-| `GET` | `/v1/models` | List models (OpenAI-compatible) |
+```json
-| `POST` | `/v1/chat/completions` | Chat (OpenAI-compatible, streaming supported) |
+{
-| `GET` | `/memory/state` | Full memory dump (debug) |
+  "status": "healthy",
-| `POST` | `/memory/clear-session` | Clear STM + Episodic |
+  "version": "0.1.7"
-| `GET` | `/memory/episodic/search-results` | Current search results |
+}
 ```
 #### `GET /v1/models`
 List available models (OpenAI-compatible).
 ```json
 {
  "object": "list",
  "data": [
    {
      "id": "alfred",
      "object": "model",
      "owned_by": "alfred"
    }
  ]
 }
 ```
 #### `POST /v1/chat/completions`
 Chat with the agent (OpenAI-compatible).
 **Request:**
 ```json
 {
  "model": "alfred",
  "messages": [
    {"role": "user", "content": "Find Inception"}
  ],
  "stream": false
 }
 ```
 **Response:**
 ```json
 {
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "alfred",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "I found Inception (2010)..."
    },
    "finish_reason": "stop"
  }]
 }
 ```
 #### `GET /memory/state`
 View full memory state (debug endpoint).
 #### `POST /memory/clear-session`
 Clear session memories (STM + Episodic).
 ## 🔧 Troubleshooting
 ### Agent doesn't respond
 1. Check API keys in `.env`
-2. Verify the LLM is running:
+2. Verify LLM provider is running:
   ```bash
   # For Ollama
   docker logs alfred-ollama
   # Check if model is pulled
   docker exec alfred-ollama ollama list
   ```
 3. Check Alfred logs: `docker logs alfred-core`
@@ -385,34 +499,76 @@ make major    # 0.1.7 → 1.0.0
 ### qBittorrent connection failed
 1. Verify qBittorrent is running: `docker ps | grep qbittorrent`
-2. Check credentials in `.env` (`QBITTORRENT_URL`, `QBITTORRENT_USERNAME`, `QBITTORRENT_PASSWORD`)
+2. Check Web UI is enabled in qBittorrent settings
 3. Verify credentials in `.env`:
   ```bash
   QBITTORRENT_URL=http://qbittorrent:16140
   QBITTORRENT_USERNAME=admin
   QBITTORRENT_PASSWORD=<check-your-env>
   ```
 ### Database connection issues
 1. Check MongoDB is healthy: `docker logs alfred-mongodb`
 2. Verify credentials match in `.env`
 3. Try restarting: `make restart`
 ### Memory not persisting
-1. Check `data/` directory is writable
+1. Check `data/` directory exists and is writable
 2. Verify volume mounts in `docker-compose.yaml`
 3. Check file permissions: `ls -la data/`
 ### Bootstrap fails
-```bash
+1. Ensure `.env.example` exists
-make validate    # Check what's wrong with .env
+2. Check `pyproject.toml` has required sections:
-make bootstrap   # Regenerate (preserves existing secrets)
+   ```toml
-```
+   [tool.alfred.settings]
   [tool.alfred.security]
   ```
 3. Run manually: `python scripts/bootstrap.py`
 ### Tests failing
-```bash
+1. Update dependencies: `poetry install`
-uv run pytest tests/test_failing.py -v --tb=long
+2. Check Python version: `python --version` (needs 3.14+)
-```
+3. Run specific failing test with verbose output:
   ```bash
   poetry run pytest tests/test_failing.py -v --tb=long
   ```
 ## 🤝 Contributing
-1. Fork the repository
+Contributions are welcome! Please follow these steps:
-2. Create a feature branch: `git checkout -b feat/my-feature`
+
-3. Make your changes + add tests
+1. **Fork** the repository
-4. Run `make test && make lint && make format`
+2. **Create** a feature branch: `git checkout -b feature/my-feature`
-5. Commit with [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `infra:`
+3. **Make** your changes
-6. Open a Pull Request
+4. **Run** tests: `make test`
 5. **Run** linting: `make lint && make format`
 6. **Commit**: `git commit -m "feat: add my feature"`
 7. **Push**: `git push origin feature/my-feature`
 8. **Create** a Pull Request
 ### Commit Convention
 We use [Conventional Commits](https://www.conventionalcommits.org/):
 - `feat:` New feature
 - `fix:` Bug fix
 - `docs:` Documentation
 - `refactor:` Code refactoring
 - `test:` Adding tests
 - `chore:` Maintenance
 ## 📖 Documentation
 - [Architecture Diagram](docs/architecture_diagram.md) — System architecture overview
 - [Class Diagram](docs/class_diagram.md) — Class structure and relationships
 - [Component Diagram](docs/component_diagram.md) — Component interactions
 - [Sequence Diagram](docs/sequence_diagram.md) — Sequence flows
 - [Flowchart](docs/flowchart.md) — System flowcharts
 ## 📄 License
@@ -420,13 +576,19 @@ MIT License — see [LICENSE](LICENSE) file for details.
 ## 🙏 Acknowledgments
- [LibreChat](https://github.com/danny-avila/LibreChat) — Chat interface
+- [LibreChat](https://github.com/danny-avila/LibreChat) — Beautiful chat interface
 - [Ollama](https://ollama.ai/) — Local LLM runtime
 - [DeepSeek](https://www.deepseek.com/) — LLM provider
- [TMDB](https://www.themoviedb.org/) — Movie & TV database
+- [TMDB](https://www.themoviedb.org/) — Movie database
 - [qBittorrent](https://www.qbittorrent.org/) — Torrent client
 - [FastAPI](https://fastapi.tiangolo.com/) — Web framework
- [uv](https://github.com/astral-sh/uv) — Fast Python package manager
+- [Pydantic](https://docs.pydantic.dev/) — Data validation
 ## 📬 Support
 - 📧 Email: francois.hodiaumont@gmail.com
 - 🐛 Issues: [GitHub Issues](https://github.com/francwa/alfred_media_organizer/issues)
 - 💬 Discussions: [GitHub Discussions](https://github.com/francwa/alfred_media_organizer/discussions)
 ---
@@ -3,16 +3,13 @@
 import json
 import logging
 from collections.abc import AsyncGenerator
 from pathlib import Path
 from typing import Any
-from alfred.infrastructure.metadata_TO_CHECK import MetadataStore
+from alfred.infrastructure.persistence import get_memory
 from alfred.infrastructure.persistence_TO_CHECK import get_memory
 from alfred.settings import settings
-from .prompt import PromptBuilder
+from .prompts import PromptBuilder
 from .registry import Tool, make_tools
 from .workflows_TO_CHECK import WorkflowLoader
 logger = logging.getLogger(__name__)
@@ -36,8 +33,8 @@ class Agent:
        self.settings = settings
        self.llm = llm
        self.tools: dict[str, Tool] = make_tools(settings)
-        self.workflow_loader = WorkflowLoader()
+        self.prompt_builder = PromptBuilder(self.tools)
-        self.prompt_builder = PromptBuilder(self.tools, self.workflow_loader)
+        self.settings = settings
        self.max_tool_iterations = max_tool_iterations
    def step(self, user_input: str) -> str:
@@ -142,7 +139,7 @@ class Agent:
        memory.save()
        return final_response
-    def _execute_tool_call(self, tool_call: dict[str, Any]) -> dict[str, Any]:  # noqa: PLR0911
+    def _execute_tool_call(self, tool_call: dict[str, Any]) -> dict[str, Any]:
        """
        Execute a single tool call.
@@ -171,163 +168,29 @@ class Agent:
                "available_tools": available,
            }
        # Defensive: reject calls to tools that are not currently in scope.
        visible = set(self.prompt_builder.visible_tool_names())
        if tool_name not in visible:
            return {
                "error": "tool_out_of_scope",
                "message": (
                    f"Tool '{tool_name}' is not available in the current "
                    "workflow scope. Call end_workflow first or start the "
                    "appropriate workflow."
                ),
                "available_tools": sorted(visible),
            }
        tool = self.tools[tool_name]
        memory = get_memory()
        # Cache lookup — for tools flagged cacheable, short-circuit on hit.
        cache_key_value = self._cache_key_for(tool, args)
        if cache_key_value is not None:
            cached = memory.stm.tool_results.get(tool_name, cache_key_value)
            if cached is not None:
                logger.info(f"Tool cache HIT: {tool_name}[{cache_key_value}]")
                self._post_tool_side_effects(tool_name, args, cached, from_cache=True)
                return {**cached, "_from_cache": True}
        # Execute tool
        try:
            result = tool.func(**args)
            return result
        except KeyboardInterrupt:
            # Don't catch KeyboardInterrupt - let it propagate
            raise
        except TypeError as e:
            # Bad arguments
            memory = get_memory()
            memory.episodic.add_error(tool_name, f"bad_args: {e}")
            return {"error": "bad_args", "message": str(e), "tool": tool_name}
        except Exception as e:
            # Other errors
            memory = get_memory()
            memory.episodic.add_error(tool_name, str(e))
            return {"error": "execution_failed", "message": str(e), "tool": tool_name}
        # Persist + side effects only on successful results.
        if isinstance(result, dict) and result.get("status") == "ok":
            if cache_key_value is not None:
                memory.stm.tool_results.put(tool_name, cache_key_value, result)
            self._post_tool_side_effects(tool_name, args, result, from_cache=False)
            memory.save()
        return result
    @staticmethod
    def _cache_key_for(tool: Tool, args: dict[str, Any]) -> str | None:
        """Return the cache key value for this call, or None if not cacheable."""
        if tool.cache_key is None:
            return None
        value = args.get(tool.cache_key)
        if value is None:
            return None
        return str(value)
    def _post_tool_side_effects(
        self,
        tool_name: str,
        args: dict[str, Any],
        result: dict[str, Any],
        *,
        from_cache: bool,
    ) -> None:
        """
        Tool-agnostic side effects applied after a successful run or cache hit.
        Today:
          - Update release_focus when a path-keyed inspector runs.
          - Persist inspector results into the release's `.alfred/metadata.yaml`.
          - Refresh episodic.last_search_results on find_torrent cache hits so
            get_torrent_by_index keeps pointing at the right list.
        """
        memory = get_memory()
        tool = self.tools.get(tool_name)
        # Release focus: any path-keyed inspector updates current_release_path.
        if tool is not None and tool.cache_key in {"source_path"}:
            path = args.get(tool.cache_key)
            if isinstance(path, str) and path:
                memory.stm.release_focus.focus(path)
        # Persist inspector results to .alfred/metadata.yaml (skip on cache
        # hit — the file is already up to date from the original run).
        if not from_cache:
            self._maybe_update_alfred(tool_name, args, result)
        # Episodic refresh when find_torrent's cache short-circuits the call.
        if from_cache and tool_name == "find_torrent":
            torrents = result.get("torrents") or []
            query = args.get("media_title") or ""
            memory.episodic.store_search_results(
                query=query, results=torrents, search_type="torrent"
            )
    def _maybe_update_alfred(
        self,
        tool_name: str,
        args: dict[str, Any],
        result: dict[str, Any],
    ) -> None:
        """
        Persist a successful inspector result into the release's
        `.alfred/metadata.yaml`. No-op when the release root can't be resolved.
        """
        if tool_name not in {"analyze_release", "probe_media", "find_media_imdb_id"}:
            return
        release_root = self._resolve_release_root(tool_name, args)
        if release_root is None:
            return
        try:
            store = MetadataStore(release_root)
            if tool_name == "analyze_release":
                store.update_parse(result)
            elif tool_name == "probe_media":
                store.update_probe(result)
            elif tool_name == "find_media_imdb_id":
                store.update_tmdb(result)
        except Exception as e:
            logger.warning(
                f"Failed to update .alfred for {tool_name} at {release_root}: {e}"
            )
    @staticmethod
    def _resolve_release_root(
        tool_name: str,
        args: dict[str, Any],
    ) -> Path | None:
        """
        Figure out which release folder owns this call.
        - analyze_release / probe_media: derived from source_path
          (folder kept as-is, file walked up to its parent).
        - find_media_imdb_id: follow the current release focus in STM.
        """
        if tool_name in {"analyze_release", "probe_media"}:
            raw = args.get("source_path")
            if not isinstance(raw, str) or not raw:
                return None
            path = Path(raw)
            return path if path.is_dir() else path.parent
        # find_media_imdb_id has no path arg — rely on release focus.
        focus = get_memory().stm.release_focus.current_release_path
        if not focus:
            return None
        path = Path(focus)
        return path if path.is_dir() else path.parent
    async def step_streaming(
        self, user_input: str, completion_id: str, created_ts: int, model: str
-    ) -> AsyncGenerator[dict[str, Any]]:
+    ) -> AsyncGenerator[dict[str, Any], None]:
        """
        Execute agent step with streaming support for LibreChat.
@@ -1,79 +0,0 @@
 """Expression loader — charge et merge les fichiers YAML d'expressions par user."""
 import random
 from pathlib import Path
 import yaml
 _USERS_DIR = Path(__file__).parent.parent / "knowledge" / "users"
 def _load_yaml(path: Path) -> dict:
    if not path.exists():
        return {}
    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
 def load_expressions(username: str | None) -> dict:
    """
    Charge common.yaml et le merge avec {username}.yaml.
    Retourne un dict avec :
      - nickname: str (surnom de l'user, ou username en fallback)
      - expressions: dict[situation -> list[str]]
    """
    common = _load_yaml(_USERS_DIR / "common.yaml")
    user_data = _load_yaml(_USERS_DIR / f"{username}.yaml") if username else {}
    # Merge expressions : common + user (les phrases user s'ajoutent)
    common_exprs: dict[str, list] = common.get("expressions", {})
    user_exprs: dict[str, list] = user_data.get("expressions", {})
    merged: dict[str, list] = {}
    all_situations = set(common_exprs) | set(user_exprs)
    for situation in all_situations:
        base = list(common_exprs.get(situation, []))
        extra = list(user_exprs.get(situation, []))
        merged[situation] = base + extra
    nickname = user_data.get("user", {}).get("nickname") or username or "mec"
    return {
        "nickname": nickname,
        "expressions": merged,
    }
 def pick(expressions: dict, situation: str, nickname: str | None = None) -> str:
    """
    Pioche une expression aléatoire pour une situation donnée.
    Résout {user} avec le nickname si fourni.
    Retourne une string vide si la situation n'existe pas.
    """
    options = expressions.get("expressions", {}).get(situation, [])
    if not options:
        return ""
    chosen = random.choice(options)
    if nickname:
        chosen = chosen.replace("{user}", nickname)
    return chosen
 def build_expressions_context(username: str | None) -> dict:
    """
    Point d'entrée principal.
    Retourne :
      - nickname: str
      - samples: dict[situation -> une phrase résolue]  — une seule par situation
    """
    data = load_expressions(username)
    nickname = data["nickname"]
    samples = {
        situation: pick(data, situation, nickname) for situation in data["expressions"]
    }
    return {
        "nickname": nickname,
        "samples": samples,
    }
@@ -6,8 +6,7 @@ from typing import Any
 import requests
 from requests.exceptions import HTTPError, RequestException, Timeout
-from alfred.settings import Settings
+from alfred.settings import Settings, settings
 from alfred.settings import settings as default_settings
 from .exceptions import LLMAPIError, LLMConfigurationError
@@ -37,7 +36,6 @@ class DeepSeekClient:
        Raises:
            LLMConfigurationError: If API key is missing
        """
        self.settings = settings or default_settings
        self.api_key = api_key or self.settings.deepseek_api_key
        self.base_url = base_url or self.settings.deepseek_base_url
        self.model = model or self.settings.deepseek_model
@@ -98,7 +96,7 @@ class DeepSeekClient:
        payload = {
            "model": self.model,
            "messages": messages,
-            "temperature": self.settings.llm_temperature,
+            "temperature": settings.llm_temperature,
        }
        # Add tools if provided
@@ -7,7 +7,6 @@ import requests
 from requests.exceptions import HTTPError, RequestException, Timeout
 from alfred.settings import Settings
 from alfred.settings import settings as default_settings
 from .exceptions import LLMAPIError, LLMConfigurationError
@@ -47,12 +46,11 @@ class OllamaClient:
        Raises:
            LLMConfigurationError: If configuration is invalid
        """
-        self.settings = settings or default_settings
+        self.base_url = base_url or settings.ollama_base_url
-        self.base_url = base_url or self.settings.ollama_base_url
+        self.model = model or settings.ollama_model
-        self.model = model or self.settings.ollama_model
+        self.timeout = timeout or settings.request_timeout
        self.timeout = timeout or self.settings.request_timeout
        self.temperature = (
-            temperature if temperature is not None else self.settings.llm_temperature
+            temperature if temperature is not None else settings.llm_temperature
        )
        if not self.base_url:
@@ -0,0 +1,101 @@
 # agent/parameters.py
 from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any
@dataclass
 class ParameterSchema:
    """Describes a required parameter for the agent."""
    key: str
    description: str
    why_needed: str  # Explanation for the AI
    type: str  # "string", "number", "object", etc.
    validator: Callable[[Any], bool] | None = None
    default: Any = None
    required: bool = True
 # Define all required parameters
 REQUIRED_PARAMETERS = [
    ParameterSchema(
        key="config",
        description="Configuration object containing all folder paths",
        why_needed=(
            "This contains the paths to all important folders:\n"
            "- download_folder: Where downloaded files arrive before being organized\n"
            "- tvshow_folder: Where TV show files are organized and stored\n"
            "- movie_folder: Where movie files are organized and stored\n"
            "- torrent_folder: Where torrent structures are saved for the torrent client"
        ),
        type="object",
        validator=lambda x: isinstance(x, dict),
        required=True,
        default={},
    ),
    ParameterSchema(
        key="tv_shows",
        description="List of TV shows the user is following",
        why_needed=(
            "This tracks which TV shows you're following. "
            "Each show includes: IMDB ID, title, number of seasons, and status (ongoing or ended)."
        ),
        type="array",
        validator=lambda x: isinstance(x, list),
        required=False,
        default=[],
    ),
 ]
 def get_parameter_schema(key: str) -> ParameterSchema | None:
    """Get schema for a specific parameter."""
    for param in REQUIRED_PARAMETERS:
        if param.key == key:
            return param
    return None
 def get_missing_required_parameters(memory_data: dict) -> list[ParameterSchema]:
    """Get list of required parameters that are missing or None."""
    missing = []
    for param in REQUIRED_PARAMETERS:
        if param.required:
            value = memory_data.get(param.key)
            if value is None:
                missing.append(param)
    return missing
 def format_parameters_for_prompt() -> str:
    """Format parameter descriptions for the AI system prompt."""
    lines = ["REQUIRED PARAMETERS:"]
    for param in REQUIRED_PARAMETERS:
        status = "REQUIRED" if param.required else "OPTIONAL"
        lines.append(f"\n- {param.key} ({status}):")
        lines.append(f"  Description: {param.description}")
        lines.append(f"  Why needed: {param.why_needed}")
        lines.append(f"  Type: {param.type}")
    return "\n".join(lines)
 def validate_parameter(key: str, value: Any) -> tuple[bool, str | None]:
    """
    Validate a parameter value against its schema.
    Returns:
        (is_valid, error_message)
    """
    schema = get_parameter_schema(key)
    if not schema:
        return True, None  # Unknown parameters are allowed
    if schema.validator:
        try:
            if not schema.validator(value):
                return False, f"Validation failed for {key}"
        except Exception as e:
            return False, f"Validation error for {key}: {str(e)}"
    return True, None
@@ -1,333 +0,0 @@
 """Prompt builder for the agent system."""
 import json
 from typing import Any
 from alfred.infrastructure.persistence_TO_CHECK import get_memory
 from alfred.infrastructure.persistence_TO_CHECK.memory import MemoryRegistry
 from .expressions import build_expressions_context
 from .registry import Tool
 from .workflows_TO_CHECK import WorkflowLoader
 # Tools that are always available, regardless of workflow scope.
 # Kept small on purpose — the noyau is what the agent uses to either
 # answer trivially or pivot into a workflow.
 CORE_TOOLS: tuple[str, ...] = (
    "set_language",
    "set_path_for_folder",
    "list_folder",
    "read_release_metadata",
    "query_library",
    "start_workflow",
    "end_workflow",
 )
 class PromptBuilder:
    """Builds system prompts for the agent with memory context."""
    def __init__(
        self,
        tools: dict[str, Tool],
        workflow_loader: WorkflowLoader | None = None,
    ):
        self.tools = tools
        self.workflow_loader = workflow_loader or WorkflowLoader()
        self._memory_registry = MemoryRegistry()
    def _active_workflow(self, memory) -> dict | None:
        """Return the YAML definition of the active workflow, or None."""
        current = memory.stm.workflow.current
        if current is None:
            return None
        return self.workflow_loader.get(current.get("name"))
    def visible_tool_names(self) -> list[str]:
        """
        Return the names of the tools currently in scope.
        - Idle (no workflow): core noyau only. The LLM enters a workflow
          via start_workflow to access more tools.
        - Workflow active: core noyau + the workflow's declared tools.
        """
        memory = get_memory()
        visible = set(CORE_TOOLS)
        workflow = self._active_workflow(memory)
        if workflow is not None:
            for name in workflow.get("tools", []):
                visible.add(name)
        # Only return tools that actually exist in the registry.
        return [name for name in self.tools if name in visible]
    def _format_identity(self, memory) -> str:
        """Build Alfred's identity and personality section."""
        username = memory.stm.get_entity("username")
        expr = build_expressions_context(username)
        nickname = expr["nickname"]
        samples = expr["samples"]
        # Format expressions as situational guidance for the LLM
        expr_lines = []
        situation_labels = {
            "greeting": "Salutation",
            "success": "Succès",
            "working": "En cours",
            "error": "Erreur",
            "unclear": "Demande floue",
            "warning": "Avertissement",
            "not_found": "Introuvable",
        }
        for situation, label in situation_labels.items():
            phrase = samples.get(situation, "")
            if phrase:
                expr_lines.append(f'  {label}: "{phrase}"')
        expressions_block = "\n".join(expr_lines)
        return f"""Tu t'appelles Alfred. Tu es un assistant d'organisation de médiathèque — direct, opérationnel, légèrement impertinent.
 PERSONNALITÉ:
 - Tu parles franglais : français avec des touches d'anglais quand ça colle mieux
 - Tu es sarcastique et n'as pas peur de te moquer si l'user fait une connerie
 - Tu envoies chier poliment (mais clairement) quand la demande est trop floue
 - Tu ne fais pas de blabla inutile. Si "ok c'est fait" suffit, c'est tout ce que tu dis
 - Tu peux jurer (putain, merde, con, ...) — c'est naturel, pas du remplissage
 - Jamais de "Great question!" ou de politesse creuse
 USER COURANT: {nickname}
 EXPRESSIONS À UTILISER (une par situation, naturellement intégrées dans ta réponse) :
 {expressions_block}"""
    def build_tools_spec(self) -> list[dict[str, Any]]:
        """Build the tool specification for the LLM API (scope-filtered)."""
        visible = set(self.visible_tool_names())
        tool_specs = []
        for tool in self.tools.values():
            if tool.name not in visible:
                continue
            spec = {
                "type": "function",
                "function": {
                    "name": tool.name,
                    "description": tool.description,
                    "parameters": tool.parameters,
                },
            }
            tool_specs.append(spec)
        return tool_specs
    def _format_tools_description(self) -> str:
        """Format the currently-visible tools with description + params."""
        visible = set(self.visible_tool_names())
        visible_tools = [t for t in self.tools.values() if t.name in visible]
        if not visible_tools:
            return ""
        return "\n".join(
            f"- {tool.name}: {tool.description}\n"
            f"  Parameters: {json.dumps(tool.parameters, ensure_ascii=False)}"
            for tool in visible_tools
        )
    def _format_workflow_scope(self, memory) -> str:
        """Describe the current workflow scope so the LLM has a plan."""
        workflow = self._active_workflow(memory)
        if workflow is None:
            available = self.workflow_loader.names()
            if not available:
                return ""
            lines = ["WORKFLOW SCOPE: idle (broad catalog narrowed to core noyau)."]
            lines.append(
                "  Call start_workflow(workflow_name, params) to enter a scope."
            )
            lines.append("  Available workflows:")
            for name in available:
                wf = self.workflow_loader.get(name) or {}
                desc = (wf.get("description") or "").strip().splitlines()
                summary = desc[0] if desc else ""
                lines.append(f"    - {name}: {summary}")
            return "\n".join(lines)
        current = memory.stm.workflow.current or {}
        lines = [
            f"WORKFLOW SCOPE: active — {current.get('name')} "
            f"(stage: {current.get('stage')})",
        ]
        params = current.get("params")
        if params:
            lines.append(f"  Params: {params}")
        wf_desc = (workflow.get("description") or "").strip()
        if wf_desc:
            lines.append(f"  Goal: {wf_desc}")
        steps = workflow.get("steps", [])
        if steps:
            lines.append("  Steps:")
            for step in steps:
                step_id = step.get("id", "?")
                step_tool = step.get("tool") or (
                    "ask_user" if step.get("ask_user") else "—"
                )
                lines.append(f"    - {step_id} ({step_tool})")
        lines.append("  Call end_workflow(reason) when done, cancelled, or off-topic.")
        return "\n".join(lines)
    def _format_episodic_context(self, memory) -> str:
        """Format episodic memory context for the prompt."""
        lines = []
        if memory.episodic.last_search_results:
            results = memory.episodic.last_search_results
            result_list = results.get("results", [])
            lines.append(
                f"\nLAST SEARCH: '{results.get('query')}' ({len(result_list)} results)"
            )
            # Show first 5 results
            for i, result in enumerate(result_list[:5]):
                name = result.get("name", "Unknown")
                lines.append(f"  {i + 1}. {name}")
            if len(result_list) > 5:
                lines.append(f"  ... and {len(result_list) - 5} more")
        if memory.episodic.pending_question:
            question = memory.episodic.pending_question
            lines.append(f"\nPENDING QUESTION: {question.get('question')}")
            lines.append(f"  Type: {question.get('type')}")
            if question.get("options"):
                lines.append(f"  Options: {len(question.get('options'))}")
        if memory.episodic.active_downloads:
            lines.append(f"\nACTIVE DOWNLOADS: {len(memory.episodic.active_downloads)}")
            for dl in memory.episodic.active_downloads[:3]:
                lines.append(f"  - {dl.get('name')}: {dl.get('progress', 0)}%")
        if memory.episodic.recent_errors:
            lines.append("\nRECENT ERRORS (up to 3):")
            for error in memory.episodic.recent_errors[-3:]:
                lines.append(
                    f"  - Action '{error.get('action')}' failed: {error.get('error')}"
                )
        # Unread events
        unread = [e for e in memory.episodic.background_events if not e.get("read")]
        if unread:
            lines.append(f"\nUNREAD EVENTS: {len(unread)}")
            for event in unread[:3]:
                lines.append(f"  - {event.get('type')}: {event.get('data')}")
        return "\n".join(lines)
    def _format_stm_context(self, memory) -> str:
        """Format short-term memory context for the prompt."""
        lines = []
        if memory.stm.current_workflow:
            workflow = memory.stm.current_workflow
            lines.append(
                f"CURRENT WORKFLOW: {workflow.get('name')} (stage: {workflow.get('stage')})"
            )
            if workflow.get("params"):
                lines.append(f"  Params: {workflow.get('params')}")
        if memory.stm.current_topic:
            lines.append(f"CURRENT TOPIC: {memory.stm.current_topic}")
        if memory.stm.extracted_entities:
            lines.append("EXTRACTED ENTITIES:")
            for key, value in memory.stm.extracted_entities.items():
                lines.append(f"  - {key}: {value}")
        if memory.stm.language:
            lines.append(f"CONVERSATION LANGUAGE: {memory.stm.language}")
        return "\n".join(lines)
    def _format_memory_schema(self) -> str:
        """Describe available memory components so the agent knows what to read/write and when."""
        schema = self._memory_registry.schema()
        tier_labels = {
            "ltm": "LONG-TERM (persisted)",
            "stm": "SHORT-TERM (session)",
            "episodic": "EPISODIC (volatile)",
        }
        lines = ["MEMORY COMPONENTS:"]
        for tier, components in schema.items():
            if not components:
                continue
            lines.append(f"\n  [{tier_labels.get(tier, tier.upper())}]")
            for c in components:
                access = c.get("access", "read")
                lines.append(f"  {c['name']} ({access}): {c['description']}")
                for field_name, field_desc in c.get("fields", {}).items():
                    lines.append(f"    · {field_name}: {field_desc}")
        return "\n".join(lines)
    def _format_config_context(self, memory) -> str:
        """Format configuration context."""
        lines = ["CURRENT CONFIGURATION:"]
        folders = {
            **memory.ltm.workspace.as_dict(),
            **memory.ltm.library_paths.to_dict(),
        }
        if folders:
            for key, value in folders.items():
                lines.append(f"  - {key}: {value}")
        else:
            lines.append("  (no configuration set)")
        return "\n".join(lines)
    def build_system_prompt(self) -> str:
        """Build the complete system prompt."""
        memory = get_memory()
        # Identity + personality
        identity = self._format_identity(memory)
        # Language instruction
        language_instruction = (
            "Si la langue de l'user est différente de la langue courante en STM, "
            "appelle `set_language` en premier avant de répondre."
        )
        # Configuration
        config_section = self._format_config_context(memory)
        # STM context
        stm_context = self._format_stm_context(memory)
        # Episodic context
        episodic_context = self._format_episodic_context(memory)
        # Memory schema
        memory_schema = self._format_memory_schema()
        # Workflow scope (active workflow plan or list of options)
        workflow_section = self._format_workflow_scope(memory)
        # Available tools (already filtered by scope)
        tools_desc = self._format_tools_description()
        tools_section = f"\nOUTILS DISPONIBLES:\n{tools_desc}" if tools_desc else ""
        rules = """
 RÈGLES:
 - Utilise les outils pour accomplir les tâches, pas pour décorer
 - Si des résultats de recherche sont dispo en mémoire épisodique, référence-les par index
 - Confirme toujours avant une opération destructive (move, delete, overwrite)
 - Réponses courtes — si c'est fait, dis-le en une ligne
 - Si la demande est floue, demande un éclaircissement AVANT de lancer quoi que ce soit
 """
        sections = [
            identity,
            language_instruction,
            config_section,
            stm_context,
            episodic_context,
            memory_schema,
            workflow_section,
            tools_section,
            rules,
        ]
        return "\n\n".join(s for s in sections if s and s.strip())
@@ -0,0 +1,180 @@
 """Prompt builder for the agent system."""
 import json
 from typing import Any
 from alfred.infrastructure.persistence import get_memory
 from .registry import Tool
 class PromptBuilder:
    """Builds system prompts for the agent with memory context."""
    def __init__(self, tools: dict[str, Tool]):
        self.tools = tools
    def build_tools_spec(self) -> list[dict[str, Any]]:
        """Build the tool specification for the LLM API."""
        tool_specs = []
        for tool in self.tools.values():
            spec = {
                "type": "function",
                "function": {
                    "name": tool.name,
                    "description": tool.description,
                    "parameters": tool.parameters,
                },
            }
            tool_specs.append(spec)
        return tool_specs
    def _format_tools_description(self) -> str:
        """Format tools with their descriptions and parameters."""
        if not self.tools:
            return ""
        return "\n".join(
            f"- {tool.name}: {tool.description}\n"
            f"  Parameters: {json.dumps(tool.parameters, ensure_ascii=False)}"
            for tool in self.tools.values()
        )
    def _format_episodic_context(self, memory) -> str:
        """Format episodic memory context for the prompt."""
        lines = []
        if memory.episodic.last_search_results:
            results = memory.episodic.last_search_results
            result_list = results.get("results", [])
            lines.append(
                f"\nLAST SEARCH: '{results.get('query')}' ({len(result_list)} results)"
            )
            # Show first 5 results
            for i, result in enumerate(result_list[:5]):
                name = result.get("name", "Unknown")
                lines.append(f"  {i + 1}. {name}")
            if len(result_list) > 5:
                lines.append(f"  ... and {len(result_list) - 5} more")
        if memory.episodic.pending_question:
            question = memory.episodic.pending_question
            lines.append(f"\nPENDING QUESTION: {question.get('question')}")
            lines.append(f"  Type: {question.get('type')}")
            if question.get("options"):
                lines.append(f"  Options: {len(question.get('options'))}")
        if memory.episodic.active_downloads:
            lines.append(f"\nACTIVE DOWNLOADS: {len(memory.episodic.active_downloads)}")
            for dl in memory.episodic.active_downloads[:3]:
                lines.append(f"  - {dl.get('name')}: {dl.get('progress', 0)}%")
        if memory.episodic.recent_errors:
            lines.append("\nRECENT ERRORS (up to 3):")
            for error in memory.episodic.recent_errors[-3:]:
                lines.append(
                    f"  - Action '{error.get('action')}' failed: {error.get('error')}"
                )
        # Unread events
        unread = [e for e in memory.episodic.background_events if not e.get("read")]
        if unread:
            lines.append(f"\nUNREAD EVENTS: {len(unread)}")
            for event in unread[:3]:
                lines.append(f"  - {event.get('type')}: {event.get('data')}")
        return "\n".join(lines)
    def _format_stm_context(self, memory) -> str:
        """Format short-term memory context for the prompt."""
        lines = []
        if memory.stm.current_workflow:
            workflow = memory.stm.current_workflow
            lines.append(
                f"CURRENT WORKFLOW: {workflow.get('type')} (stage: {workflow.get('stage')})"
            )
            if workflow.get("target"):
                lines.append(f"  Target: {workflow.get('target')}")
        if memory.stm.current_topic:
            lines.append(f"CURRENT TOPIC: {memory.stm.current_topic}")
        if memory.stm.extracted_entities:
            lines.append("EXTRACTED ENTITIES:")
            for key, value in memory.stm.extracted_entities.items():
                lines.append(f"  - {key}: {value}")
        if memory.stm.language:
            lines.append(f"CONVERSATION LANGUAGE: {memory.stm.language}")
        return "\n".join(lines)
    def _format_config_context(self, memory) -> str:
        """Format configuration context."""
        lines = ["CURRENT CONFIGURATION:"]
        if memory.ltm.config:
            for key, value in memory.ltm.config.items():
                lines.append(f"  - {key}: {value}")
        else:
            lines.append("  (no configuration set)")
        return "\n".join(lines)
    def build_system_prompt(self) -> str:
        """Build the complete system prompt."""
        # Get memory once for all context formatting
        memory = get_memory()
        # Base instruction
        base = "You are a helpful AI assistant for managing a media library."
        # Language instruction
        language_instruction = (
            "Your first task is to determine the user's language from their message "
            "and use the `set_language` tool if it's different from the current one. "
            "After that, proceed to help the user."
        )
        # Available tools
        tools_desc = self._format_tools_description()
        tools_section = f"\nAVAILABLE TOOLS:\n{tools_desc}" if tools_desc else ""
        # Configuration
        config_section = self._format_config_context(memory)
        if config_section:
            config_section = f"\n{config_section}"
        # STM context
        stm_context = self._format_stm_context(memory)
        if stm_context:
            stm_context = f"\n{stm_context}"
        # Episodic context
        episodic_context = self._format_episodic_context(memory)
        # Important rules
        rules = """
 IMPORTANT RULES:
 - Use tools to accomplish tasks
 - When search results are available, reference them by index (e.g., "add_torrent_by_index")
 - Always confirm actions with the user before executing destructive operations
 - Provide clear, concise responses
 """
        # Examples
        examples = """
 EXAMPLES:
 - User: "Find Inception" → Use find_media_imdb_id, then find_torrent
 - User: "download the 3rd one" → Use add_torrent_by_index with index=3
 - User: "List my downloads" → Use list_folder with folder_type="download"
 """
        return f"""{base}
 {language_instruction}
 {tools_section}
 {config_section}
 {stm_context}
 {episodic_context}
 {rules}
 {examples}
 """
@@ -1,4 +1,4 @@
-"""Tool registry — defines and registers all available tools for the agent."""
+"""Tool registry - defines and registers all available tools for the agent."""
 import inspect
 import logging
@@ -6,9 +6,6 @@ from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any
 from .tools_TO_CHECK.spec import ToolSpec, ToolSpecError
 from .tools_TO_CHECK.spec_loader import load_tool_specs
 logger = logging.getLogger(__name__)
@@ -20,63 +17,51 @@ class Tool:
    description: str
    func: Callable[..., dict[str, Any]]
    parameters: dict[str, Any]
    cache_key: str | None = None  # Parameter name to use as STM cache key.
-_PY_TYPE_TO_JSON = {
+def _create_tool_from_function(func: Callable) -> Tool:
    str: "string",
    int: "integer",
    float: "number",
    bool: "boolean",
    list: "array",
    dict: "object",
 }
 def _json_type_for(annotation) -> str:
    """Map a Python type annotation to a JSON Schema 'type' string."""
    if annotation is inspect.Parameter.empty:
        return "string"
    # Strip Optional[X] / X | None to X.
    args = getattr(annotation, "__args__", None)
    if args:
        non_none = [a for a in args if a is not type(None)]
        if len(non_none) == 1:
            annotation = non_none[0]
    return _PY_TYPE_TO_JSON.get(annotation, "string")
 def _create_tool_from_function(func: Callable, spec: ToolSpec | None = None) -> Tool:
    """
-    Create a Tool object from a function, optionally enriched with a spec.
+    Create a Tool object from a function.
-    Types and required-ness always come from the Python signature (source of
+    Args:
-    truth for the API contract). When a spec is provided, the description
+        func: Function to convert to a tool
-    and per-parameter docs come from the YAML spec instead of the docstring.
+
    Returns:
        Tool object with metadata extracted from function
    """
    sig = inspect.signature(func)
-    sig_params = {name: p for name, p in sig.parameters.items() if name != "self"}
+    doc = inspect.getdoc(func)
-    if spec is not None:
+    # Extract description from docstring (first line)
-        _validate_spec_matches_signature(func.__name__, sig_params, spec)
+    description = doc.strip().split("\n")[0] if doc else func.__name__
        description = spec.compile_description()
        param_descriptions = {
            name: spec.compile_parameter_description(name) for name in sig_params
        }
    else:
        doc = inspect.getdoc(func)
        description = doc.strip().split("\n")[0] if doc else func.__name__
        param_descriptions = {name: f"Parameter {name}" for name in sig_params}
-    properties: dict[str, dict[str, Any]] = {}
+    # Build JSON schema from function signature
-    required: list[str] = []
+    properties = {}
    required = []
    for param_name, param in sig.parameters.items():
        if param_name == "self":
            continue
        # Map Python types to JSON schema types
        param_type = "string"  # default
        if param.annotation != inspect.Parameter.empty:
            if param.annotation is str:
                param_type = "string"
            elif param.annotation is int:
                param_type = "integer"
            elif param.annotation is float:
                param_type = "number"
            elif param.annotation is bool:
                param_type = "boolean"
    for param_name, param in sig_params.items():
        properties[param_name] = {
-            "type": _json_type_for(param.annotation),
+            "type": param_type,
-            "description": param_descriptions[param_name],
+            "description": f"Parameter {param_name}",
        }
-        if param.default is inspect.Parameter.empty:
+
        # Add to required if no default value
        if param.default == inspect.Parameter.empty:
            required.append(param_name)
    parameters = {
@@ -85,94 +70,46 @@ def _create_tool_from_function(func: Callable, spec: ToolSpec | None = None) ->
        "required": required,
    }
    cache_key = spec.cache.key if spec is not None and spec.cache is not None else None
    return Tool(
        name=func.__name__,
        description=description,
        func=func,
        parameters=parameters,
        cache_key=cache_key,
    )
 def _validate_spec_matches_signature(
    func_name: str,
    sig_params: dict[str, inspect.Parameter],
    spec: ToolSpec,
 ) -> None:
    """Ensure every signature param has a spec entry and vice versa."""
    sig_names = set(sig_params.keys())
    spec_names = set(spec.parameters.keys())
    missing_in_spec = sig_names - spec_names
    if missing_in_spec:
        raise ToolSpecError(
            f"tool '{func_name}': spec is missing entries for parameter(s) "
            f"{sorted(missing_in_spec)}"
        )
    extra_in_spec = spec_names - sig_names
    if extra_in_spec:
        raise ToolSpecError(
            f"tool '{func_name}': spec has entries for unknown parameter(s) "
            f"{sorted(extra_in_spec)} (not in function signature)"
        )
 def make_tools(settings) -> dict[str, Tool]:
    """
    Create and register all available tools.
    Args:
-        settings: Application settings instance.
+        settings: Application settings instance
    Returns:
-        Dictionary mapping tool names to Tool objects.
+        Dictionary mapping tool names to Tool objects
    """
-    from .tools_TO_CHECK import api as api_tools  # noqa: PLC0415
+    # Import tools here to avoid circular dependencies
-    from .tools_TO_CHECK import filesystem as fs_tools  # noqa: PLC0415
+    from .tools import api as api_tools  # noqa: PLC0415
-    from .tools_TO_CHECK import language as lang_tools  # noqa: PLC0415
+    from .tools import filesystem as fs_tools  # noqa: PLC0415
-    from .tools_TO_CHECK import workflow as wf_tools  # noqa: PLC0415
+    from .tools import language as lang_tools  # noqa: PLC0415
    # List of all tool functions
    tool_functions = [
        fs_tools.set_path_for_folder,
        fs_tools.list_folder,
        fs_tools.read_release_metadata,
        fs_tools.query_library,
        fs_tools.analyze_release,
        fs_tools.probe_media,
        fs_tools.resolve_season_destination,
        fs_tools.resolve_episode_destination,
        fs_tools.resolve_movie_destination,
        fs_tools.resolve_series_destination,
        fs_tools.move_media,
        fs_tools.move_to_destination,
        fs_tools.manage_subtitles,
        fs_tools.create_seed_links,
        fs_tools.learn,
        api_tools.find_media_imdb_id,
        api_tools.find_torrent,
        api_tools.add_torrent_by_index,
        api_tools.add_torrent_to_qbittorrent,
        api_tools.get_torrent_by_index,
        lang_tools.set_language,
        wf_tools.start_workflow,
        wf_tools.end_workflow,
    ]
-    specs = load_tool_specs()
+    # Create Tool objects from functions
-
+    tools = {}
    tools: dict[str, Tool] = {}
    for func in tool_functions:
-        spec = specs.get(func.__name__)
+        tool = _create_tool_from_function(func)
        tool = _create_tool_from_function(func, spec=spec)
        tools[tool.name] = tool
-    with_spec = sum(1 for fn in tool_functions if fn.__name__ in specs)
+    logger.info(f"Registered {len(tools)} tools: {list(tools.keys())}")
    logger.info(
        f"Registered {len(tools)} tools "
        f"({with_spec} with YAML spec, {len(tools) - with_spec} doc-only): "
        f"{list(tools.keys())}"
    )
    return tools
@@ -0,0 +1,22 @@
 """Tools module - filesystem and API tools for the agent."""
 from .api import (
    add_torrent_by_index,
    add_torrent_to_qbittorrent,
    find_media_imdb_id,
    find_torrent,
    get_torrent_by_index,
 )
 from .filesystem import list_folder, set_path_for_folder
 from .language import set_language
 __all__ = [
    "set_path_for_folder",
    "list_folder",
    "find_media_imdb_id",
    "find_torrent",
    "get_torrent_by_index",
    "add_torrent_to_qbittorrent",
    "add_torrent_by_index",
    "set_language",
 ]
@@ -3,53 +3,60 @@
 import logging
 from typing import Any
-from alfred.application.movies_TO_CHECK import SearchMovieUseCase
+from alfred.application.movies import SearchMovieUseCase
-from alfred.application.torrents_TO_CHECK import AddTorrentUseCase, SearchTorrentsUseCase
+from alfred.application.torrents import AddTorrentUseCase, SearchTorrentsUseCase
-from alfred.application.tv_shows_TO_CHECK import SearchShowUseCase
+from alfred.infrastructure.api.knaben import knaben_client
-from alfred.infrastructure.api_TO_CHECK.knaben import knaben_client
+from alfred.infrastructure.api.qbittorrent import qbittorrent_client
-from alfred.infrastructure.api_TO_CHECK.qbittorrent import qbittorrent_client
+from alfred.infrastructure.api.tmdb import tmdb_client
-from alfred.infrastructure.api_TO_CHECK.tmdb import tmdb_client
+from alfred.infrastructure.persistence import get_memory
 from alfred.infrastructure.persistence_TO_CHECK import get_memory
 logger = logging.getLogger(__name__)
-def search_movies(media_title: str) -> dict[str, Any]:
+def find_media_imdb_id(media_title: str) -> dict[str, Any]:
-    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/search_movies.yaml."""
+    """
    Find the IMDb ID for a given media title using TMDB API.
    Args:
        media_title: Title of the media to search for.
    Returns:
        Dict with IMDb ID and media info, or error details.
    """
    use_case = SearchMovieUseCase(tmdb_client)
    response = use_case.execute(media_title)
    result = response.to_dict()
    if result.get("status") == "ok":
        memory = get_memory()
-        memory.stm.set_entity("last_movie_search", {"hits": result.get("hits", [])})
+        memory.stm.set_entity(
-        memory.stm.set_topic("searching_movie")
+            "last_media_search",
-        logger.debug(
+            {
-            f"Stored movie search result in STM: {len(result.get('hits', []))} hits"
+                "title": result.get("title"),
-        )
+                "imdb_id": result.get("imdb_id"),
-
+                "media_type": result.get("media_type"),
-    return result
+                "tmdb_id": result.get("tmdb_id"),
-
+            },
 def search_shows(show_title: str) -> dict[str, Any]:
    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/search_shows.yaml."""
    use_case = SearchShowUseCase(tmdb_client)
    response = use_case.execute(show_title)
    result = response.to_dict()
    if result.get("status") == "ok":
        memory = get_memory()
        memory.stm.set_entity("last_show_search", {"hits": result.get("hits", [])})
        memory.stm.set_topic("searching_show")
        logger.debug(
            f"Stored show search result in STM: {len(result.get('hits', []))} hits"
        )
        memory.stm.set_topic("searching_media")
        logger.debug(f"Stored media search result in STM: {result.get('title')}")
    return result
 def find_torrent(media_title: str) -> dict[str, Any]:
-    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/find_torrent.yaml."""
+    """
    Find torrents for a given media title using Knaben API.
    Results are stored in episodic memory so the user can reference them
    by index (e.g., "download the 3rd one").
    Args:
        media_title: Title of the media to search for.
    Returns:
        Dict with torrent list or error details.
    """
    logger.info(f"Searching torrents for: {media_title}")
    use_case = SearchTorrentsUseCase(knaben_client)
@@ -69,7 +76,17 @@ def find_torrent(media_title: str) -> dict[str, Any]:
 def get_torrent_by_index(index: int) -> dict[str, Any]:
-    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/get_torrent_by_index.yaml."""
+    """
    Get a torrent from the last search results by its index.
    Allows the user to reference results by number after a search.
    Args:
        index: 1-based index of the torrent in the search results.
    Returns:
        Dict with torrent data or error if not found.
    """
    logger.info(f"Getting torrent at index: {index}")
    memory = get_memory()
@@ -96,7 +113,15 @@ def get_torrent_by_index(index: int) -> dict[str, Any]:
 def add_torrent_to_qbittorrent(magnet_link: str) -> dict[str, Any]:
-    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/add_torrent_to_qbittorrent.yaml."""
+    """
    Add a torrent to qBittorrent using a magnet link.
    Args:
        magnet_link: Magnet link of the torrent to add.
    Returns:
        Dict with success status or error details.
    """
    logger.info("Adding torrent to qBittorrent")
    use_case = AddTorrentUseCase(qbittorrent_client)
@@ -132,7 +157,17 @@ def add_torrent_to_qbittorrent(magnet_link: str) -> dict[str, Any]:
 def add_torrent_by_index(index: int) -> dict[str, Any]:
-    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/add_torrent_by_index.yaml."""
+    """
    Add a torrent from the last search results by its index.
    Combines get_torrent_by_index and add_torrent_to_qbittorrent.
    Args:
        index: 1-based index of the torrent in the search results.
    Returns:
        Dict with success status or error details.
    """
    logger.info(f"Adding torrent by index: {index}")
    torrent_result = get_torrent_by_index(index)
@@ -0,0 +1,40 @@
 """Filesystem tools for folder management."""
 from typing import Any
 from alfred.application.filesystem import ListFolderUseCase, SetFolderPathUseCase
 from alfred.infrastructure.filesystem import FileManager
 def set_path_for_folder(folder_name: str, path_value: str) -> dict[str, Any]:
    """
    Set a folder path in the configuration.
    Args:
        folder_name: Name of folder to set (download, tvshow, movie, torrent).
        path_value: Absolute path to the folder.
    Returns:
        Dict with status or error information.
    """
    file_manager = FileManager()
    use_case = SetFolderPathUseCase(file_manager)
    response = use_case.execute(folder_name, path_value)
    return response.to_dict()
 def list_folder(folder_type: str, path: str = ".") -> dict[str, Any]:
    """
    List contents of a configured folder.
    Args:
        folder_type: Type of folder to list (download, tvshow, movie, torrent).
        path: Relative path within the folder (default: root).
    Returns:
        Dict with folder contents or error information.
    """
    file_manager = FileManager()
    use_case = ListFolderUseCase(file_manager)
    response = use_case.execute(folder_type, path)
    return response.to_dict()
@@ -3,13 +3,21 @@
 import logging
 from typing import Any
-from alfred.infrastructure.persistence_TO_CHECK import get_memory
+from alfred.infrastructure.persistence import get_memory
 logger = logging.getLogger(__name__)
 def set_language(language: str) -> dict[str, Any]:
-    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/set_language.yaml."""
+    """
    Set the conversation language.
    Args:
        language: Language code (e.g., 'en', 'fr', 'es', 'de')
    Returns:
        Status dictionary
    """
    try:
        memory = get_memory()
        memory.stm.set_language(language)
@@ -1,23 +0,0 @@
 """Tools module — agent-exposed wrappers.
 Re-exports are intentionally minimal during the ``unfuck`` refactor.
 Tool wiring (registry / specs / LLM-facing surface) is the last
 chunk of work on this branch; until then, importers should reach
 into the submodules directly (``alfred.agent.tools.filesystem``, …).
 """
 from .api import (
    add_torrent_by_index,
    add_torrent_to_qbittorrent,
    find_torrent,
    get_torrent_by_index,
 )
 from .language import set_language
 __all__ = [
    "find_torrent",
    "get_torrent_by_index",
    "add_torrent_to_qbittorrent",
    "add_torrent_by_index",
    "set_language",
 ]
@@ -1,373 +0,0 @@
 """Filesystem tools for folder management.
 Thin wrappers around the 5 atomic filesystem use cases
 (``alfred.application.filesystem``) plus a few self-contained tools
 (``analyze_release``, ``probe_media``, ``learn``, …).
 Tools removed during the ``unfuck`` filesystem refactor — to be
 rewired in a later step:
  - ``manage_subtitles`` (depends on the rewritten subtitle services)
  - ``set_path_for_folder`` (no replacement use case yet)
  - ``create_seed_links`` (flow has changed: hard-link straight to
    library, no copy back; will be re-introduced per-file when the
    organize-release workflow lands)
  - ``resolve_season_destination`` / ``resolve_episode_destination``
    / ``resolve_movie_destination`` / ``resolve_series_destination``
    (their use cases moved to ``_OLD`` files pending a rewrite)
 """
 from pathlib import Path
 from typing import Any
 import yaml
 import alfred as _alfred_pkg
 from alfred.application.filesystem import (
    DirectoryRoots,
    create_dir_use_case,
    list_dir_use_case,
    move_file_use_case,
 )
 from alfred.infrastructure.knowledge_TO_CHECK.release_kb import YamlReleaseKnowledge
 from alfred.infrastructure.metadata_TO_CHECK import MetadataStore
 from alfred.infrastructure.persistence_TO_CHECK import get_memory
 from alfred.infrastructure.probe_TO_CHECK import FfprobeMediaProber
 # Agent-tools frontier: this is the legitimate home for the singletons that
 # back every LLM-exposed wrapper. The use cases below take ``kb`` / ``prober``
 # as required params; tests inject their own stubs.
 _KB = YamlReleaseKnowledge()
 _PROBER = FfprobeMediaProber()
 _LEARNED_ROOT = Path(_alfred_pkg.__file__).parent.parent / "data" / "knowledge"
 class _RootsNotConfigured(Exception):
    """Raised when one of the 4 expected roots is missing from memory."""
    def __init__(self, missing: list[str]):
        super().__init__(f"Roots not configured: {missing}")
        self.missing = missing
 def _load_directory_roots() -> DirectoryRoots:
    """Build :class:`DirectoryRoots` from the persisted memory.
    Reads:
      - ``ltm.workspace.download``  → ``downloads``
      - ``ltm.workspace.torrent``   → ``torrents``
      - ``ltm.library_paths['movies']``    → ``movies``
      - ``ltm.library_paths['tv_shows']``  → ``tv_shows``
    Raises:
        _RootsNotConfigured: if any of the four paths is unset.
    """
    memory = get_memory()
    downloads = memory.ltm.workspace.download
    torrents = memory.ltm.workspace.torrent
    movies = memory.ltm.library_paths.get("movies")
    tv_shows = memory.ltm.library_paths.get("tv_shows")
    missing: list[str] = []
    if not downloads:
        missing.append("downloads")
    if not torrents:
        missing.append("torrents")
    if not movies:
        missing.append("movies")
    if not tv_shows:
        missing.append("tv_shows")
    if missing:
        raise _RootsNotConfigured(missing)
    return DirectoryRoots(
        downloads=Path(downloads),
        torrents=Path(torrents),
        movies=Path(movies),
        tv_shows=Path(tv_shows),
    )
 def _roots_error(exc: _RootsNotConfigured) -> dict[str, Any]:
    return {
        "status": "error",
        "error": "roots_not_configured",
        "message": (
            f"Missing roots: {exc.missing}. "
            "Configure them via /set_path before using filesystem tools."
        ),
    }
 # ---------------------------------------------------------------------------
 # 5 atomic filesystem tools — thin wrappers over the use cases.
 # ---------------------------------------------------------------------------
 def list_folder(path: str) -> dict[str, Any]:
    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/list_folder.yaml."""
    try:
        roots = _load_directory_roots()
    except _RootsNotConfigured as e:
        return _roots_error(e)
    return list_dir_use_case(Path(path), roots).to_dict()
 def create_directory(path: str) -> dict[str, Any]:
    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/create_directory.yaml."""
    try:
        roots = _load_directory_roots()
    except _RootsNotConfigured as e:
        return _roots_error(e)
    return create_dir_use_case(Path(path), roots).to_dict()
 def move_media(source: str, destination: str) -> dict[str, Any]:
    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/move_media.yaml."""
    try:
        roots = _load_directory_roots()
    except _RootsNotConfigured as e:
        return _roots_error(e)
    return move_file_use_case(Path(source), Path(destination), roots).to_dict()
 def move_to_destination(source: str, destination: str) -> dict[str, Any]:
    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/move_to_destination.yaml.
    Convenience tool that creates the destination's parent directory
    if missing, then moves the file. Saves the LLM from having to
    chain ``create_directory`` + ``move_media`` explicitly.
    """
    try:
        roots = _load_directory_roots()
    except _RootsNotConfigured as e:
        return _roots_error(e)
    dst = Path(destination)
    mkdir_resp = create_dir_use_case(dst.parent, roots)
    if mkdir_resp.status != "ok":
        return mkdir_resp.to_dict()
    return move_file_use_case(Path(source), dst, roots).to_dict()
 # ---------------------------------------------------------------------------
 # Self-contained tools — not impacted by the filesystem refactor.
 # ---------------------------------------------------------------------------
 def learn(pack: str, category: str, key: str, values: list[str]) -> dict[str, Any]:
    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/learn.yaml."""
    _VALID_PACKS = {"subtitles"}
    _VALID_CATEGORIES = {"languages", "types", "formats"}
    if pack not in _VALID_PACKS:
        return {
            "status": "error",
            "error": "unknown_pack",
            "message": f"Unknown pack '{pack}'. Valid: {sorted(_VALID_PACKS)}",
        }
    if category not in _VALID_CATEGORIES:
        return {
            "status": "error",
            "error": "unknown_category",
            "message": f"Unknown category '{category}'. Valid: {sorted(_VALID_CATEGORIES)}",
        }
    learned_path = _LEARNED_ROOT / "subtitles_learned.yaml"
    _LEARNED_ROOT.mkdir(parents=True, exist_ok=True)
    data: dict = {}
    if learned_path.exists():
        try:
            with open(learned_path, encoding="utf-8") as f:
                data = yaml.safe_load(f) or {}
        except Exception as e:
            return {"status": "error", "error": "read_failed", "message": str(e)}
    cat_data = data.setdefault(category, {})
    entry = cat_data.setdefault(key, {"tokens": []})
    existing = entry.get("tokens", [])
    new_tokens = [v for v in values if v not in existing]
    entry["tokens"] = existing + new_tokens
    tmp = learned_path.with_suffix(".yaml.tmp")
    try:
        with open(tmp, "w", encoding="utf-8") as f:
            yaml.safe_dump(
                data, f, allow_unicode=True, default_flow_style=False, sort_keys=False
            )
        tmp.rename(learned_path)
    except Exception as e:
        tmp.unlink(missing_ok=True)
        return {"status": "error", "error": "write_failed", "message": str(e)}
    return {
        "status": "ok",
        "pack": pack,
        "category": category,
        "key": key,
        "added_count": len(new_tokens),
        "tokens": entry["tokens"],
    }
 def analyze_release(release_name: str, source_path: str) -> dict[str, Any]:
    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/analyze_release.yaml."""
    from alfred.application.release_TO_CHECK import inspect_release  # noqa: PLC0415
    result = inspect_release(release_name, Path(source_path), _KB, _PROBER)
    parsed = result.parsed
    return {
        "status": "ok",
        "media_type": parsed.media_type,
        "parse_path": parsed.parse_path,
        "title": parsed.title,
        "year": parsed.year,
        "season": parsed.season,
        "episode": parsed.episode,
        "episode_end": parsed.episode_end,
        "quality": parsed.quality,
        "source": parsed.source,
        "codec": parsed.codec,
        "group": parsed.group,
        "languages": parsed.languages,
        "audio_codec": parsed.audio_codec,
        "audio_channels": parsed.audio_channels,
        "bit_depth": parsed.bit_depth,
        "hdr_format": parsed.hdr_format,
        "edition": parsed.edition,
        "site_tag": parsed.site_tag,
        "is_season_pack": parsed.is_season_pack,
        "probe_used": result.probe_used,
        "confidence": result.report.confidence,
        "road": result.report.road,
        "recommended_action": result.recommended_action,
    }
 def probe_media(source_path: str) -> dict[str, Any]:
    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/probe_media.yaml."""
    path = Path(source_path)
    if not path.exists():
        return {
            "status": "error",
            "error": "not_found",
            "message": f"{source_path} does not exist",
        }
    media_info = _PROBER.probe(path)
    if media_info is None:
        return {
            "status": "error",
            "error": "probe_failed",
            "message": "ffprobe failed to read the file",
        }
    return {
        "status": "ok",
        "video": {
            "codec": media_info.video_codec,
            "resolution": media_info.resolution,
            "width": media_info.width,
            "height": media_info.height,
            "duration_seconds": media_info.duration_seconds,
            "bitrate_kbps": media_info.bitrate_kbps,
        },
        "audio_tracks": [
            {
                "index": t.index,
                "codec": t.codec,
                "channels": t.channels,
                "channel_layout": t.channel_layout,
                "language": t.language,
                "is_default": t.is_default,
            }
            for t in media_info.audio_tracks
        ],
        "subtitle_tracks": [
            {
                "index": t.index,
                "codec": t.codec,
                "language": t.language,
                "is_default": t.is_default,
                "is_forced": t.is_forced,
            }
            for t in media_info.subtitle_tracks
        ],
        "audio_languages": media_info.audio_languages,
        "is_multi_audio": media_info.is_multi_audio,
    }
 def read_release_metadata(release_path: str) -> dict[str, Any]:
    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/read_release_metadata.yaml."""
    path = Path(release_path)
    if not path.exists():
        return {
            "status": "error",
            "error": "not_found",
            "message": f"{release_path} does not exist",
        }
    root = path if path.is_dir() else path.parent
    store = MetadataStore(root)
    if not store.exists():
        return {
            "status": "ok",
            "release_path": str(root),
            "has_metadata": False,
            "metadata": {},
        }
    return {
        "status": "ok",
        "release_path": str(root),
        "has_metadata": True,
        "metadata": store.load(),
    }
 def query_library(name: str) -> dict[str, Any]:
    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/query_library.yaml."""
    needle = name.strip().lower()
    if not needle:
        return {
            "status": "error",
            "error": "empty_name",
            "message": "name must be a non-empty string",
        }
    memory = get_memory()
    roots = memory.ltm.library_paths.to_dict() or {}
    if not roots:
        return {
            "status": "error",
            "error": "no_libraries",
            "message": "No library paths configured — call set_path_for_folder first.",
        }
    matches: list[dict[str, Any]] = []
    for collection, root in roots.items():
        root_path = Path(root)
        if not root_path.is_dir():
            continue
        for entry in root_path.iterdir():
            if not entry.is_dir():
                continue
            if needle not in entry.name.lower():
                continue
            store = MetadataStore(entry)
            matches.append(
                {
                    "collection": collection,
                    "name": entry.name,
                    "path": str(entry),
                    "has_metadata": store.exists(),
                }
            )
    return {
        "status": "ok",
        "query": name,
        "match_count": len(matches),
        "matches": matches,
    }
@@ -1,221 +0,0 @@
 """
 ToolSpec — semantic description of a tool, loaded from YAML.
 Each tool exposed to the agent has a matching YAML spec under
 alfred/agent/tools/specs/{tool_name}.yaml. The spec carries everything the
 LLM needs to decide *when* and *why* to call the tool — separated from the
 Python signature, which remains the source of truth for *how* (types,
 required-ness).
 The YAML structure is documented in the dataclasses below. Loading a spec
 validates its shape; missing or unexpected fields raise ToolSpecError.
 """
 from __future__ import annotations
 from dataclasses import dataclass, field
 from pathlib import Path
 import yaml
 class ToolSpecError(ValueError):
    """Raised when a YAML tool spec is malformed or inconsistent."""
@dataclass(frozen=True)
 class ParameterSpec:
    """Semantic description of a single tool parameter."""
    description: str  # Short: what the value represents.
    why_needed: str  # Why the tool needs this — drives LLM reasoning.
    example: str | None = None  # Concrete example value, shown to the LLM.
    @classmethod
    def from_dict(cls, name: str, data: dict) -> ParameterSpec:
        _require(data, "description", f"parameter '{name}'")
        _require(data, "why_needed", f"parameter '{name}'")
        return cls(
            description=str(data["description"]).strip(),
            why_needed=str(data["why_needed"]).strip(),
            example=str(data["example"]).strip()
            if data.get("example") is not None
            else None,
        )
@dataclass(frozen=True)
 class ReturnsSpec:
    """Description of one possible return shape (ok / needs_clarification / error / ...)."""
    description: str
    fields: dict[str, str] = field(default_factory=dict)
    @classmethod
    def from_dict(cls, key: str, data: dict) -> ReturnsSpec:
        _require(data, "description", f"returns.{key}")
        fields = data.get("fields") or {}
        if not isinstance(fields, dict):
            raise ToolSpecError(
                f"returns.{key}.fields must be a dict, got {type(fields).__name__}"
            )
        return cls(
            description=str(data["description"]).strip(),
            fields={str(k): str(v).strip() for k, v in fields.items()},
        )
@dataclass(frozen=True)
 class CacheSpec:
    """Marks a tool as cacheable in STM.tool_results, keyed by one of its parameters."""
    key: str  # Name of the parameter whose value is the cache key.
    @classmethod
    def from_dict(cls, data: dict) -> CacheSpec:
        _require(data, "key", "cache")
        return cls(key=str(data["key"]).strip())
@dataclass(frozen=True)
 class ToolSpec:
    """Full semantic spec for one tool."""
    name: str
    summary: str  # One-liner — becomes Tool.description.
    description: str  # Longer paragraph.
    when_to_use: str
    when_not_to_use: str | None
    next_steps: str | None
    parameters: dict[str, ParameterSpec]  # name -> ParameterSpec
    returns: dict[str, ReturnsSpec]  # status_key -> ReturnsSpec
    cache: CacheSpec | None = None  # If present, tool is cached.
    @classmethod
    def from_yaml_path(cls, path: Path) -> ToolSpec:
        with open(path, encoding="utf-8") as f:
            data = yaml.safe_load(f) or {}
        if not isinstance(data, dict):
            raise ToolSpecError(f"{path}: top-level must be a mapping")
        try:
            return cls.from_dict(data)
        except ToolSpecError as e:
            raise ToolSpecError(f"{path}: {e}") from e
    @classmethod
    def from_dict(cls, data: dict) -> ToolSpec:
        _require(data, "name", "spec")
        _require(data, "summary", "spec")
        _require(data, "description", "spec")
        _require(data, "when_to_use", "spec")
        params_raw = data.get("parameters") or {}
        if not isinstance(params_raw, dict):
            raise ToolSpecError("parameters must be a mapping")
        parameters = {
            pname: ParameterSpec.from_dict(pname, pdata or {})
            for pname, pdata in params_raw.items()
        }
        returns_raw = data.get("returns") or {}
        if not isinstance(returns_raw, dict):
            raise ToolSpecError("returns must be a mapping")
        returns = {
            rkey: ReturnsSpec.from_dict(rkey, rdata or {})
            for rkey, rdata in returns_raw.items()
        }
        cache_raw = data.get("cache")
        if cache_raw is not None and not isinstance(cache_raw, dict):
            raise ToolSpecError("cache must be a mapping")
        cache = CacheSpec.from_dict(cache_raw) if cache_raw else None
        spec = cls(
            name=str(data["name"]).strip(),
            summary=str(data["summary"]).strip(),
            description=str(data["description"]).strip(),
            when_to_use=str(data["when_to_use"]).strip(),
            when_not_to_use=_strip_or_none(data.get("when_not_to_use")),
            next_steps=_strip_or_none(data.get("next_steps")),
            parameters=parameters,
            returns=returns,
            cache=cache,
        )
        if cache is not None and cache.key not in parameters:
            raise ToolSpecError(
                f"cache.key '{cache.key}' is not a declared parameter "
                f"(declared: {sorted(parameters)})"
            )
        return spec
    def compile_description(self) -> str:
        """
        Build the long description text passed to the LLM as Tool.description.
        Layout:
            <summary>
            <description>
            When to use:
              <when_to_use>
            When NOT to use:    (if present)
              <when_not_to_use>
            Next steps:         (if present)
              <next_steps>
            Returns:
              <status>: <description>
                · <field>: <desc>
        """
        parts = [self.summary, "", self.description]
        parts += ["", "When to use:", _indent(self.when_to_use)]
        if self.when_not_to_use:
            parts += ["", "When NOT to use:", _indent(self.when_not_to_use)]
        if self.next_steps:
            parts += ["", "Next steps:", _indent(self.next_steps)]
        if self.returns:
            parts += ["", "Returns:"]
            for status, ret in self.returns.items():
                parts.append(f"  {status}: {ret.description}")
                for fname, fdesc in ret.fields.items():
                    parts.append(f"    · {fname}: {fdesc}")
        return "\n".join(parts)
    def compile_parameter_description(self, name: str) -> str:
        """Build the JSON Schema 'description' field for one parameter."""
        p = self.parameters.get(name)
        if p is None:
            raise ToolSpecError(f"tool '{self.name}': no spec for parameter '{name}'")
        text = f"{p.description} (Why: {p.why_needed})"
        if p.example:
            text += f" Example: {p.example}"
        return text
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
 def _require(data: dict, key: str, where: str) -> None:
    if data.get(key) is None or (isinstance(data[key], str) and not data[key].strip()):
        raise ToolSpecError(f"{where}: missing required field '{key}'")
 def _strip_or_none(value) -> str | None:
    if value is None:
        return None
    s = str(value).strip()
    return s or None
 def _indent(text: str, prefix: str = "  ") -> str:
    return "\n".join(prefix + line for line in text.splitlines())
@@ -1,53 +0,0 @@
 """
 ToolSpecLoader — discover and load all YAML tool specs from a directory.
 Convention: one YAML file per tool, named exactly like the Python function
 that implements it (e.g. resolve_season_destination.yaml).
 """
 from __future__ import annotations
 import logging
 from pathlib import Path
 from .spec import ToolSpec, ToolSpecError
 logger = logging.getLogger(__name__)
 _DEFAULT_SPECS_DIR = Path(__file__).parent / "specs"
 def load_tool_specs(specs_dir: Path | None = None) -> dict[str, ToolSpec]:
    """
    Load every {tool}.yaml under specs_dir into a {name -> ToolSpec} mapping.
    Args:
        specs_dir: Directory to scan. Defaults to alfred/agent/tools/specs/.
    Returns:
        Mapping from tool name to its parsed ToolSpec.
    Raises:
        ToolSpecError: if a spec is malformed, or if the filename doesn't
                       match the 'name' field inside the YAML.
    """
    root = specs_dir or _DEFAULT_SPECS_DIR
    if not root.exists():
        logger.warning(f"Tool specs directory not found: {root}")
        return {}
    specs: dict[str, ToolSpec] = {}
    for path in sorted(root.glob("*.yaml")):
        spec = ToolSpec.from_yaml_path(path)
        expected_name = path.stem
        if spec.name != expected_name:
            raise ToolSpecError(
                f"{path}: filename stem '{expected_name}' "
                f"does not match spec.name '{spec.name}'"
            )
        if spec.name in specs:
            raise ToolSpecError(f"duplicate tool spec name: '{spec.name}'")
        specs[spec.name] = spec
    logger.info(f"Loaded {len(specs)} tool spec(s) from {root}")
    return specs
@@ -1,53 +0,0 @@
 name: add_torrent_by_index
 summary: >
  Pick a torrent from the last find_torrent results by index and add
  it to qBittorrent in one call.
 description: |
  Convenience wrapper that combines get_torrent_by_index +
  add_torrent_to_qbittorrent. Looks up the torrent at the given
  1-based index, extracts its magnet link, and sends it to
  qBittorrent. The result mirrors add_torrent_to_qbittorrent's, with
  the chosen torrent's name appended on success.
 when_to_use: |
  The default action after find_torrent when the user picks a hit by
  number ("download the second one"). One call, two side effects:
  episodic memory updated + download started.
 when_not_to_use: |
  - When the user only wants to inspect, not download — use
    get_torrent_by_index.
  - When the magnet comes from outside the search results — use
    add_torrent_to_qbittorrent directly.
 next_steps: |
  - On status=ok: confirm the download started and end the workflow
    if not already ended.
  - On status=error (not_found): the index is out of range; show the
    available count from episodic memory.
  - On status=error (no_magnet): the search result was malformed —
    suggest re-running find_torrent.
 parameters:
  index:
    description: 1-based position of the torrent in the last find_torrent results.
    why_needed: |
      Identifies which torrent to add. Out-of-range indices return
      not_found.
    example: 3
 returns:
  ok:
    description: Torrent was added to qBittorrent.
    fields:
      status: "'ok'"
      message: Confirmation message.
      torrent_name: Name of the torrent that was added.
  error:
    description: Failed to add.
    fields:
      error: Short error code (not_found, no_magnet, ...).
      message: Human-readable explanation.
@@ -1,48 +0,0 @@
 name: add_torrent_to_qbittorrent
 summary: >
  Send a magnet link to qBittorrent and start the download.
 description: |
  Adds a torrent to qBittorrent using its WebUI API. On success, the
  download is also recorded in episodic memory as an active_download
  so the agent can track its progress later, the STM topic is set to
  "downloading", and the current workflow is ended (the user typically
  leaves the find-and-download scope at this point).
 when_to_use: |
  When the user provides a raw magnet link, or when chaining manually
  after get_torrent_by_index. For the common "user picked search hit
  N" case, prefer add_torrent_by_index — one call instead of two.
 when_not_to_use: |
  - For .torrent files (not supported by this tool — magnet only).
  - When qBittorrent is not configured / reachable — the call will
    fail and the user has to fix the config first.
 next_steps: |
  - On status=ok: the workflow is already ended; confirm to the user
    that the download has started.
  - On status=error: surface the message; common causes are auth
    failure or qBittorrent being unreachable.
 parameters:
  magnet_link:
    description: Magnet URI of the torrent to add (magnet:?xt=urn:btih:...).
    why_needed: |
      The actual payload sent to qBittorrent. Must be a full magnet
      URI, not a hash alone.
    example: "magnet:?xt=urn:btih:abc123..."
 returns:
  ok:
    description: Torrent accepted by qBittorrent.
    fields:
      status: "'ok'"
      message: Confirmation message.
  error:
    description: qBittorrent rejected the request or is unreachable.
    fields:
      error: Short error code.
      message: Human-readable explanation.
@@ -1,85 +0,0 @@
 name: analyze_release
 summary: >
  One-shot analyzer that parses a release name, detects its media type
  from the folder layout, and enriches the result with ffprobe data.
 description: |
  Combines three steps in a single call so the agent gets a complete
  picture before routing:
    1. parse_release(release_name) — extracts title, year, season,
       episode, quality, source, codec, group, languages, audio info,
       HDR, edition, site tag.
    2. detect_media_type(parsed, path) — uses the on-disk layout
       (single file vs. folder, presence of S01 dirs, episode count)
       to choose: movie / tv_episode / tv_season / tv_complete /
       other / unknown.
    3. ffprobe enrichment — when the media type is recognised, runs
       ffprobe on the first video file found and fills in audio
       codec/channels, bit depth, HDR format. Sets probe_used=true.
 when_to_use: |
  As the very first step of any organize workflow, right after
  list_folder, on each release the user wants to handle. The output
  drives which resolve_*_destination to call next.
 when_not_to_use: |
  - When you only need codec/audio info on a specific video file:
    use probe_media (no parsing, no media-type detection).
  - For releases the user has already analyzed earlier in the same
    workflow — the parse is deterministic, no need to re-run.
 next_steps: |
  - media_type == movie       → resolve_movie_destination
  - media_type == tv_season   → resolve_season_destination
  - media_type == tv_episode  → resolve_episode_destination
  - media_type == tv_complete → resolve_series_destination
  - media_type in (other, unknown) → ask the user what to do; do not
    auto-route.
 cache:
  key: source_path
 parameters:
  release_name:
    description: Raw release folder or file name as it appears on disk.
    why_needed: |
      Source of all the parsed tokens (quality, codec, group, ...).
      Don't sanitise it — the parser relies on the exact spelling.
    example: Breaking.Bad.S01.1080p.BluRay.x265-GROUP
  source_path:
    description: Absolute path to the release folder or file on disk.
    why_needed: |
      Required for layout-based media-type detection and for ffprobe
      to find a video file inside the release.
    example: /downloads/Breaking.Bad.S01.1080p.BluRay.x265-GROUP
 returns:
  ok:
    description: Release analyzed.
    fields:
      status: "'ok'"
      media_type: "One of: movie, tv_episode, tv_season, tv_complete, other, unknown."
      parse_path: "Which parser branch was taken (debug)."
      title: Parsed title.
      year: Parsed year (int) or null.
      season: Season number (int) or null.
      episode: Episode number (int) or null.
      episode_end: Range end episode (multi-episode releases) or null.
      quality: Resolution token (e.g. 1080p, 2160p).
      source: Source token (BluRay, WEB-DL, ...).
      codec: Video codec token (x264, x265, ...).
      group: Release group name or null.
      languages: List of detected language tokens.
      audio_codec: Audio codec from ffprobe (when probe_used=true).
      audio_channels: Audio channel count from ffprobe.
      bit_depth: Bit depth from ffprobe.
      hdr_format: HDR format from ffprobe (HDR10, DV, ...) or null.
      edition: Edition tag (Extended, Director's Cut, ...) or null.
      site_tag: Source-site tag if present.
      is_season_pack: True when the folder contains a full season.
      probe_used: True when ffprobe successfully enriched the result.
      confidence: Parser confidence score, 0–100 (higher = more reliable).
      road: "Parser road: 'easy' (group schema matched), 'shitty' (heuristic but acceptable), or 'path_of_pain' (low confidence — ask the user before auto-routing)."
      recommended_action: "Orchestrator hint: 'process' (go straight to resolve_*_destination), 'ask_user' (media_type unknown or road=path_of_pain — confirm with the user first), or 'skip' (no main video, or media_type=other — nothing to organize)."
@@ -1,59 +0,0 @@
 name: create_seed_links
 summary: >
  Recreate the original torrent folder structure with hard-links so
  qBittorrent can keep seeding after the library move.
 description: |
  Hard-links the library video file back into torrents/<original_folder_name>/
  and copies all remaining files from the original download folder
  (subtitles, .nfo, .jpg, .txt, …) so the torrent data is complete on
  disk. qBittorrent then sees the same content at the location it
  expects and can keep seeding without rehashing the whole torrent.
 when_to_use: |
  Only when the user has confirmed they want to keep seeding after a
  move. Call right after manage_subtitles (or after move_media if there
  are no subs).
 when_not_to_use: |
  - When the user explicitly answered "no" to "keep seeding?".
  - When the download was not from a torrent (e.g. direct download).
  - Before the library file is in place — this tool reads it.
 next_steps: |
  - After success: optionally call qBittorrent to update the torrent's
    save path / force a recheck (not yet covered by a tool).
  - End the workflow.
 parameters:
  library_file:
    description: Absolute path to the video file now in the library.
    why_needed: |
      The source for the hard-link — same inode means qBittorrent sees
      identical bytes at the seeding path.
    example: /tv_shows/Oz.1997.1080p.WEBRip.x265-KONTRAST/Season 03/Oz.S03E01.mkv
  original_download_folder:
    description: Absolute path to the original download folder.
    why_needed: |
      Provides the folder name to recreate under torrents/ and the
      auxiliary files (subs, nfo, ...) to copy over.
    example: /downloads/Oz.S03.1080p.WEBRip.x265-KONTRAST
 returns:
  ok:
    description: Seeding folder rebuilt.
    fields:
      status: "'ok'"
      torrent_subfolder: Absolute path of the recreated folder under torrents/.
      linked_file: Absolute path of the hard-linked video.
      copied_files: List of auxiliary files that were copied.
      copied_count: Number of auxiliary files copied.
      skipped: List of files skipped (already present, unreadable, ...).
  error:
    description: Failed to rebuild the seeding folder.
    fields:
      error: Short error code.
      message: Human-readable explanation.
@@ -1,48 +0,0 @@
 name: end_workflow
 summary: >
  Leave the current workflow scope and return to the broad-catalog mode.
 description: |
  Clears the active workflow from STM. After this call the visible tool
  catalog returns to the core noyau plus start_workflow, so the agent is
  ready to handle a different request.
 when_to_use: |
  - When all the workflow's steps have completed successfully.
  - When the user explicitly cancels the current task.
  - When the user changes subject mid-conversation and the active
    workflow is no longer relevant.
  - When an unrecoverable error makes continuing pointless — explain
    in 'reason'.
 when_not_to_use: |
  - Do not call when there is no active workflow — it will return an
    error. Just call start_workflow for the new request instead.
  - Do not call mid-step just to "free up tools"; finish the step
    or fail it explicitly first.
 next_steps: |
  - After ending, you can either call start_workflow for a new task or
    answer the user directly from the broad catalog.
 parameters:
  reason:
    description: Short reason for ending — completed, cancelled, changed_subject, error, ...
    why_needed: |
      Recorded in episodic memory for debugging and future audits. A
      structured short string is more useful than a long sentence.
    example: completed
 returns:
  ok:
    description: Workflow ended; catalog is back to the broad noyau.
    fields:
      workflow: Name of the workflow that just ended.
      reason: The reason that was passed in.
  error:
    description: Could not end — typically because nothing was active.
    fields:
      error: Short error code (no_active_workflow).
      message: Human-readable explanation.
@@ -1,56 +0,0 @@
 name: find_media_imdb_id
 summary: >
  Search TMDB for a media title and return its canonical title, year,
  IMDb id, and TMDB id.
 description: |
  Looks up a title on TMDB and returns the canonical metadata needed by
  the resolve_*_destination tools. On success, the result is also
  stashed in short-term memory under "last_media_search" so later steps
  in the workflow can read it without re-calling TMDB. The STM topic
  is set to "searching_media".
 when_to_use: |
  Right after analyze_release, before calling resolve_*_destination —
  the resolvers need the canonical title + year and refuse to guess
  them from the raw release name.
 when_not_to_use: |
  - When you already have the IMDb id in STM from an earlier step in
    the same workflow.
  - For torrent search — use find_torrent instead.
 next_steps: |
  - On status=ok: call the appropriate resolve_*_destination with
    tmdb_title and tmdb_year from the result.
  - On status=error (not_found): show the error and ask the user for
    a more precise title.
 cache:
  key: media_title
 parameters:
  media_title:
    description: Title to search for. Free-form — TMDB does the matching.
    why_needed: |
      Drives the TMDB query. Pass a sanitized version (no resolution
      tokens, no group name) for best results.
    example: Breaking Bad
 returns:
  ok:
    description: Match found.
    fields:
      status: "'ok'"
      title: Canonical title as returned by TMDB.
      year: Release year (movies) or first-air year (series).
      media_type: "'movie' or 'tv'."
      imdb_id: IMDb identifier (ttXXXXXXX) or null.
      tmdb_id: TMDB numeric id.
  error:
    description: No match or API failure.
    fields:
      error: Short error code (not_found, api_error, ...).
      message: Human-readable explanation.
@@ -1,52 +0,0 @@
 name: find_torrent
 summary: >
  Search Knaben for torrents matching a media title; cache results in
  episodic memory.
 description: |
  Queries the Knaben aggregator for up to 10 torrents matching the
  given title, then stores the result list in episodic memory under
  "last_search_results". The user can then refer to a torrent by
  1-based index ("download the 3rd one") via get_torrent_by_index or
  add_torrent_by_index. The STM topic is set to "selecting_torrent".
 when_to_use: |
  When the user wants to download something new — typically the first
  step of a "find + download" sub-task. The agent should usually
  pre-filter the title (canonical name + year) before searching for
  cleaner results.
 when_not_to_use: |
  - For TMDB metadata lookup — use find_media_imdb_id.
  - When a search was already performed in the same session and the
    user is just picking from the existing list.
 next_steps: |
  - Present the indexed results to the user.
  - Once chosen: call add_torrent_by_index(N) — that wraps
    get_torrent_by_index + add_torrent_to_qbittorrent.
 cache:
  key: media_title
 parameters:
  media_title:
    description: Title to search for on Knaben. Free-form.
    why_needed: |
      Drives the search query. Use the canonical title (from
      find_media_imdb_id) plus quality preferences for better hits.
    example: Inception 2010 1080p
 returns:
  ok:
    description: Search returned a list of torrents.
    fields:
      status: "'ok'"
      torrents: "List of {name, size, seeders, leechers, magnet, ...}, up to 10."
  error:
    description: Search failed.
    fields:
      error: Short error code.
      message: Human-readable explanation.
@@ -1,48 +0,0 @@
 name: get_torrent_by_index
 summary: >
  Retrieve a torrent from the last find_torrent search by its 1-based
  index.
 description: |
  Reads episodic memory's last_search_results and returns the entry at
  the given 1-based position. Pure lookup — does not start a download.
  Fails when the search results are missing or the index is out of
  range.
 when_to_use: |
  When the user references a search hit by number ("show me the second
  one") but doesn't yet want to download — e.g. inspection, sharing
  the magnet, ...
 when_not_to_use: |
  - When the user wants to start downloading: use add_torrent_by_index
    instead (one call instead of two).
  - When no search has been performed yet — the result will be
    not_found.
 next_steps: |
  - Display the torrent to the user.
  - If they then say "add it", call add_torrent_to_qbittorrent with the
    magnet, or add_torrent_by_index with the same index.
 parameters:
  index:
    description: 1-based position in the last find_torrent result list.
    why_needed: |
      Maps to a specific torrent entry. Out-of-range values return an
      error, not a wraparound.
    example: 3
 returns:
  ok:
    description: Torrent found at that index.
    fields:
      status: "'ok'"
      torrent: "Full torrent dict (name, size, seeders, leechers, magnet, ...)."
  error:
    description: No torrent at that index.
    fields:
      error: Short error code (not_found).
      message: Human-readable explanation, e.g. "Search for torrents first."
@@ -1,76 +0,0 @@
 name: learn
 summary: >
  Teach Alfred a new token mapping and persist it to the learned
  knowledge pack so future scans recognise it.
 description: |
  Appends a new token (or list of tokens) to a key inside a knowledge
  pack and writes the result to `data/knowledge/<pack>_learned.yaml`.
  The change is persisted atomically (write-tmp + rename) so a crash
  cannot corrupt the file. Currently only the `subtitles` pack is
  supported.
 when_to_use: |
  When manage_subtitles returns needs_clarification with unresolved
  tokens, after confirming with the user what the tokens mean. Call
  once per (category, key) — multiple values can be added in a single
  call.
 when_not_to_use: |
  - Without explicit user confirmation of what the token means.
  - For knowledge that belongs in the static pack
    (alfred/knowledge/<pack>.yaml) — that's editor territory, not
    runtime learning.
 next_steps: |
  - After success: re-run the workflow step that triggered the
    clarification (typically manage_subtitles) so the new mapping is
    applied.
 parameters:
  pack:
    description: Knowledge pack name. Currently only "subtitles" is supported.
    why_needed: |
      Decides which `*_learned.yaml` file under data/knowledge/ gets
      written. The pack name is namespaced to avoid collisions across
      domains.
    example: subtitles
  category:
    description: Category within the pack — "languages", "types", or "formats".
    why_needed: |
      Different categories use different lookup tables at scan time.
      A wrong category silently has no effect.
    example: languages
  key:
    description: Canonical entry id — ISO 639-1 code, type name, format name.
    why_needed: |
      The destination bucket for the new tokens. Existing tokens under
      this key are kept; only new values are appended.
    example: es
  values:
    description: List of token spellings to add.
    why_needed: |
      Release groups use many spellings for the same language/type;
      pass them all in one call instead of multiple round-trips.
    example: '["spanish", "espanol", "spa"]'
 returns:
  ok:
    description: Mapping saved.
    fields:
      status: "'ok'"
      pack: Name of the pack that was written to.
      category: Category that was updated.
      key: Key that was updated.
      added_count: Number of values that were actually new (deduplicated).
      tokens: Full updated token list for that key.
  error:
    description: Save failed.
    fields:
      error: Short error code (unknown_pack, unknown_category, read_failed, write_failed).
      message: Human-readable explanation.
@@ -1,63 +0,0 @@
 name: list_folder
 summary: >
  List the contents of a configured folder, optionally below a
  relative subpath.
 description: |
  Reads a folder previously configured via set_path_for_folder and
  returns its entries (files + directories). A relative `path` lets you
  drill down without re-specifying the absolute root each time. Path
  traversal is rejected (no `..`, no absolute paths) so the agent
  cannot escape the configured root.
 when_to_use: |
  - At the start of an organize workflow to discover what's available
    in the download folder.
  - To browse a library collection ("what tv shows do I have?").
  - As a sanity check before any move to confirm the target exists.
 when_not_to_use: |
  - For folders that are not configured — call set_path_for_folder
    first.
  - To list arbitrary system paths — this tool is intentionally scoped
    to the known roots.
 next_steps: |
  - After listing the download folder: typically call analyze_release
    on a specific entry.
  - After listing a library folder: use the result to disambiguate a
    destination during resolve_*_destination.
 cache:
  key: path
 parameters:
  folder_type:
    description: Logical folder key (download, torrent, movie, tv_show, ...).
    why_needed: |
      Resolves to an absolute root through LTM. Must have been set via
      set_path_for_folder beforehand.
    example: download
  path:
    description: Relative subpath inside the root (default ".").
    why_needed: |
      Lets you drill into a subfolder without expanding the root. No
      ".." or absolute path is allowed.
    example: Breaking.Bad.S01.1080p.BluRay.x265-GROUP
 returns:
  ok:
    description: Listing returned.
    fields:
      status: "'ok'"
      folder_type: The key that was listed.
      path: The relative path that was listed.
      entries: List of {name, type, size?} for each entry.
  error:
    description: Could not list the folder.
    fields:
      error: Short error code (folder_not_configured, path_not_found, path_traversal, ...).
      message: Human-readable explanation.
@@ -1,67 +0,0 @@
 name: manage_subtitles
 summary: >
  Detect, filter, and place subtitle tracks next to a video that has just
  been organised into the library.
 description: |
  Scans the source video's surroundings for subtitle files
  (.srt, .ass, .ssa, .vtt, .sub), classifies them by language and type
  (standard / SDH / forced), filters by the user's SubtitlePreferences
  (languages, min size, keep_sdh, keep_forced), and hard-links the
  passing files next to the destination video using the convention
  `<lang>.<ext>`, `<lang>.sdh.<ext>`, `<lang>.forced.<ext>`.
  If no subtitles are found, returns status=ok with placed_count=0 — not
  an error.
 when_to_use: |
  Always after a successful move_media / move_to_destination, before
  closing the workflow. Pass the original source path (where subs live)
  and the new library path (where they should land).
 when_not_to_use: |
  - Do not call before the video itself has been moved — the destination
    must exist for hard-links to make sense.
  - Skip when the user explicitly asks not to handle subtitles.
 next_steps: |
  - On status=ok: continue with create_seed_links (if seeding) or end
    the workflow.
  - On status=needs_clarification: ask the user about the unresolved
    tokens, then optionally call learn() to teach the new mapping.
 parameters:
  source_video:
    description: Absolute path to the original video file (in the download folder).
    why_needed: |
      Subtitles typically live next to the source, either as siblings or
      in a Subs/ subfolder. The scanner walks from this path.
    example: /downloads/Oz.S03.1080p.WEBRip.x265-KONTRAST/Oz.S03E01.mkv
  destination_video:
    description: Absolute path to the video file in its library location.
    why_needed: |
      Subtitles are hard-linked next to this file so media players pick
      them up automatically.
    example: /tv_shows/Oz.1997.1080p.WEBRip.x265-KONTRAST/Season 03/Oz.S03E01.mkv
 returns:
  ok:
    description: Subtitles scanned (and possibly placed).
    fields:
      status: "'ok'"
      placed: List of {source, destination, filename} for each linked file.
      placed_count: Number of subtitle files placed.
      skipped_count: Number of subtitle files filtered out.
  needs_clarification:
    description: One or more tokens could not be classified.
    fields:
      unresolved: List of unrecognised tokens with their context.
      question: Human-readable question to relay to the user.
  error:
    description: Scan or placement failed.
    fields:
      error: Short error code.
      message: Human-readable explanation.
@@ -1,58 +0,0 @@
 name: move_media
 summary: >
  Safely move a media file with copy + integrity check + delete source.
 description: |
  Copies the source file to the destination with an integrity check,
  then deletes the source. Slower than move_to_destination (which is a
  plain rename) but safer across filesystems where rename is not atomic
  or when you want a checksum verification.
 when_to_use: |
  Use to move a single file across filesystems or when paranoia about
  data integrity is justified — e.g. moving a finished download from a
  scratch disk to the main library array.
 when_not_to_use: |
  - For same-filesystem moves where speed matters: use move_to_destination
    (instant rename on ZFS/ext4 within the same dataset).
  - For folder-level moves of complete packs: use move_to_destination —
    move_media is a single-file operation.
 next_steps: |
  - After a successful move: call manage_subtitles to place any subtitle
    tracks, then create_seed_links if the user wants to keep seeding.
  - On error: surface the error code (file_not_found, destination_exists,
    integrity_check_failed) and ask the user how to proceed.
 parameters:
  source:
    description: Absolute path to the source video file.
    why_needed: |
      The file being moved. Typically lives under the downloads folder
      after a torrent completes.
    example: /downloads/Inception.2010.1080p.BluRay.x265-GROUP/movie.mkv
  destination:
    description: Absolute path of the destination file — must not already exist.
    why_needed: |
      Where the file lands in the library. Comes from a resolve_*_destination
      call so the naming convention is respected.
    example: /movies/Inception.2010.1080p.BluRay.x265-GROUP/Inception.2010.1080p.BluRay.x265-GROUP.mkv
 returns:
  ok:
    description: Move succeeded.
    fields:
      status: "'ok'"
      source: Absolute path of the source (now gone).
      destination: Absolute path of the destination (now in place).
      filename: Basename of the destination file.
      size: Size in bytes.
  error:
    description: Move failed.
    fields:
      error: Short error code (file_not_found, destination_exists, integrity_check_failed, ...).
      message: Human-readable explanation.
@@ -1,55 +0,0 @@
 name: move_to_destination
 summary: >
  Move a file or folder to a destination, creating parent directories as needed.
 description: |
  Performs an actual move on disk. Uses the system 'mv' command, so on the
  same filesystem (e.g. ZFS) this is an instant rename. Creates the parent
  directory of the destination if it doesn't exist yet, then moves. Returns
  before/after paths on success, or an error if the destination already
  exists or the source can't be moved.
 when_to_use: |
  Use after one of the resolve_*_destination tools returned status=ok, to
  perform the move it described. The 'source' and 'destination' arguments
  come directly from the resolved paths.
 when_not_to_use: |
  - Never move when status was not 'ok' (clarification still pending or
    error happened) — that would leave the library in a half-broken state.
  - Don't use this for the seed-link step; use create_seed_links for that.
 next_steps: |
  - After a successful move: call manage_subtitles to place any subtitle
    tracks, then create_seed_links to keep qBittorrent seeding.
  - On error: surface the message; do not retry blindly — check whether
    the destination already exists or the source path is correct.
 parameters:
  source:
    description: Absolute path to the source file or folder to move.
    why_needed: |
      The thing being moved. Comes from the user's download folder or from
      a previous tool's output.
    example: /downloads/Oz.S03.1080p.WEBRip.x265-KONTRAST
  destination:
    description: Absolute path of the destination — must not already exist.
    why_needed: |
      Where to put the source. Comes from a resolve_*_destination call so
      that the path matches the library's naming convention.
    example: /tv_shows/Oz.1997.1080p.WEBRip.x265-KONTRAST/Oz.S03.1080p.WEBRip.x265-KONTRAST
 returns:
  ok:
    description: Move succeeded.
    fields:
      source: Absolute path of the source (now gone).
      destination: Absolute path of the destination (now in place).
  error:
    description: Move failed.
    fields:
      error: Short error code (source_not_found, destination_exists, mkdir_failed, move_failed).
      message: Human-readable explanation of what went wrong.
@@ -1,56 +0,0 @@
 name: probe_media
 summary: >
  Run ffprobe on a single video file and return its technical details.
 description: |
  Inspects a specific video file with ffprobe and returns codec,
  resolution, duration, bitrate, the list of audio tracks (with
  language and channel layout), and the list of embedded subtitle
  tracks. Independent of any release-name parsing — works on any file
  you can point at.
 when_to_use: |
  - To inspect a file's audio/subtitle tracks before deciding what to
    do (e.g. choose a default audio language).
  - To verify a video's resolution / codec when the release name is
    unreliable.
  - As a building block when analyze_release is overkill.
 when_not_to_use: |
  - For full release routing — analyze_release does parsing + media
    type detection + probe in one call.
  - On non-video files — ffprobe will return probe_failed.
 next_steps: |
  - The returned info typically feeds a user-facing decision (e.g.
    "this is 7.1 DTS, want to keep it?"); rarely chained directly to
    another tool.
 cache:
  key: source_path
 parameters:
  source_path:
    description: Absolute path to the video file to probe.
    why_needed: |
      ffprobe needs the exact file (not a folder). For releases use
      analyze_release; for a known file path, pass it here.
    example: /downloads/Inception.2010.1080p.BluRay.x265-GROUP/movie.mkv
 returns:
  ok:
    description: Probe succeeded.
    fields:
      status: "'ok'"
      video: "Dict with codec, resolution, width, height, duration_seconds, bitrate_kbps."
      audio_tracks: "List of {index, codec, channels, channel_layout, language, is_default}."
      subtitle_tracks: "List of {index, codec, language, is_default, is_forced}."
      audio_languages: List of language codes present in audio tracks.
      is_multi_audio: True when more than one audio language is present.
  error:
    description: Probe failed.
    fields:
      error: Short error code (not_found, probe_failed).
      message: Human-readable explanation.
@@ -1,54 +0,0 @@
 name: query_library
 summary: >
  Find release folders across all configured library roots whose name
  contains a substring (case-insensitive).
 description: |
  Scans every configured library root (movies, tv_shows, …) at depth 1
  and returns folders whose name contains the query. For each match,
  reports whether a `.alfred/metadata.yaml` exists — handy to spot
  releases that have not been inspected yet. Does not recurse into
  seasons / episodes; one entry per release folder.
 when_to_use: |
  - To answer "do I already have X?" without listing whole library
    roots one by one.
  - To pick the release_path to feed read_release_metadata or any
    inspector tool.
 when_not_to_use: |
  - To list the *whole* library — that scan should live behind a
    dedicated tool (not implemented yet).
  - To browse a single root — use list_folder instead, it's cheaper
    and doesn't open every library.
 next_steps: |
  - When one match is found: feed its path to read_release_metadata or
    analyze_release.
  - When several match: surface the indexed list to the user and ask
    which one they mean.
 parameters:
  name:
    description: Case-insensitive substring of the release name to look for.
    why_needed: |
      Library folders are named after the release (Title.Year.... or
      Title (Year)). A substring is enough to catch typical user
      phrasings ("foundation", "inception 2010").
    example: foundation
 returns:
  ok:
    description: Scan completed (possibly zero matches).
    fields:
      status: "'ok'"
      query: The query string as received.
      match_count: Number of matching folders.
      matches: "List of {collection, name, path, has_metadata}."
  error:
    description: Scan could not run.
    fields:
      error: Short error code (no_libraries, empty_name).
      message: Human-readable explanation.
@@ -1,55 +0,0 @@
 name: read_release_metadata
 summary: >
  Read the `.alfred/metadata.yaml` file for a release folder.
 description: |
  Returns whatever has been previously persisted by inspector tools
  (analyze_release, probe_media, find_media_imdb_id) and by the subtitle
  pipeline. Works for any folder — download or library — as long as the
  release has been touched at least once. Missing metadata is not an
  error: the tool returns `has_metadata=false` with an empty dict.
 when_to_use: |
  - Before re-running analyze_release / probe_media on a release you
    might have already seen — saves a full re-inspection.
  - To answer "what do we know about X?" without scanning.
  - To list which releases in a library have no `.alfred` yet (loop +
    `has_metadata`).
 when_not_to_use: |
  - To search a library by name — use query_library.
  - When you need a fresh probe/parse — call the inspector directly,
    the result will be persisted automatically.
 next_steps: |
  - If `has_metadata=false`, decide whether to inspect now
    (analyze_release / probe_media).
  - If `has_metadata=true`, read `metadata.parse`, `metadata.probe`,
    `metadata.tmdb` blocks before deciding next actions.
 cache:
  key: release_path
 parameters:
  release_path:
    description: Absolute path to the release folder (or any file inside it).
    why_needed: |
      The store lives at `<release_root>/.alfred/metadata.yaml`. A file
      path is auto-resolved to its parent folder.
    example: /mnt/library/tv_shows/Foundation.2021.1080p.WEBRip.x265-RARBG
 returns:
  ok:
    description: Release inspected (file may or may not exist).
    fields:
      status: "'ok'"
      release_path: Absolute path of the release folder.
      has_metadata: True if `.alfred/metadata.yaml` exists.
      metadata: Full content of the file, or empty dict.
  error:
    description: Path does not exist on disk.
    fields:
      error: Short error code (not_found).
      message: Human-readable explanation.
@@ -1,93 +0,0 @@
 name: resolve_episode_destination
 summary: >
  Compute destination paths for a single TV episode file (file move).
 description: |
  Resolves the target series folder, season subfolder, and full destination
  filename for a single-episode release. Returns paths only — does not move
  anything. If a series folder with a different name already exists, returns
  needs_clarification.
 when_to_use: |
  Use after analyze_release has identified the release as a single episode
  (media_type=tv_show, season AND episode both set). TMDB must already be
  queried for the canonical title/year, and optionally the episode title.
 when_not_to_use: |
  - Season packs (folder containing many episodes): use resolve_season_destination.
  - Multi-season packs: use resolve_series_destination.
  - Movies: use resolve_movie_destination.
 next_steps: |
  - On status=ok: call move_to_destination with the source video file and
    destination=library_file.
  - On status=needs_clarification: present question/options to the user,
    then re-call with confirmed_folder set.
  - On status=error: surface the message; do not move.
 parameters:
  release_name:
    description: Raw release file name (with extension).
    why_needed: |
      Drives extraction of quality/source/codec/group, which become part of
      the destination filename so each file is self-describing.
    example: Oz.S03E01.1080p.WEBRip.x265-KONTRAST.mkv
  source_file:
    description: Absolute path to the source video file on disk.
    why_needed: |
      Used to read the source file extension (.mkv, .mp4, .avi…) for the
      destination filename — release names don't always carry the extension.
    example: /downloads/Oz.S03E01.1080p.WEBRip.x265-KONTRAST/file.mkv
  tmdb_title:
    description: Canonical show title from TMDB.
    why_needed: |
      Title prefix for both the series folder and the destination filename;
      ensures consistent naming across all episodes of the show.
    example: Oz
  tmdb_year:
    description: Show start year from TMDB.
    why_needed: |
      Disambiguates remakes/reboots sharing a title; year is part of the
      series folder identity.
    example: "1997"
  tmdb_episode_title:
    description: Episode title from TMDB. Optional.
    why_needed: |
      When present, the destination filename embeds the episode title for
      human-readability (e.g. Oz.S01E01.The.Routine...).
    example: The Routine
  confirmed_folder:
    description: Folder name the user picked after needs_clarification.
    why_needed: |
      Forces the use case to skip detection and use this exact folder name.
    example: Oz.1997.1080p.WEBRip.x265-KONTRAST
 returns:
  ok:
    description: Paths resolved; ready to move the episode file.
    fields:
      series_folder: Absolute path to the series root folder.
      season_folder: Absolute path to the season subfolder.
      library_file: Absolute path to the destination .mkv file (move target).
      series_folder_name: Series folder name for display.
      season_folder_name: Season folder name for display.
      filename: Destination filename for display.
      is_new_series_folder: True if the series folder doesn't exist yet.
  needs_clarification:
    description: A folder exists with a different name; user must choose.
    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.
@@ -1,72 +0,0 @@
 name: resolve_movie_destination
 summary: >
  Compute destination paths for a movie file (file move).
 description: |
  Resolves the target movie folder and full destination filename for a movie
  release. Returns paths only — does not move anything. Movies do not have
  the existing-folder disambiguation problem that TV shows have (each
  release lands in its own folder named after the canonical title + year +
  tech).
 when_to_use: |
  Use after analyze_release has identified the release as a movie
  (media_type=movie). TMDB must already be queried for the canonical title
  and release year.
 when_not_to_use: |
  - TV shows in any form: use resolve_season_destination /
    resolve_episode_destination / resolve_series_destination.
  - Documentaries when they're treated as series rather than standalone
    films: route them through the TV-show resolvers.
 next_steps: |
  - On status=ok: call move_to_destination with the source video file and
    destination=library_file.
  - On status=error: surface the message; do not move.
 parameters:
  release_name:
    description: Raw release folder or file name.
    why_needed: |
      Drives extraction of quality/source/codec/group/edition tokens, which
      become part of both the movie folder and filename so each release is
      self-describing on disk.
    example: Inception.2010.1080p.BluRay.x265-GROUP
  source_file:
    description: Absolute path to the source video file on disk.
    why_needed: |
      Used to read the file extension for the destination filename.
    example: /downloads/Inception.2010.1080p.BluRay.x265-GROUP/movie.mkv
  tmdb_title:
    description: Canonical movie title from TMDB.
    why_needed: |
      Title prefix for the destination folder/file; ensures the library
      uses the canonical title and not a sanitized release-name title.
    example: Inception
  tmdb_year:
    description: Movie release year from TMDB.
    why_needed: |
      Disambiguates remakes that share a title (Dune 1984 vs Dune 2021)
      and locks the folder identity in time.
    example: "2010"
 returns:
  ok:
    description: Paths resolved; ready to move.
    fields:
      movie_folder: Absolute path to the movie folder.
      library_file: Absolute path to the destination .mkv file (move target).
      movie_folder_name: Folder name for display.
      filename: Destination filename for display.
      is_new_folder: True if the movie folder doesn't exist yet.
  error:
    description: Resolution failed.
    fields:
      error: Short error code (e.g. library_not_set).
      message: Human-readable explanation.
@@ -1,95 +0,0 @@
 name: resolve_season_destination
 summary: >
  Compute destination paths for a season pack (folder move) in the TV library.
 description: |
  Resolves the target series folder and season subfolder for a complete-season
  download. Returns the paths only — does not perform any move. If a series
  folder for this show already exists in the library with a different name
  (different group/quality/source), returns needs_clarification so the user
  can decide whether to merge into the existing folder or create a new one.
 when_to_use: |
  Use after analyze_release has identified the release as a season pack
  (media_type=tv_show, season set, episode unset). TMDB must already be
  queried so tmdb_title and tmdb_year are canonical values, not raw tokens
  from the release name.
 when_not_to_use: |
  - Single-episode files: use resolve_episode_destination instead.
  - Multi-season packs (S01-S05 etc.): use resolve_series_destination.
  - Movies: use resolve_movie_destination.
 next_steps: |
  - On status=ok: call move_to_destination with source=<download folder> and
    destination=season_folder.
  - On status=needs_clarification: present the question and options to the
    user, then re-call this tool with confirmed_folder set to the user's pick.
  - On status=error: surface the message to the user; do not move anything.
 parameters:
  release_name:
    description: Raw release folder name as it appears on disk.
    why_needed: |
      Drives extraction of quality/source/codec/group tokens — these are
      embedded in the target folder name (Title.Year.Quality.Source.Codec-GROUP)
      to make releases self-describing on the filesystem.
    example: Oz.S03.1080p.WEBRip.x265-KONTRAST
  tmdb_title:
    description: Canonical show title from TMDB.
    why_needed: |
      Builds the title prefix of the folder name. Must come from TMDB to
      avoid typos and variant spellings present in the raw release name.
    example: Oz
  tmdb_year:
    description: Show start year from TMDB.
    why_needed: |
      Disambiguates shows that share a title across decades (e.g. multiple
      remakes of "The Office") and locks the folder identity.
    example: "1997"
  confirmed_folder:
    description: |
      Folder name chosen by the user after a previous needs_clarification
      response.
    why_needed: |
      Short-circuits the existing-folder detection and forces the use case
      to use this exact folder name, even if it doesn't match the computed
      one.
    example: Oz.1997.1080p.WEBRip.x265-KONTRAST
  source_path:
    description: |
      Absolute path to the release folder on disk. Optional.
    why_needed: |
      When provided, the tool runs ffprobe on the main video inside the
      folder and uses the probe data to fill quality/codec tokens that
      may be missing from the release name. The enriched tech tokens
      end up in the destination folder name, so providing source_path
      gives more accurate names for releases with sparse metadata.
    example: /downloads/Oz.S03.1080p.WEBRip.x265-KONTRAST
 returns:
  ok:
    description: Paths resolved unambiguously; ready to move.
    fields:
      series_folder: Absolute path to the series root folder.
      season_folder: Absolute path to the season subfolder (move target).
      series_folder_name: Just the series folder name, for display.
      season_folder_name: Just the season folder name, for display.
      is_new_series_folder: True if the series folder doesn't exist yet.
  needs_clarification:
    description: A folder already exists with a different name; ask the user.
    fields:
      question: Human-readable question for the user.
      options: List of folder names the user can pick from.
  error:
    description: Resolution failed (config missing, invalid release name, etc.).
    fields:
      error: Short error code (e.g. library_not_set).
      message: Human-readable explanation.
@@ -1,87 +0,0 @@
 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
  source_path:
    description: |
      Absolute path to the release folder on disk. Optional.
    why_needed: |
      When provided, the tool runs ffprobe on the main video inside the
      folder and uses probe data to fill quality/codec tokens that may
      be missing from the release name, producing a more accurate
      destination folder name.
    example: /downloads/The.Wire.S01-S05.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.
@@ -1,47 +0,0 @@
 name: set_language
 summary: >
  Set the conversation language so all subsequent assistant messages
  match it.
 description: |
  Persists an ISO 639-1 language code in short-term memory under
  conversation.language. Read by the prompt builder and any tool that
  needs to localise output. Does not validate the code against an ISO
  list — the LLM is trusted to pass a sensible value.
 when_to_use: |
  As the very first call when the user writes in a language different
  from the current STM language. Doing it before answering avoids a
  mid-reply switch.
 when_not_to_use: |
  - On every turn — only when the language actually changes.
  - To pick a subtitle language — that lives in SubtitlePreferences,
    not the conversation language.
 next_steps: |
  - After success: continue the user's request in the newly set
    language.
 parameters:
  language:
    description: ISO 639-1 language code (en, fr, es, de, ...).
    why_needed: |
      Identifies the target language unambiguously across the UI and
      any localisation logic.
    example: fr
 returns:
  ok:
    description: Language saved.
    fields:
      status: "'ok'"
      message: Confirmation message.
      language: The language code that was saved.
  error:
    description: Could not save the language.
    fields:
      status: "'error'"
      error: Short error code or exception message.
@@ -1,58 +0,0 @@
 name: set_path_for_folder
 summary: >
  Configure where a known folder lives on disk (download, torrent, or
  any library collection).
 description: |
  Stores an absolute path in long-term memory under a folder key. Two
  classes of folders exist:
    - Workspace paths: "download", "torrent" — single-valued each, used
      by the organize workflows.
    - Library paths: any other key (e.g. "movie", "tv_show",
      "documentary") — these are the collections you organise into.
  The path must exist and be a directory; otherwise the call fails
  without changing memory.
 when_to_use: |
  On first run, or when the user moves a folder, or when introducing a
  new library collection (e.g. "set the documentaries folder to ...").
 when_not_to_use: |
  - For one-off listings — list_folder works without configuration only
    if the folder is already set.
  - To rename or delete an existing folder — this only sets paths.
 next_steps: |
  - After success: typical follow-ups are list_folder on the same key,
    or starting a workflow that needs the path.
 parameters:
  folder_name:
    description: Logical name of the folder (download, torrent, movie, tv_show, ...).
    why_needed: |
      The key the agent uses everywhere afterwards. "download" and
      "torrent" are reserved for workspace; anything else becomes a
      library collection.
    example: tv_show
  path_value:
    description: Absolute path to the folder on disk.
    why_needed: |
      Must exist and be readable. Stored verbatim in LTM — relative
      paths are rejected.
    example: /tank/library/tv_shows
 returns:
  ok:
    description: Path saved to long-term memory.
    fields:
      status: "'ok'"
      folder_name: The logical name that was set.
      path_value: The absolute path that was saved.
  error:
    description: Could not set the path.
    fields:
      error: Short error code (path_not_found, not_a_directory, invalid_path, ...).
      message: Human-readable explanation.
@@ -1,64 +0,0 @@
 name: start_workflow
 summary: >
  Enter a workflow scope — narrows the visible tool catalog and gives the
  agent a clear multi-step plan to follow.
 description: |
  Activates a named workflow defined in YAML under agent/workflows/.
  Once active, only the workflow's declared tools (plus the core noyau)
  are exposed to the LLM, which keeps the decision space small and
  focused. The returned plan (description + steps) is the script the
  agent should execute until end_workflow is called.
 when_to_use: |
  Use as the very first action whenever the user request maps to a
  known workflow (e.g. "organize Breaking Bad" → media.organize_media).
  Pass any parameters you already know (release name, target media,
  flags) in 'params' so later steps can read them from STM.
 when_not_to_use: |
  - Do not start a workflow for purely conversational replies or
    one-shot lookups that need a single tool call.
  - Do not start a new workflow while one is already active — call
    end_workflow first.
 next_steps: |
  - On status=ok: follow the returned 'steps' list, calling the tools
    in order. The visible tool catalog has already been narrowed.
  - On status=error (unknown_workflow): surface the available list to
    the user and ask which one they meant.
  - On status=error (workflow_already_active): either continue the
    active workflow or call end_workflow first.
 parameters:
  workflow_name:
    description: Fully-qualified name of the workflow to start (e.g. media.organize_media).
    why_needed: |
      Identifies which YAML definition to load. Names use the
      'domain.action' convention (media.*, mail.*, ...).
    example: media.organize_media
  params:
    description: Initial parameters to seed the workflow with (release name, target, flags).
    why_needed: |
      Later steps read these from STM instead of asking the user again.
      Pass whatever you already extracted from the user's message.
    example: '{"release_name": "Breaking.Bad.S01.1080p.BluRay.x265-GROUP", "keep_seeding": true}'
 returns:
  ok:
    description: Workflow activated; catalog has been narrowed.
    fields:
      workflow: Name of the activated workflow.
      description: Human-readable description of what the workflow does.
      steps: Ordered list of steps to execute.
      tools: Tools that are now visible (in addition to the core noyau).
  error:
    description: Could not activate the workflow.
    fields:
      error: Short error code (unknown_workflow, workflow_already_active).
      message: Human-readable explanation.
      available_workflows: List of valid workflow names (only on unknown_workflow).
      active_workflow: Name of the currently active workflow (only on workflow_already_active).
@@ -1,86 +0,0 @@
 """Workflow scoping tools — start_workflow / end_workflow meta-tools.
 These tools let the agent enter and leave a workflow scope. While a
 workflow is active, the PromptBuilder narrows the visible tool catalog
 to the noyau + the workflow's declared tools, so the LLM doesn't have
 to reason over the full set.
 """
 import logging
 from typing import Any
 from alfred.infrastructure.persistence_TO_CHECK import get_memory
 from ..workflows_TO_CHECK import WorkflowLoader
 logger = logging.getLogger(__name__)
 _loader_cache: list[WorkflowLoader] = []
 def _get_loader() -> WorkflowLoader:
    """Lazily build the module-level WorkflowLoader."""
    if not _loader_cache:
        _loader_cache.append(WorkflowLoader())
    return _loader_cache[0]
 def start_workflow(workflow_name: str, params: dict) -> dict[str, Any]:
    """See specs/start_workflow.yaml for full description."""
    loader = _get_loader()
    workflow = loader.get(workflow_name)
    if workflow is None:
        return {
            "status": "error",
            "error": "unknown_workflow",
            "message": f"Workflow '{workflow_name}' not found",
            "available_workflows": loader.names(),
        }
    memory = get_memory()
    current = memory.stm.workflow.current
    if current is not None:
        return {
            "status": "error",
            "error": "workflow_already_active",
            "message": (
                f"Workflow '{current.get('name')}' is already active. "
                "Call end_workflow before starting a new one."
            ),
            "active_workflow": current.get("name"),
        }
    memory.stm.start_workflow(workflow_name, params or {})
    memory.save()
    logger.info(f"start_workflow: '{workflow_name}' with params={params}")
    return {
        "status": "ok",
        "workflow": workflow_name,
        "description": workflow.get("description", ""),
        "steps": workflow.get("steps", []),
        "tools": workflow.get("tools", []),
    }
 def end_workflow(reason: str) -> dict[str, Any]:
    """See specs/end_workflow.yaml for full description."""
    memory = get_memory()
    current = memory.stm.workflow.current
    if current is None:
        return {
            "status": "error",
            "error": "no_active_workflow",
            "message": "No workflow is currently active.",
        }
    workflow_name = current.get("name")
    memory.stm.end_workflow()
    memory.save()
    logger.info(f"end_workflow: '{workflow_name}' reason={reason!r}")
    return {
        "status": "ok",
        "workflow": workflow_name,
        "reason": reason,
    }
@@ -1,3 +0,0 @@
 from .loader import WorkflowLoader
 __all__ = ["WorkflowLoader"]
@@ -1,52 +0,0 @@
 """WorkflowLoader — autodiscovers and loads workflow YAML files.
 Scans the workflows/ directory for all .yaml files and exposes them
 as dicts. No manual registration needed — drop a new .yaml file and
 it will be picked up automatically.
 """
 import logging
 from pathlib import Path
 import yaml
 logger = logging.getLogger(__name__)
 _WORKFLOWS_DIR = Path(__file__).parent
 class WorkflowLoader:
    """
    Loads all workflow definitions from the workflows/ directory.
    Usage:
        loader = WorkflowLoader()
        all_workflows = loader.all()
        workflow = loader.get("media.organize_media")
    """
    def __init__(self):
        self._workflows: dict[str, dict] = {}
        self._load()
    def _load(self) -> None:
        for path in sorted(_WORKFLOWS_DIR.glob("*.yaml")):
            try:
                data = yaml.safe_load(path.read_text(encoding="utf-8"))
                name = data.get("name") or path.stem
                self._workflows[name] = data
                logger.info(f"WorkflowLoader: Loaded '{name}' from {path.name}")
            except Exception as e:
                logger.warning(f"WorkflowLoader: Could not load {path.name}: {e}")
    def all(self) -> dict[str, dict]:
        """Return all loaded workflows keyed by name."""
        return self._workflows
    def get(self, name: str) -> dict | None:
        """Return a specific workflow by name, or None if not found."""
        return self._workflows.get(name)
    def names(self) -> list[str]:
        """Return all available workflow names."""
        return list(self._workflows.keys())
@@ -1,69 +0,0 @@
 name: media.manage_subtitles
 description: >
  Place subtitle files alongside a video that has just been organised into the library.
  Detects the release pattern automatically, identifies and classifies all tracks,
  filters by user rules, and hard-links matching files to the destination.
  If any tracks are unrecognised, asks the user and optionally teaches Alfred.
 trigger:
  examples:
    - "handle subtitles for The X-Files S01E01"
    - "place the subs next to the file"
    - "subtitles are in the Subs/ folder"
    - "add subtitles"
 tools:
  - manage_subtitles
  - learn
 memory:
  SubtitlePreferences: read
  Workflow: read-write
 steps:
  - id: place_subtitles
    tool: manage_subtitles
    description: >
      Detect release pattern, identify and classify all subtitle tracks,
      filter by rules, hard-link matching files next to the destination video.
      Reads SubtitlePreferences from LTM for language/type/format filtering.
    params:
      source_video: "{source_video}"
      destination_video: "{destination_video}"
      imdb_id: "{imdb_id}"
      media_type: "{media_type}"
      release_group: "{release_group}"
      season: "{season}"
      episode: "{episode}"
    on_result:
      ok_placed_zero: skip               # no subtitles found — not an error
      needs_clarification: ask_user      # unrecognised tokens found
  - id: ask_user
    description: >
      Some tracks could not be classified. Show the user the unresolved tokens
      and ask if they want to teach Alfred what they mean.
      If yes → go to learn_tokens. If no → end workflow.
    ask_user:
      question: >
        I could not identify some tokens in the subtitle files: {unresolved}.
        Do you want to teach me what they mean?
      answers:
        yes: { next_step: learn_tokens }
        no:  { next_step: end }
  - id: learn_tokens
    tool: learn
    description: >
      Persist a new token mapping to the learned knowledge pack so Alfred
      recognises it in future scans without asking again.
    params:
      pack: "subtitles"
      category: "{token_category}"   # "languages" or "types"
      key: "{token_key}"             # e.g. "es", "de"
      values: "{token_values}"       # e.g. ["spanish", "espanol"]
 subtitle_naming:
  standard:  "{lang}.{ext}"
  sdh:       "{lang}.sdh.{ext}"
  forced:    "{lang}.forced.{ext}"
@@ -1,92 +0,0 @@
 name: media.organize_media
 description: >
  Organise a downloaded series or movie into the media library.
  Triggered when the user asks to move/organize a specific title.
  Always moves the video file. Optionally creates seed links in the
  torrents folder so qBittorrent can keep seeding.
 trigger:
  examples:
    - "organize Breaking Bad"
    - "organise Severance season 2"
    - "move Inception to my library"
    - "organize Breaking Bad season 1, keep seeding"
 tools:
  - list_folder
  - analyze_release
  - probe_media
  - find_media_imdb_id
  - resolve_season_destination
  - resolve_episode_destination
  - resolve_movie_destination
  - resolve_series_destination
  - move_to_destination
  - manage_subtitles
  - create_seed_links
 memory:
  WorkspacePaths: read
  LibraryPaths: read
  Library: read-write
  Workflow: read-write
  Entities: read-write
 steps:
  - id: list_downloads
    tool: list_folder
    description: List the download folder to find the target files.
    params:
      folder_type: download
  - id: analyze
    tool: analyze_release
    description: >
      Parse the release name to detect media_type (movie / tv_season /
      tv_episode / tv_complete) and extract season/episode info.
  - id: identify_media
    tool: find_media_imdb_id
    description: Confirm canonical title and year via TMDB.
  - id: resolve_destination
    description: >
      Call the resolver that matches media_type from analyze_release:
        movie       → resolve_movie_destination
        tv_season   → resolve_season_destination
        tv_episode  → resolve_episode_destination
        tv_complete → resolve_series_destination
      If the resolver returns needs_clarification, ask the user and
      re-call with confirmed_folder.
  - id: move_file
    tool: move_to_destination
    description: >
      Move the video file/folder to the destination returned by the
      resolver above.
  - id: handle_subtitles
    tool: manage_subtitles
    description: >
      Place subtitle files alongside the video in the library.
      Pass the original source path and the new library destination path.
    on_missing: skip
  - id: ask_seeding
    ask_user:
      question: "Do you want to keep seeding this torrent?"
      answers:
        "yes": { next_step: create_seed_links }
        "no":  { next_step: end }
  - id: create_seed_links
    tool: create_seed_links
    description: >
      Hard-link the library video file back into torrents/<original_folder>/
      and copy all remaining files from the original download folder
      (subs, nfo, jpg, …) so the torrent stays complete for seeding.
 naming_convention:
  # Resolved by domain entities (Movie, Episode) — not hardcoded here
  tv_show: "{title}/Season {season:02d}/{title}.S{season:02d}E{episode:02d}.{ext}"
  movie: "{title} ({year})/{title}.{year}.{ext}"
@@ -15,7 +15,7 @@ from alfred.agent.agent import Agent
 from alfred.agent.llm.deepseek import DeepSeekClient
 from alfred.agent.llm.exceptions import LLMAPIError, LLMConfigurationError
 from alfred.agent.llm.ollama import OllamaClient
-from alfred.infrastructure.persistence_TO_CHECK import get_memory, init_memory
+from alfred.infrastructure.persistence import get_memory, init_memory
 from alfred.settings import settings
 logging.basicConfig(
@@ -29,7 +29,7 @@ app = FastAPI(
    version="0.2.0",
 )
-memory_path = Path(settings.data_storage_dir) / "memory"
+memory_path = Path(settings.data_storage) / "memory"
 init_memory(storage_dir=str(memory_path))
 logger.info(f"Memory context initialized (path: {memory_path})")
@@ -37,21 +37,6 @@ logger.info(f"Memory context initialized (path: {memory_path})")
 llm_provider = settings.default_llm_provider.lower()
 class _UnconfiguredLLM:
    """Placeholder LLM used when no provider could be configured at import time.
    Importing the FastAPI app must not fail just because credentials are
    absent (e.g. during test collection). Any actual call surfaces a clear
    503 error at request time via the handlers below.
    """
    def __init__(self, reason: str):
        self.reason = reason
    def complete(self, *args, **kwargs):
        raise LLMAPIError(f"LLM is not configured: {self.reason}")
 try:
    if llm_provider == "local":
        logger.info("Using local Ollama LLM")
@@ -64,11 +49,8 @@ try:
    else:
        raise ValueError(f"Unknown LLM provider: {llm_provider}")
 except LLMConfigurationError as e:
    # Degrade gracefully: keep the app importable so tests can patch agent.step
    # and so missing credentials surface as a 503 at the endpoint, not as an
    # import error.
    logger.error(f"Failed to initialize LLM: {e}")
-    llm = _UnconfiguredLLM(str(e))
+    raise
 # Initialize agent
 agent = Agent(
@@ -1,26 +0,0 @@
 """Application-layer exceptions shared across orchestrators.
 Kept in a dedicated module (rather than inside each orchestrator's
 file) because the sync flows for TV shows and movies raise structurally
 identical "not found in library" errors — pulling them out makes the
 shared semantics explicit and avoids cross-imports between the
 ``tv_shows`` and ``movies`` packages.
 """
 from __future__ import annotations
 class ShowNotFoundInLibrary(LookupError):
    """Raised when no on-disk TV show carries the requested ``tmdb_id``.
    The sync orchestrator raises this when both the library index and
    the per-show release repository return ``None`` for a lookup —
    there is nothing on disk to refresh TMDB facts against.
    """
 class MovieNotFoundInLibrary(LookupError):
    """Raised when no on-disk movie carries the requested ``tmdb_id``.
    Symmetric to :class:`ShowNotFoundInLibrary` for the movies library.
    """
@@ -1,42 +1,12 @@
-"""Filesystem application layer — 5 atomic use cases as free functions.
+"""Filesystem use cases."""
-Each use case:
+from .dto import ListFolderResponse, SetFolderPathResponse
- accepts :class:`pathlib.Path` inputs plus a :class:`DirectoryRoots` VO,
+from .list_folder import ListFolderUseCase
- guards inputs against escaping configured roots,
+from .set_folder_path import SetFolderPathUseCase
 - calls the matching infra op,
 - catches :class:`~alfred.infrastructure.filesystem.FilesystemError` and
  returns a frozen DTO with a normalized error code.
 No global state, no ``get_memory()``. Roots are injected.
 """
 from .create_dir import create_dir_use_case
 from .directory_roots import DirectoryRoots
 from .dto import (
    CreateDirResponse,
    LinkFileResponse,
    ListDirResponse,
    MoveDirResponse,
    MoveFileResponse,
 )
 from .link_file import link_file_use_case
 from .list_dir import list_dir_use_case
 from .move_dir import move_dir_use_case
 from .move_file import move_file_use_case
 __all__ = [
-    # use cases
+    "SetFolderPathUseCase",
-    "list_dir_use_case",
+    "ListFolderUseCase",
-    "create_dir_use_case",
+    "SetFolderPathResponse",
-    "link_file_use_case",
+    "ListFolderResponse",
    "move_file_use_case",
    "move_dir_use_case",
    # VO
    "DirectoryRoots",
    # DTOs
    "ListDirResponse",
    "CreateDirResponse",
    "LinkFileResponse",
    "MoveFileResponse",
    "MoveDirResponse",
 ]
@@ -1,41 +0,0 @@
 """Internal helpers: mapping infra exceptions → error codes.
 Kept private (``_errors``) — only the 5 use cases in this package use
 it. Centralizes the exception → code translation so every use case
 returns consistent error payloads.
 """
 from __future__ import annotations
 from alfred.infrastructure.filesystem import (
    CrossDevice,
    DestinationExists,
    FilesystemError,
    FilesystemOSError,
    NotADirectory,
    NotAFile,
    PermissionDenied,
    SourceNotFound,
 )
 # Application-layer error codes (guard violations, not infra).
 PATH_NOT_ALLOWED = "path_not_allowed"
 def code_for(exc: FilesystemError) -> str:
    """Return the snake-case error code for an infra exception."""
    if isinstance(exc, SourceNotFound):
        return "source_not_found"
    if isinstance(exc, DestinationExists):
        return "destination_exists"
    if isinstance(exc, NotADirectory):
        return "not_a_directory"
    if isinstance(exc, NotAFile):
        return "not_a_file"
    if isinstance(exc, PermissionDenied):
        return "permission_denied"
    if isinstance(exc, CrossDevice):
        return "cross_device"
    if isinstance(exc, FilesystemOSError):
        return "filesystem_os_error"
    return "filesystem_error"
@@ -1,33 +0,0 @@
 """create_dir use case — create a directory under one of the configured roots."""
 from __future__ import annotations
 from pathlib import Path
 from alfred.infrastructure.filesystem import FilesystemError, create_dir
 from ._errors import PATH_NOT_ALLOWED, code_for
 from .directory_roots import DirectoryRoots
 from .dto import CreateDirResponse
 def create_dir_use_case(path: Path, roots: DirectoryRoots) -> CreateDirResponse:
    """Create directory ``path`` (and any missing parents) provided it
    lives under one of the configured roots.
    Idempotent on the infra side: re-running on an existing directory
    returns ``status="ok"``.
    """
    if not roots.contains(path):
        return CreateDirResponse(
            status="error",
            error=PATH_NOT_ALLOWED,
            message=f"Path is outside configured roots: {path}",
        )
    try:
        create_dir(path)
    except FilesystemError as e:
        return CreateDirResponse(status="error", error=code_for(e), message=str(e))
    return CreateDirResponse(status="ok", path=path)
@@ -1,54 +0,0 @@
 """CreateSeedLinksUseCase — prepares a torrent folder for continued seeding."""
 import logging
 from alfred.infrastructure.filesystem import FileManager
 from alfred.infrastructure.persistence_TO_CHECK import get_memory
 from .dto import CreateSeedLinksResponse
 logger = logging.getLogger(__name__)
 class CreateSeedLinksUseCase:
    """
    Prepares a torrent subfolder so qBittorrent can keep seeding after a move.
    Hard-links the video file from the library back into torrents/<original_folder>/,
    then copies all remaining files from the original download folder (subs, nfo, …).
    """
    def __init__(self, file_manager: FileManager):
        self.file_manager = file_manager
    def execute(
        self, library_file: str, original_download_folder: str
    ) -> CreateSeedLinksResponse:
        memory = get_memory()
        torrent_folder = memory.ltm.workspace.torrent
        if not torrent_folder:
            return CreateSeedLinksResponse(
                status="error",
                error="torrent_folder_not_set",
                message="Torrent folder is not configured. Use set_path_for_folder to set it.",
            )
        result = self.file_manager.create_seed_links(
            library_file, original_download_folder, torrent_folder
        )
        if result.get("status") == "ok":
            return CreateSeedLinksResponse(
                status="ok",
                torrent_subfolder=result.get("torrent_subfolder"),
                linked_file=result.get("linked_file"),
                copied_files=result.get("copied_files"),
                copied_count=result.get("copied_count", 0),
                skipped=result.get("skipped"),
            )
        return CreateSeedLinksResponse(
            status="error",
            error=result.get("error"),
            message=result.get("message"),
        )
@@ -1,56 +0,0 @@
 """DirectoryRoots — VO carrying the configured filesystem roots.
 Replaces the ad-hoc ``get_memory().ltm.workspace.<x>`` lookups that were
 sprinkled across the filesystem use cases. By making roots an explicit
 input, use cases become pure (no global state read) and easy to test.
 The roots are read once at the tool wrapper boundary (where the agent
 config lives) and threaded through the use cases.
 """
 from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path
@dataclass(frozen=True)
 class DirectoryRoots:
    """Configured roots of Alfred's filesystem.
    All paths must be absolute and existing directories — validation is
    expected at the boundary that builds this VO.
    Attributes:
        downloads: where qBittorrent drops finished torrents.
        torrents: where seeding hard-links live (mirrors downloads/).
        movies: library root for movies.
        tv_shows: library root for TV shows.
    """
    downloads: Path
    torrents: Path
    movies: Path
    tv_shows: Path
    def all(self) -> tuple[Path, ...]:
        """Return every configured root, in declaration order."""
        return (self.downloads, self.torrents, self.movies, self.tv_shows)
    def contains(self, path: Path) -> bool:
        """Return True if ``path`` is inside one of the configured roots.
        Uses ``Path.resolve()`` to handle symlinks and ``..`` segments,
        then ``relative_to`` for an exact within-root check.
        """
        try:
            resolved = path.resolve()
        except OSError:
            return False
        for root in self.all():
            try:
                resolved.relative_to(root.resolve())
                return True
            except (ValueError, OSError):
                continue
        return False
@@ -1,111 +1,61 @@
-"""DTOs for the 5 atomic filesystem use cases.
+"""Filesystem application DTOs."""
-Each use case returns a small frozen dataclass tagged with a ``status``
+from dataclasses import dataclass
 field. On error, ``error`` (machine-readable code) and ``message``
 (human-readable) are populated; on success, the relevant payload
 fields are.
 Error codes mirror the infrastructure exception types (lowercased,
 snake-cased) — e.g. ``SourceNotFound`` → ``"source_not_found"`` — plus
 the application-layer ``"path_not_allowed"`` for guard violations.
 """
 from __future__ import annotations
 from dataclasses import dataclass, field
 from pathlib import Path
-@dataclass(frozen=True)
+@dataclass
-class ListDirResponse:
+class SetFolderPathResponse:
-    """Response from ``list_dir_use_case``."""
+    """Response from setting a folder path."""
    status: str  # "ok" | "error"
    path: Path | None = None
    entries: tuple[Path, ...] = ()
    error: str | None = None
    message: str | None = None
    def to_dict(self) -> dict:
        if self.error:
            return {"status": self.status, "error": self.error, "message": self.message}
        return {
            "status": self.status,
            "path": str(self.path) if self.path else None,
            "entries": [str(p) for p in self.entries],
        }
@dataclass(frozen=True)
 class CreateDirResponse:
    """Response from ``create_dir_use_case``."""
    status: str
-    path: Path | None = None
+    folder_name: str | None = None
    path: str | None = None
    error: str | None = None
    message: str | None = None
-    def to_dict(self) -> dict:
+    def to_dict(self):
        """Convert to dict for agent compatibility."""
        result = {"status": self.status}
        if self.error:
-            return {"status": self.status, "error": self.error, "message": self.message}
+            result["error"] = self.error
-        return {"status": self.status, "path": str(self.path) if self.path else None}
+            result["message"] = self.message
        else:
            if self.folder_name:
                result["folder_name"] = self.folder_name
            if self.path:
                result["path"] = self.path
        return result
-@dataclass(frozen=True)
+@dataclass
-class LinkFileResponse:
+class ListFolderResponse:
-    """Response from ``link_file_use_case``."""
+    """Response from listing a folder."""
    status: str
-    source: Path | None = None
+    folder_type: str | None = None
-    destination: Path | None = None
+    path: str | None = None
    entries: list[str] | None = None
    count: int | None = None
    error: str | None = None
    message: str | None = None
-    def to_dict(self) -> dict:
+    def to_dict(self):
        """Convert to dict for agent compatibility."""
        result = {"status": self.status}
        if self.error:
-            return {"status": self.status, "error": self.error, "message": self.message}
+            result["error"] = self.error
-        return {
+            result["message"] = self.message
-            "status": self.status,
+        else:
-            "source": str(self.source) if self.source else None,
+            if self.folder_type:
-            "destination": str(self.destination) if self.destination else None,
+                result["folder_type"] = self.folder_type
-        }
+            if self.path:
                result["path"] = self.path
            if self.entries is not None:
                result["entries"] = self.entries
            if self.count is not None:
                result["count"] = self.count
-
+        return result
@dataclass(frozen=True)
 class MoveFileResponse:
    """Response from ``move_file_use_case``."""
    status: str
    source: Path | None = None
    destination: Path | None = None
    error: str | None = None
    message: str | None = None
    def to_dict(self) -> dict:
        if self.error:
            return {"status": self.status, "error": self.error, "message": self.message}
        return {
            "status": self.status,
            "source": str(self.source) if self.source else None,
            "destination": str(self.destination) if self.destination else None,
        }
@dataclass(frozen=True)
 class MoveDirResponse:
    """Response from ``move_dir_use_case``."""
    status: str
    source: Path | None = None
    destination: Path | None = None
    error: str | None = None
    message: str | None = None
    def to_dict(self) -> dict:
        if self.error:
            return {"status": self.status, "error": self.error, "message": self.message}
        return {
            "status": self.status,
            "source": str(self.source) if self.source else None,
            "destination": str(self.destination) if self.destination else None,
        }
@@ -1,188 +0,0 @@
 """Filesystem application DTOs."""
 from __future__ import annotations
 from dataclasses import dataclass
@dataclass
 class CopyMediaResponse:
    """Response from copying a media file."""
    status: str
    source: str | None = None
    destination: str | None = None
    filename: str | None = None
    size: int | None = None
    error: str | None = None
    message: str | None = None
    def to_dict(self) -> dict:
        if self.error:
            return {"status": self.status, "error": self.error, "message": self.message}
        return {
            "status": self.status,
            "source": self.source,
            "destination": self.destination,
            "filename": self.filename,
            "size": self.size,
        }
@dataclass
 class MoveMediaResponse:
    """Response from moving a media file."""
    status: str
    source: str | None = None
    destination: str | None = None
    filename: str | None = None
    size: int | None = None
    error: str | None = None
    message: str | None = None
    def to_dict(self) -> dict:
        if self.error:
            return {"status": self.status, "error": self.error, "message": self.message}
        return {
            "status": self.status,
            "source": self.source,
            "destination": self.destination,
            "filename": self.filename,
            "size": self.size,
        }
@dataclass
 class PlacedSubtitle:
    """One subtitle file successfully placed."""
    source: str
    destination: str
    filename: str
    def to_dict(self) -> dict:
        return {
            "source": self.source,
            "destination": self.destination,
            "filename": self.filename,
        }
@dataclass
 class UnresolvedTrack:
    """A subtitle track that needs agent clarification before placement."""
    raw_tokens: list[str]
    file_path: str | None = None
    file_size_kb: float | None = None
    reason: str = ""  # "unknown_language" | "low_confidence"
    def to_dict(self) -> dict:
        return {
            "raw_tokens": self.raw_tokens,
            "file_path": self.file_path,
            "file_size_kb": self.file_size_kb,
            "reason": self.reason,
        }
@dataclass
 class AvailableSubtitle:
    """One subtitle track available on an embedded media item."""
    language: str  # ISO 639-2 code
    subtitle_type: str  # "standard" | "sdh" | "forced" | "unknown"
    def to_dict(self) -> dict:
        return {"language": self.language, "type": self.subtitle_type}
@dataclass
 class ManageSubtitlesResponse:
    """Response from the manage_subtitles use case."""
    status: str  # "ok" | "needs_clarification" | "error"
    video_path: str | None = None
    placed: list[PlacedSubtitle] | None = None
    skipped_count: int = 0
    unresolved: list[UnresolvedTrack] | None = None
    available: list[AvailableSubtitle] | None = None  # embedded tracks summary
    error: str | None = None
    message: str | None = None
    def to_dict(self) -> dict:
        if self.error:
            return {"status": self.status, "error": self.error, "message": self.message}
        result = {
            "status": self.status,
            "video_path": self.video_path,
            "placed": [p.to_dict() for p in (self.placed or [])],
            "placed_count": len(self.placed or []),
            "skipped_count": self.skipped_count,
        }
        if self.unresolved:
            result["unresolved"] = [u.to_dict() for u in self.unresolved]
            result["unresolved_count"] = len(self.unresolved)
        if self.available:
            result["available"] = [a.to_dict() for a in self.available]
        return result
@dataclass
 class CreateSeedLinksResponse:
    """Response from creating seed links for a torrent."""
    status: str
    torrent_subfolder: str | None = None
    linked_file: str | None = None
    copied_files: list[str] | None = None
    copied_count: int = 0
    skipped: list[str] | None = None
    error: str | None = None
    message: str | None = None
    def to_dict(self) -> dict:
        if self.error:
            return {"status": self.status, "error": self.error, "message": self.message}
        return {
            "status": self.status,
            "torrent_subfolder": self.torrent_subfolder,
            "linked_file": self.linked_file,
            "copied_files": self.copied_files or [],
            "copied_count": self.copied_count,
            "skipped": self.skipped or [],
        }
@dataclass
 class ListFolderResponse:
    """Response from listing a folder."""
    status: str
    folder_type: str | None = None # SHOULD BE A PROPERTY
    path: str | None = None # NOT NONE - Should be path
    entries: list[str] | None = None # NOT NONE - Empty list of path
    count: int | None = None # USELESS
    error: str | None = None
    message: str | None = None
    def to_dict(self):
        """Convert to dict for agent compatibility."""
        result = {"status": self.status}
        if self.error:
            result["error"] = self.error
            result["message"] = self.message
        else:
            if self.folder_type:
                result["folder_type"] = self.folder_type
            if self.path:
                result["path"] = self.path
            if self.entries is not None:
                result["entries"] = self.entries
            if self.count is not None:
                result["count"] = self.count
        return result
@@ -1,40 +0,0 @@
 """link_file use case — hard-link a file from one root to another."""
 from __future__ import annotations
 from pathlib import Path
 from alfred.infrastructure.filesystem import FilesystemError, link_file
 from ._errors import PATH_NOT_ALLOWED, code_for
 from .directory_roots import DirectoryRoots
 from .dto import LinkFileResponse
 def link_file_use_case(
    src: Path, dst: Path, roots: DirectoryRoots
 ) -> LinkFileResponse:
    """Hard-link ``src`` to ``dst``. Both must be under configured roots.
    The destination parent must already exist — the caller is expected
    to have created it via ``create_dir_use_case`` if needed.
    """
    if not roots.contains(src):
        return LinkFileResponse(
            status="error",
            error=PATH_NOT_ALLOWED,
            message=f"Source is outside configured roots: {src}",
        )
    if not roots.contains(dst):
        return LinkFileResponse(
            status="error",
            error=PATH_NOT_ALLOWED,
            message=f"Destination is outside configured roots: {dst}",
        )
    try:
        link_file(src, dst)
    except FilesystemError as e:
        return LinkFileResponse(status="error", error=code_for(e), message=str(e))
    return LinkFileResponse(status="ok", source=src, destination=dst)
@@ -1,34 +0,0 @@
 """list_dir use case — list a directory after guarding it within roots."""
 from __future__ import annotations
 from pathlib import Path
 from alfred.infrastructure.filesystem import FilesystemError, list_dir
 from ._errors import PATH_NOT_ALLOWED, code_for
 from .directory_roots import DirectoryRoots
 from .dto import ListDirResponse
 def list_dir_use_case(path: Path, roots: DirectoryRoots) -> ListDirResponse:
    """List the immediate children of ``path`` if it lives under one of
    the configured roots.
    Returns a :class:`ListDirResponse`. On guard failure, status is
    ``"error"`` with ``error="path_not_allowed"``. On infra failure,
    status is ``"error"`` with a code mapped from the raised exception.
    """
    if not roots.contains(path):
        return ListDirResponse(
            status="error",
            error=PATH_NOT_ALLOWED,
            message=f"Path is outside configured roots: {path}",
        )
    try:
        entries = list_dir(path)
    except FilesystemError as e:
        return ListDirResponse(status="error", error=code_for(e), message=str(e))
    return ListDirResponse(status="ok", path=path, entries=tuple(entries))
@@ -1,308 +0,0 @@
 """ManageSubtitlesUseCase — orchestrates the full subtitle pipeline for a video file."""
 import logging
 from pathlib import Path
 from alfred.application.subtitles_TO_CHECK.placer import (
    PlacedTrack,
    SubtitlePlacer,
    _build_dest_name,
 )
 from alfred.domain.shared_TO_CHECK.value_objects import ImdbId
 from alfred.domain.subtitles_TO_CHECK.entities import SubtitleScanResult
 from alfred.domain.subtitles_TO_CHECK.services.identifier import SubtitleIdentifier
 from alfred.domain.subtitles_TO_CHECK.services.matcher import SubtitleMatcher
 from alfred.domain.subtitles_TO_CHECK.services.pattern_detector import PatternDetector
 from alfred.domain.subtitles_TO_CHECK.services.utils import available_subtitles
 from alfred.domain.subtitles_TO_CHECK.value_objects import ScanStrategy
 from alfred.infrastructure.filesystem.scanner import PathlibFilesystemScanner
 from alfred.infrastructure.knowledge_TO_CHECK.subtitles.base import SubtitleKnowledgeBase
 from alfred.infrastructure.knowledge_TO_CHECK.subtitles.loader import KnowledgeLoader
 from alfred.infrastructure.persistence_TO_CHECK.context import get_memory
 from alfred.infrastructure.probe_TO_CHECK.ffprobe_prober import FfprobeMediaProber
 from alfred.infrastructure.subtitle_TO_CHECK.metadata_store import SubtitleMetadataStore
 from alfred.infrastructure.subtitle_TO_CHECK.rule_repository import RuleSetRepository
 from .dto import (
    AvailableSubtitle,
    ManageSubtitlesResponse,
    PlacedSubtitle,
    UnresolvedTrack,
 )
 logger = logging.getLogger(__name__)
 def _infer_library_root(dest_video: Path, media_type: str) -> Path:
    """
    Infer the media library root folder from the destination video path.
    TV show:  video → Season 01 → The X-Files   (3 levels up)
    Movie:    video → Inception (2010)           (1 level up)
    """
    if media_type == "tv_show":
        return dest_video.parent.parent
    return dest_video.parent
 def _to_imdb_id(raw: str | None) -> ImdbId | None:
    if not raw:
        return None
    try:
        return ImdbId(raw)
    except Exception:
        return None
 class ManageSubtitlesUseCase:
    """
    Full subtitle pipeline:
    1. Load knowledge base
    2. Detect (or confirm) the release pattern
    3. Identify all tracks (ffprobe + filesystem scan)
    4. Load + resolve rules for this media
    5. Match tracks against rules
    6. If any tracks are unresolved → return needs_clarification (don't place yet)
    7. Place matched tracks via hard-link
    8. Persist to .alfred/metadata.yaml
    The use case is stateless — all dependencies are instantiated inline.
    """
    def execute(
        self,
        source_video: str,
        destination_video: str,
        imdb_id: str | None = None,
        media_type: str = "tv_show",
        release_group: str | None = None,
        season: int | None = None,
        episode: int | None = None,
        confirmed_pattern_id: str | None = None,
        dry_run: bool = False,
    ) -> ManageSubtitlesResponse:
        source_path = Path(source_video)
        dest_path = Path(destination_video)
        if not source_path.exists() and not source_path.parent.exists():
            return ManageSubtitlesResponse(
                status="error",
                error="source_not_found",
                message=f"Source video not found: {source_video}",
            )
        kb = SubtitleKnowledgeBase(KnowledgeLoader())
        prober = FfprobeMediaProber()
        scanner = PathlibFilesystemScanner()
        library_root = _infer_library_root(dest_path, media_type)
        store = SubtitleMetadataStore(library_root)
        repo = RuleSetRepository(library_root)
        # --- Pattern resolution ---
        pattern = self._resolve_pattern(
            kb,
            prober,
            scanner,
            store,
            source_path,
            confirmed_pattern_id,
            release_group,
        )
        if pattern is None:
            return ManageSubtitlesResponse(
                status="error",
                error="pattern_not_found",
                message="Could not determine subtitle pattern for this release.",
            )
        # --- Identify ---
        media_id = _to_imdb_id(imdb_id)
        identifier = SubtitleIdentifier(kb, prober, scanner)
        metadata = identifier.identify(
            video_path=source_path,
            pattern=pattern,
            media_id=media_id,
            media_type=media_type,
            release_group=release_group,
        )
        if metadata.total_count == 0:
            logger.info(
                f"ManageSubtitles: no subtitle tracks found for {source_path.name}"
            )
            return ManageSubtitlesResponse(
                status="ok",
                video_path=destination_video,
                placed=[],
                skipped_count=0,
            )
        # --- Embedded short-circuit ---
        if pattern.scan_strategy == ScanStrategy.EMBEDDED:
            logger.info("ManageSubtitles: embedded pattern — skipping matcher")
            available = [
                AvailableSubtitle(
                    language=t.language.code if t.language else "?",
                    subtitle_type=t.subtitle_type.value,
                )
                for t in available_subtitles(metadata.embedded_tracks)
            ]
            return ManageSubtitlesResponse(
                status="ok",
                video_path=destination_video,
                placed=[],
                skipped_count=0,
                available=available,
            )
        # --- Match (external only) ---
        subtitle_prefs = None
        try:
            memory = get_memory()
            subtitle_prefs = memory.ltm.subtitle_preferences
        except Exception:
            pass
        rules = repo.load(release_group, subtitle_prefs).resolve(kb.default_rules())
        matcher = SubtitleMatcher()
        matched, unresolved = matcher.match(metadata.external_tracks, rules)
        if unresolved:
            logger.info(
                f"ManageSubtitles: {len(unresolved)} unresolved track(s) — needs clarification"
            )
            return ManageSubtitlesResponse(
                status="needs_clarification",
                video_path=destination_video,
                placed=[],
                unresolved=[_to_unresolved_dto(t) for t in unresolved],
            )
        if not matched:
            return ManageSubtitlesResponse(
                status="ok",
                video_path=destination_video,
                placed=[],
                skipped_count=metadata.total_count,
            )
        # --- Dry run: skip placement ---
        if dry_run:
            placed_dtos = []
            for t in matched:
                if not t.file_path:
                    continue
                try:
                    filename = _build_dest_name(t, dest_path.stem)
                except ValueError:
                    continue
                placed_dtos.append(
                    PlacedSubtitle(
                        source=str(t.file_path),
                        destination=str(dest_path.parent / filename),
                        filename=filename,
                    )
                )
            return ManageSubtitlesResponse(
                status="ok",
                video_path=destination_video,
                placed=placed_dtos,
                skipped_count=0,
            )
        # --- Place ---
        placer = SubtitlePlacer()
        place_result = placer.place(matched, dest_path)
        # --- Persist ---
        if place_result.placed:
            pairs = _pair_placed_with_tracks(place_result.placed, matched)
            store.append_history(pairs, season, episode, release_group)
        placed_dtos = [
            PlacedSubtitle(
                source=str(p.source),
                destination=str(p.destination),
                filename=p.filename,
            )
            for p in place_result.placed
        ]
        return ManageSubtitlesResponse(
            status="ok",
            video_path=destination_video,
            placed=placed_dtos,
            skipped_count=place_result.skipped_count,
        )
    def _resolve_pattern(
        self,
        kb: SubtitleKnowledgeBase,
        prober: FfprobeMediaProber,
        scanner: PathlibFilesystemScanner,
        store: SubtitleMetadataStore,
        source_path: Path,
        confirmed_pattern_id: str | None,
        release_group: str | None,
    ):
        # 1. Explicit override from caller
        if confirmed_pattern_id:
            p = kb.pattern(confirmed_pattern_id)
            if p:
                return p
            logger.warning(f"ManageSubtitles: unknown pattern '{confirmed_pattern_id}'")
        # 2. Previously confirmed in metadata store
        stored_id = store.confirmed_pattern()
        if stored_id:
            p = kb.pattern(stored_id)
            if p:
                logger.debug(f"ManageSubtitles: using confirmed pattern '{stored_id}'")
                return p
        # 3. Auto-detect
        release_root = source_path.parent
        detector = PatternDetector(kb, prober, scanner)
        result = detector.detect(release_root, source_path)
        if result["detected"] and result["confidence"] >= 0.6:
            logger.info(
                f"ManageSubtitles: auto-detected pattern '{result['detected'].id}' "
                f"(confidence={result['confidence']:.2f})"
            )
            return result["detected"]
        # 4. Fallback — adjacent (safest default)
        logger.info("ManageSubtitles: falling back to 'adjacent' pattern")
        return kb.pattern("adjacent")
 def _to_unresolved_dto(
    track: SubtitleScanResult, min_confidence: float = 0.7
 ) -> UnresolvedTrack:
    reason = "unknown_language" if track.language is None else "low_confidence"
    return UnresolvedTrack(
        raw_tokens=track.raw_tokens,
        file_path=str(track.file_path) if track.file_path else None,
        file_size_kb=track.file_size_kb,
        reason=reason,
    )
 def _pair_placed_with_tracks(
    placed: list[PlacedTrack],
    tracks: list[SubtitleScanResult],
 ) -> list[tuple[PlacedTrack, SubtitleScanResult]]:
    """
    Pair each PlacedTrack with its originating SubtitleScanResult by source path.
    Falls back to positional matching if paths don't align.
    """
    track_by_path = {t.file_path: t for t in tracks if t.file_path}
    pairs = []
    for p in placed:
        track = track_by_path.get(p.source)
        if track is None and tracks:
            track = tracks[0]  # positional fallback
        if track:
            pairs.append((p, track))
    return pairs
@@ -1,36 +0,0 @@
 """move_dir use case — move a directory tree between configured roots."""
 from __future__ import annotations
 from pathlib import Path
 from alfred.infrastructure.filesystem import FilesystemError, move_dir
 from ._errors import PATH_NOT_ALLOWED, code_for
 from .directory_roots import DirectoryRoots
 from .dto import MoveDirResponse
 def move_dir_use_case(
    src: Path, dst: Path, roots: DirectoryRoots
 ) -> MoveDirResponse:
    """Move directory ``src`` to ``dst``. Both must be under configured roots."""
    if not roots.contains(src):
        return MoveDirResponse(
            status="error",
            error=PATH_NOT_ALLOWED,
            message=f"Source is outside configured roots: {src}",
        )
    if not roots.contains(dst):
        return MoveDirResponse(
            status="error",
            error=PATH_NOT_ALLOWED,
            message=f"Destination is outside configured roots: {dst}",
        )
    try:
        move_dir(src, dst)
    except FilesystemError as e:
        return MoveDirResponse(status="error", error=code_for(e), message=str(e))
    return MoveDirResponse(status="ok", source=src, destination=dst)
@@ -1,36 +0,0 @@
 """move_file use case — move a file between configured roots."""
 from __future__ import annotations
 from pathlib import Path
 from alfred.infrastructure.filesystem import FilesystemError, move_file
 from ._errors import PATH_NOT_ALLOWED, code_for
 from .directory_roots import DirectoryRoots
 from .dto import MoveFileResponse
 def move_file_use_case(
    src: Path, dst: Path, roots: DirectoryRoots
 ) -> MoveFileResponse:
    """Move file ``src`` to ``dst``. Both must be under configured roots."""
    if not roots.contains(src):
        return MoveFileResponse(
            status="error",
            error=PATH_NOT_ALLOWED,
            message=f"Source is outside configured roots: {src}",
        )
    if not roots.contains(dst):
        return MoveFileResponse(
            status="error",
            error=PATH_NOT_ALLOWED,
            message=f"Destination is outside configured roots: {dst}",
        )
    try:
        move_file(src, dst)
    except FilesystemError as e:
        return MoveFileResponse(status="error", error=code_for(e), message=str(e))
    return MoveFileResponse(status="ok", source=src, destination=dst)
@@ -1,43 +0,0 @@
 """Move media use case."""
 import logging
 from alfred.infrastructure.filesystem import FileManager
 from .dto import MoveMediaResponse
 logger = logging.getLogger(__name__)
 class MoveMediaUseCase:
    """Use case for moving a media file to a destination (copy + delete source)."""
    def __init__(self, file_manager: FileManager):
        self.file_manager = file_manager
    def execute(self, source: str, destination: str) -> MoveMediaResponse:
        """
        Move a media file from source to destination.
        Args:
            source: Absolute path to the source file.
            destination: Absolute path to the destination file.
        Returns:
            MoveMediaResponse with success or error information.
        """
        result = self.file_manager.move_file(source, destination)
        if result.get("status") == "ok":
            return MoveMediaResponse(
                status="ok",
                source=result.get("source"),
                destination=result.get("destination"),
                filename=result.get("filename"),
                size=result.get("size"),
            )
        return MoveMediaResponse(
            status="error",
            error=result.get("error"),
            message=result.get("message"),
        )
@@ -1,464 +0,0 @@
 """
 Destination resolution — compute library paths for releases.
 Four distinct use cases, one per release type:
 - resolve_season_destination    : season pack (folder move)
 - resolve_episode_destination   : single episode (file move)
 - resolve_movie_destination     : movie (file move)
 - resolve_series_destination    : complete series multi-season pack (folder move)
 Each returns a dedicated DTO with only the fields that make sense for that type.
 These use cases follow Option B of the snapshot-VO design: ``ParsedRelease``
 arrives with ``title_sanitized`` already computed, and TMDB-supplied strings
 are sanitized **at the use-case boundary** (here) before being passed into
 ``ParsedRelease`` builder methods. The builders themselves perform no I/O and
 no sanitization.
 """
 from __future__ import annotations
 import logging
 from dataclasses import dataclass
 from pathlib import Path
 from alfred.application.release_TO_CHECK import inspect_release
 from alfred.domain.release import parse_release
 from alfred.domain.releases_TO_CHECK.ports import ReleaseKnowledge
 from alfred.domain.release.value_objects import ParsedRelease
 from alfred.domain.shared_TO_CHECK.ports import MediaProber
 from alfred.infrastructure.persistence_TO_CHECK import get_memory
 logger = logging.getLogger(__name__)
 def _resolve_parsed(
    release_name: str,
    source_path: str | None,
    kb: ReleaseKnowledge,
    prober: MediaProber,
 ) -> ParsedRelease:
    """Pick the right entry point depending on whether we have a path.
    When ``source_path`` is provided and points to something that exists,
    we run the full inspection pipeline so probe data can refresh tech
    fields (which feed every filename builder). Otherwise we fall back
    to a parse-only path — same behavior as before.
    """
    if source_path:
        path = Path(source_path)
        if path.exists():
            return inspect_release(release_name, path, kb, prober).parsed
    parsed, _ = parse_release(release_name, kb)
    return parsed
 def _find_existing_tvshow_folders(
    tv_root: Path, tmdb_title_safe: str, tmdb_year: int
 ) -> list[str]:
    """Return folder names in tv_root that match title + year prefix."""
    if not tv_root.exists():
        return []
    clean_title = tmdb_title_safe.replace(" ", ".")
    prefix = f"{clean_title}.{tmdb_year}".lower()
    return sorted(
        entry.name
        for entry in tv_root.iterdir()
        if entry.is_dir() and entry.name.lower().startswith(prefix)
    )
 def _get_tv_root() -> Path | None:
    memory = get_memory()
    tv_root = memory.ltm.library_paths.get("tv_show")
    return Path(tv_root) if tv_root else None
 # ---------------------------------------------------------------------------
 # Internal sentinel + series-folder resolver (shared by the 3 TV use cases)
 # ---------------------------------------------------------------------------
@dataclass
 class _Clarification:
    """Module-private sentinel signalling that user input is needed."""
    question: str
    options: list[str]
 def _resolve_series_folder(
    tv_root: Path,
    tmdb_title: str,
    tmdb_title_safe: str,
    tmdb_year: int,
    computed_name: str,
    confirmed_folder: str | None,
 ) -> tuple[str, bool] | _Clarification:
    """
    Resolve which series folder to use.
    Returns:
        (folder_name, is_new) if resolved unambiguously,
        _Clarification(question, options) if the caller must ask the user.
    """
    if confirmed_folder:
        return confirmed_folder, not (tv_root / confirmed_folder).exists()
    existing = _find_existing_tvshow_folders(tv_root, tmdb_title_safe, tmdb_year)
    if not existing:
        return computed_name, True
    if len(existing) == 1 and existing[0] == computed_name:
        return existing[0], False
    options = existing + ([computed_name] if computed_name not in existing else [])
    return _Clarification(
        question=(
            f"Un dossier série existe déjà pour '{tmdb_title}' "
            f"mais son nom diffère du nom calculé ({computed_name}). "
            f"Lequel utiliser ?"
        ),
        options=options,
    )
 # ---------------------------------------------------------------------------
 # DTOs
 # ---------------------------------------------------------------------------
@dataclass
 class _ResolvedDestinationBase:
    """
    Shared shape across all resolution DTOs.
    Holds the status flag and the fields used in non-ok states
    (error / needs_clarification). Subclasses add their own ok-state fields
    and a to_dict() that delegates the non-ok cases via _base_dict().
    """
    status: str  # "ok" | "needs_clarification" | "error"
    # needs_clarification
    question: str | None = None
    options: list[str] | None = None
    # error
    error: str | None = None
    message: str | None = None
    def _base_dict(self) -> dict | None:
        """Return the dict for error/needs_clarification, or None for ok."""
        if self.status == "error":
            return {"status": self.status, "error": self.error, "message": self.message}
        if self.status == "needs_clarification":
            return {
                "status": self.status,
                "question": self.question,
                "options": self.options or [],
            }
        return None
@dataclass
 class ResolvedSeasonDestination(_ResolvedDestinationBase):
    """Paths for a season pack — folder move, no individual file paths."""
    series_folder: str | None = None
    season_folder: str | None = None
    series_folder_name: str | None = None
    season_folder_name: str | None = None
    is_new_series_folder: bool = False
    def to_dict(self) -> dict:
        return self._base_dict() or {
            "status": self.status,
            "series_folder": self.series_folder,
            "season_folder": self.season_folder,
            "series_folder_name": self.series_folder_name,
            "season_folder_name": self.season_folder_name,
            "is_new_series_folder": self.is_new_series_folder,
        }
@dataclass
 class ResolvedEpisodeDestination(_ResolvedDestinationBase):
    """Paths for a single episode — file move."""
    series_folder: str | None = None
    season_folder: str | None = None
    library_file: str | None = None  # full path to destination .mkv
    series_folder_name: str | None = None
    season_folder_name: str | None = None
    filename: str | None = None
    is_new_series_folder: bool = False
    def to_dict(self) -> dict:
        return self._base_dict() or {
            "status": self.status,
            "series_folder": self.series_folder,
            "season_folder": self.season_folder,
            "library_file": self.library_file,
            "series_folder_name": self.series_folder_name,
            "season_folder_name": self.season_folder_name,
            "filename": self.filename,
            "is_new_series_folder": self.is_new_series_folder,
        }
@dataclass
 class ResolvedMovieDestination(_ResolvedDestinationBase):
    """Paths for a movie — file move."""
    movie_folder: str | None = None
    library_file: str | None = None
    movie_folder_name: str | None = None
    filename: str | None = None
    is_new_folder: bool = False
    def to_dict(self) -> dict:
        return self._base_dict() or {
            "status": self.status,
            "movie_folder": self.movie_folder,
            "library_file": self.library_file,
            "movie_folder_name": self.movie_folder_name,
            "filename": self.filename,
            "is_new_folder": self.is_new_folder,
        }
@dataclass
 class ResolvedSeriesDestination(_ResolvedDestinationBase):
    """Paths for a complete multi-season series pack — folder move."""
    series_folder: str | None = None
    series_folder_name: str | None = None
    is_new_series_folder: bool = False
    def to_dict(self) -> dict:
        return self._base_dict() or {
            "status": self.status,
            "series_folder": self.series_folder,
            "series_folder_name": self.series_folder_name,
            "is_new_series_folder": self.is_new_series_folder,
        }
 # ---------------------------------------------------------------------------
 # Use cases
 # ---------------------------------------------------------------------------
 def resolve_season_destination(
    release_name: str,
    tmdb_title: str,
    tmdb_year: int,
    kb: ReleaseKnowledge,
    prober: MediaProber,
    confirmed_folder: str | None = None,
    source_path: str | None = None,
 ) -> ResolvedSeasonDestination:
    """
    Compute destination paths for a season pack.
    Returns series_folder + season_folder. No file paths — the whole
    source folder is moved as-is into season_folder.
    When ``source_path`` points to the release on disk, the parser is
    augmented with ffprobe data so tech tokens missing from the release
    name (quality / codec) end up in the folder names.
    """
    tv_root = _get_tv_root()
    if not tv_root:
        return ResolvedSeasonDestination(
            status="error",
            error="library_not_set",
            message="TV show library path is not configured.",
        )
    parsed = _resolve_parsed(release_name, source_path, kb, prober)
    tmdb_title_safe = kb.sanitize_for_fs(tmdb_title)
    computed_name = parsed.show_folder_name(tmdb_title_safe, tmdb_year)
    resolved = _resolve_series_folder(
        tv_root, tmdb_title, tmdb_title_safe, tmdb_year, computed_name, confirmed_folder
    )
    if isinstance(resolved, _Clarification):
        return ResolvedSeasonDestination(
            status="needs_clarification",
            question=resolved.question,
            options=resolved.options,
        )
    series_folder_name, is_new = resolved
    season_folder_name = parsed.season_folder_name()
    series_path = tv_root / series_folder_name
    season_path = series_path / season_folder_name
    return ResolvedSeasonDestination(
        status="ok",
        series_folder=str(series_path),
        season_folder=str(season_path),
        series_folder_name=series_folder_name,
        season_folder_name=season_folder_name,
        is_new_series_folder=is_new,
    )
 def resolve_episode_destination(
    release_name: str,
    source_file: str,
    tmdb_title: str,
    tmdb_year: int,
    kb: ReleaseKnowledge,
    prober: MediaProber,
    tmdb_episode_title: str | None = None,
    confirmed_folder: str | None = None,
 ) -> ResolvedEpisodeDestination:
    """
    Compute destination paths for a single episode file.
    Returns series_folder + season_folder + library_file (full path to .mkv).
    ``source_file`` doubles as the inspection target — when it exists,
    ffprobe enrichment refreshes tech tokens missing from the release name.
    """
    tv_root = _get_tv_root()
    if not tv_root:
        return ResolvedEpisodeDestination(
            status="error",
            error="library_not_set",
            message="TV show library path is not configured.",
        )
    parsed = _resolve_parsed(release_name, source_file, kb, prober)
    ext = Path(source_file).suffix
    tmdb_title_safe = kb.sanitize_for_fs(tmdb_title)
    tmdb_episode_title_safe = (
        kb.sanitize_for_fs(tmdb_episode_title) if tmdb_episode_title else None
    )
    computed_name = parsed.show_folder_name(tmdb_title_safe, tmdb_year)
    resolved = _resolve_series_folder(
        tv_root, tmdb_title, tmdb_title_safe, tmdb_year, computed_name, confirmed_folder
    )
    if isinstance(resolved, _Clarification):
        return ResolvedEpisodeDestination(
            status="needs_clarification",
            question=resolved.question,
            options=resolved.options,
        )
    series_folder_name, is_new = resolved
    season_folder_name = parsed.season_folder_name()
    filename = parsed.episode_filename(tmdb_episode_title_safe, ext)
    series_path = tv_root / series_folder_name
    season_path = series_path / season_folder_name
    file_path = season_path / filename
    return ResolvedEpisodeDestination(
        status="ok",
        series_folder=str(series_path),
        season_folder=str(season_path),
        library_file=str(file_path),
        series_folder_name=series_folder_name,
        season_folder_name=season_folder_name,
        filename=filename,
        is_new_series_folder=is_new,
    )
 def resolve_movie_destination(
    release_name: str,
    source_file: str,
    tmdb_title: str,
    tmdb_year: int,
    kb: ReleaseKnowledge,
    prober: MediaProber,
 ) -> ResolvedMovieDestination:
    """
    Compute destination paths for a movie file.
    Returns movie_folder + library_file (full path to .mkv).
    ``source_file`` doubles as the inspection target — when it exists,
    ffprobe enrichment refreshes tech tokens missing from the release name.
    """
    memory = get_memory()
    movies_root = memory.ltm.library_paths.get("movie")
    if not movies_root:
        return ResolvedMovieDestination(
            status="error",
            error="library_not_set",
            message="Movie library path is not configured.",
        )
    parsed = _resolve_parsed(release_name, source_file, kb, prober)
    ext = Path(source_file).suffix
    tmdb_title_safe = kb.sanitize_for_fs(tmdb_title)
    folder_name = parsed.movie_folder_name(tmdb_title_safe, tmdb_year)
    filename = parsed.movie_filename(tmdb_title_safe, tmdb_year, ext)
    folder_path = Path(movies_root) / folder_name
    file_path = folder_path / filename
    return ResolvedMovieDestination(
        status="ok",
        movie_folder=str(folder_path),
        library_file=str(file_path),
        movie_folder_name=folder_name,
        filename=filename,
        is_new_folder=not folder_path.exists(),
    )
 def resolve_series_destination(
    release_name: str,
    tmdb_title: str,
    tmdb_year: int,
    kb: ReleaseKnowledge,
    prober: MediaProber,
    confirmed_folder: str | None = None,
    source_path: str | None = None,
 ) -> ResolvedSeriesDestination:
    """
    Compute destination path for a complete multi-season series pack.
    Returns only series_folder — the whole pack lands directly inside it.
    When ``source_path`` points to the release on disk, ffprobe
    enrichment refreshes tech tokens missing from the release name.
    """
    tv_root = _get_tv_root()
    if not tv_root:
        return ResolvedSeriesDestination(
            status="error",
            error="library_not_set",
            message="TV show library path is not configured.",
        )
    parsed = _resolve_parsed(release_name, source_path, kb, prober)
    tmdb_title_safe = kb.sanitize_for_fs(tmdb_title)
    computed_name = parsed.show_folder_name(tmdb_title_safe, tmdb_year)
    resolved = _resolve_series_folder(
        tv_root, tmdb_title, tmdb_title_safe, tmdb_year, computed_name, confirmed_folder
    )
    if isinstance(resolved, _Clarification):
        return ResolvedSeriesDestination(
            status="needs_clarification",
            question=resolved.question,
            options=resolved.options,
        )
    series_folder_name, is_new = resolved
    series_path = tv_root / series_folder_name
    return ResolvedSeriesDestination(
        status="ok",
        series_folder=str(series_path),
        series_folder_name=series_folder_name,
        is_new_series_folder=is_new,
    )
@@ -0,0 +1,50 @@
 """Set folder path use case."""
 import logging
 from alfred.infrastructure.filesystem import FileManager
 from .dto import SetFolderPathResponse
 logger = logging.getLogger(__name__)
 class SetFolderPathUseCase:
    """
    Use case for setting a folder path in configuration.
    This orchestrates the FileManager to set folder paths.
    """
    def __init__(self, file_manager: FileManager):
        """
        Initialize use case.
        Args:
            file_manager: FileManager instance
        """
        self.file_manager = file_manager
    def execute(self, folder_name: str, path_value: str) -> SetFolderPathResponse:
        """
        Set a folder path in configuration.
        Args:
            folder_name: Name of folder to set (download, tvshow, movie, torrent)
            path_value: Absolute path to the folder
        Returns:
            SetFolderPathResponse with success or error information
        """
        result = self.file_manager.set_folder_path(folder_name, path_value)
        if result.get("status") == "ok":
            return SetFolderPathResponse(
                status="ok",
                folder_name=result.get("folder_name"),
                path=result.get("path"),
            )
        else:
            return SetFolderPathResponse(
                status="error", error=result.get("error"), message=result.get("message")
            )
@@ -1,10 +1,9 @@
 """Movie use cases."""
-from .dto import MovieHit, SearchMovieResponse
+from .dto import SearchMovieResponse
 from .search_movie import SearchMovieUseCase
 __all__ = [
    "MovieHit",
    "SearchMovieResponse",
    "SearchMovieUseCase",
    "SearchMovieResponse",
 ]
@@ -0,0 +1,44 @@
 """Movie application DTOs."""
 from dataclasses import dataclass
@dataclass
 class SearchMovieResponse:
    """Response from searching for a movie."""
    status: str
    imdb_id: str | None = None
    title: str | None = None
    media_type: str | None = None
    tmdb_id: int | None = None
    overview: str | None = None
    release_date: str | None = None
    vote_average: float | None = None
    error: str | None = None
    message: str | None = None
    def to_dict(self):
        """Convert to dict for agent compatibility."""
        result = {"status": self.status}
        if self.error:
            result["error"] = self.error
            result["message"] = self.message
        else:
            if self.imdb_id:
                result["imdb_id"] = self.imdb_id
            if self.title:
                result["title"] = self.title
            if self.media_type:
                result["media_type"] = self.media_type
            if self.tmdb_id:
                result["tmdb_id"] = self.tmdb_id
            if self.overview:
                result["overview"] = self.overview
            if self.release_date:
                result["release_date"] = self.release_date
            if self.vote_average:
                result["vote_average"] = self.vote_average
        return result
@@ -0,0 +1,93 @@
 """Search movie use case."""
 import logging
 from alfred.infrastructure.api.tmdb import (
    TMDBAPIError,
    TMDBClient,
    TMDBConfigurationError,
    TMDBNotFoundError,
 )
 from .dto import SearchMovieResponse
 logger = logging.getLogger(__name__)
 class SearchMovieUseCase:
    """
    Use case for searching a movie and retrieving its IMDb ID.
    This orchestrates the TMDB API client to find movie information.
    """
    def __init__(self, tmdb_client: TMDBClient):
        """
        Initialize use case.
        Args:
            tmdb_client: TMDB API client
        """
        self.tmdb_client = tmdb_client
    def execute(self, media_title: str) -> SearchMovieResponse:
        """
        Search for a movie by title.
        Args:
            media_title: Title of the movie to search for
        Returns:
            SearchMovieResponse with movie information or error
        """
        try:
            # Use the TMDB client to search for media
            result = self.tmdb_client.search_media(media_title)
            # Check if IMDb ID was found
            if result.imdb_id:
                logger.info(f"IMDb ID found for '{media_title}': {result.imdb_id}")
                return SearchMovieResponse(
                    status="ok",
                    imdb_id=result.imdb_id,
                    title=result.title,
                    media_type=result.media_type,
                    tmdb_id=result.tmdb_id,
                    overview=result.overview,
                    release_date=result.release_date,
                    vote_average=result.vote_average,
                )
            else:
                logger.warning(f"No IMDb ID available for '{media_title}'")
                return SearchMovieResponse(
                    status="ok",
                    title=result.title,
                    media_type=result.media_type,
                    tmdb_id=result.tmdb_id,
                    error="no_imdb_id",
                    message=f"No IMDb ID available for '{result.title}'",
                )
        except TMDBNotFoundError as e:
            logger.info(f"Media not found: {e}")
            return SearchMovieResponse(
                status="error", error="not_found", message=str(e)
            )
        except TMDBConfigurationError as e:
            logger.error(f"TMDB configuration error: {e}")
            return SearchMovieResponse(
                status="error", error="configuration_error", message=str(e)
            )
        except TMDBAPIError as e:
            logger.error(f"TMDB API error: {e}")
            return SearchMovieResponse(
                status="error", error="api_error", message=str(e)
            )
        except ValueError as e:
            logger.error(f"Validation error: {e}")
            return SearchMovieResponse(
                status="error", error="validation_failed", message=str(e)
            )
@@ -1,40 +0,0 @@
 """Movie application DTOs."""
 from dataclasses import dataclass, field
@dataclass(frozen=True)
 class MovieHit:
    """One movie hit, flattened for transport to the agent."""
    tmdb_id: int
    title: str
    release_year: int | None = None
    def to_dict(self) -> dict:
        out: dict = {"tmdb_id": self.tmdb_id, "title": self.title}
        if self.release_year is not None:
            out["release_year"] = self.release_year
        return out
@dataclass
 class SearchMovieResponse:
    """Response from searching for a movie."""
    status: str
    hits: list[MovieHit] = field(default_factory=list)
    error: str | None = None
    message: str | None = None
    def to_dict(self):
        """Convert to dict for agent compatibility."""
        result: dict = {"status": self.status}
        if self.error:
            result["error"] = self.error
            result["message"] = self.message
        else:
            result["hits"] = [h.to_dict() for h in self.hits]
        return result
@@ -1,60 +0,0 @@
 """Search movie use case."""
 import logging
 from alfred.infrastructure.api_TO_CHECK.tmdb import (
    TMDBAPIError,
    TMDBClient,
    TMDBConfigurationError,
 )
 from .dto import MovieHit, SearchMovieResponse
 logger = logging.getLogger(__name__)
 class SearchMovieUseCase:
    """List movies matching a free-text query via TMDB ``/search/movie``.
    The use case is a thin orchestrator: it asks the client for hits,
    flattens domain VOs into agent-friendly primitives, and wraps
    errors. It deliberately does **not** look up ``imdb_id`` —
    enrichment is the caller's job (via :meth:`TMDBClient.get_movie_info`
    on a chosen ``tmdb_id``).
    """
    def __init__(self, tmdb_client: TMDBClient):
        self.tmdb_client = tmdb_client
    def execute(self, media_title: str) -> SearchMovieResponse:
        try:
            results = self.tmdb_client.search_movies(media_title)
            hits = [
                MovieHit(
                    tmdb_id=r.tmdb_id.value,
                    title=str(r.title),
                    release_year=r.release_year.value if r.release_year else None,
                )
                for r in results
            ]
            logger.info(f"search_movies({media_title!r}) → {len(hits)} hits")
            return SearchMovieResponse(status="ok", hits=hits)
        except TMDBConfigurationError as e:
            logger.error(f"TMDB configuration error: {e}")
            return SearchMovieResponse(
                status="error", error="configuration_error", message=str(e)
            )
        except TMDBAPIError as e:
            logger.error(f"TMDB API error: {e}")
            return SearchMovieResponse(
                status="error", error="api_error", message=str(e)
            )
        except ValueError as e:
            logger.error(f"Validation error: {e}")
            return SearchMovieResponse(
                status="error", error="validation_failed", message=str(e)
            )
@@ -1,20 +0,0 @@
 """Release application layer — orchestrators sitting between domain
 parsing and infrastructure I/O.
 Public surface:
 - :func:`is_supported_video` / :func:`find_main_video` — pre-pipeline
  filesystem helpers (extension-only filtering, top-level video pick).
 - :func:`inspect_release` / :class:`InspectedResult` — full inspection
  pipeline combining parse + filesystem refinement + probe enrichment.
 """
 from .inspect import InspectedResult, inspect_release
 from .supported_media import find_main_video, is_supported_video
 __all__ = [
    "InspectedResult",
    "find_main_video",
    "inspect_release",
    "is_supported_video",
 ]
@@ -1,67 +0,0 @@
 """
 detect_media_type — filesystem-based media type refinement.
 Enriches a ParsedRelease.media_type with evidence from the actual source path
 (file or folder). Called after parse_release() to produce a final classification.
 Classification logic:
  1. If source_path is a file — check its extension directly.
  2. If source_path is a folder — collect all extensions inside (non-recursive
     for the first level, then recursive if nothing conclusive found).
  3. Decision:
     - Any non_video extension AND no video extension → "other"
     - Any video extension → keep parsed media_type ("movie" | "tv_show" | "unknown")
     - No conclusive extension found → keep parsed media_type as-is
     - Mixed (video + non_video) → "unknown"
 """
 from __future__ import annotations
 from pathlib import Path
 from alfred.domain.releases_TO_CHECK.ports import ReleaseKnowledge
 from alfred.domain.release.value_objects import ParsedRelease
 def detect_media_type(
    parsed: ParsedRelease, source_path: Path, kb: ReleaseKnowledge
 ) -> str:
    """
    Return a refined media_type string for the given source_path.
    Does not mutate parsed — returns the new media_type value only.
    The caller is responsible for updating the ParsedRelease if needed.
    """
    extensions = _collect_extensions(source_path)
    # Metadata extensions (.nfo, .srt, …) are always present alongside releases
    # and must not influence the type decision.
    conclusive = extensions - kb.metadata_extensions
    has_video = bool(conclusive & kb.video_extensions)
    has_non_video = bool(conclusive & kb.non_video_extensions)
    if has_video and has_non_video:
        return "unknown"
    if has_non_video and not has_video:
        return "other"
    if has_video:
        return parsed.media_type  # trust token-level inference
    # No conclusive extension — trust token-level inference
    return parsed.media_type
 def _collect_extensions(path: Path) -> set[str]:
    """Return the set of lowercase extensions found at path (file or folder)."""
    if not path.exists():
        return set()
    if path.is_file():
        return {path.suffix.lower()}
    # Folder — scan first level only
    exts: set[str] = set()
    for child in path.iterdir():
        if child.is_file():
            exts.add(child.suffix.lower())
    return exts
@@ -1,74 +0,0 @@
 """enrich_from_probe — fill missing ParsedRelease fields from MediaInfo."""
 from __future__ import annotations
 from dataclasses import replace
 from alfred.domain.releases_TO_CHECK.ports import ReleaseKnowledge
 from alfred.domain.release.value_objects import ParsedRelease
 from alfred.domain.shared_TO_CHECK.media import MediaInfo
 def enrich_from_probe(
    parsed: ParsedRelease, info: MediaInfo, kb: ReleaseKnowledge
 ) -> ParsedRelease:
    """
    Return a new ParsedRelease with None fields filled from ffprobe MediaInfo.
    Only overwrites fields that are currently None — token-level values
    from the release name always take priority. ``ParsedRelease`` is
    frozen; this returns a new instance via :func:`dataclasses.replace`.
    Translation tables (ffprobe codec name → scene token, channel count
    → layout) live in ``kb.probe_mappings`` (loaded from
    ``alfred/knowledge/release/probe_mappings.yaml``). When ffprobe
    reports a value with no mapping entry, the fallback is the uppercase
    raw value so unknown codecs still surface in a predictable form.
    """
    mappings = kb.probe_mappings
    video_codec_map: dict[str, str] = mappings.get("video_codec", {})
    audio_codec_map: dict[str, str] = mappings.get("audio_codec", {})
    channel_map: dict[int, str] = mappings.get("audio_channels", {})
    updates: dict[str, object] = {}
    if parsed.quality is None and info.resolution:
        updates["quality"] = info.resolution
    if parsed.codec is None and info.video_codec:
        updates["codec"] = video_codec_map.get(
            info.video_codec.lower(), info.video_codec.upper()
        )
    # bit_depth: ffprobe exposes it via pix_fmt — not in MediaInfo yet, skip.
    # Audio — use the default track, fallback to first
    default_track = next((t for t in info.audio_tracks if t.is_default), None)
    track = default_track or (info.audio_tracks[0] if info.audio_tracks else None)
    if track:
        if parsed.audio_codec is None and track.codec:
            updates["audio_codec"] = audio_codec_map.get(
                track.codec.lower(), track.codec.upper()
            )
        if parsed.audio_channels is None and track.channels:
            updates["audio_channels"] = channel_map.get(
                track.channels, f"{track.channels}ch"
            )
    # Languages — merge ffprobe languages with token-level ones
    # "und" = undetermined, not useful
    if info.audio_languages:
        existing_upper = {lang.upper() for lang in parsed.languages}
        new_languages = list(parsed.languages)
        for lang in info.audio_languages:
            if lang.lower() != "und" and lang.upper() not in existing_upper:
                new_languages.append(lang)
                existing_upper.add(lang.upper())
        if len(new_languages) != len(parsed.languages):
            updates["languages"] = tuple(new_languages)
    if not updates:
        return parsed
    return replace(parsed, **updates)
@@ -1,192 +0,0 @@
 """Release inspection orchestrator — the canonical "look at this thing"
 entry point.
 ``inspect_release`` is the single composition of the four layers we
 care about for a freshly-arrived release:
 1. **Parse the name** — :func:`alfred.domain.release.services.parse_release`
   gives a ``ParsedRelease`` plus a ``ParseReport`` (confidence + road).
 2. **Pick the main video** — :func:`find_main_video` runs a top-level
   scan over the source path. If nothing qualifies the result still
   completes; downstream callers decide what to do with a videoless
   release.
 3. **Refine the media type** — :func:`detect_media_type` uses the
   on-disk extension mix to override any token-level guess (e.g. a
   bare ``.iso`` folder becomes ``"other"``). The refined value is
   patched onto ``parsed`` in place — same convention as
   ``analyze_release`` had before.
 4. **Probe the video** — the injected :class:`MediaProber` fills in
   missing technical fields via :func:`enrich_from_probe`. Skipped
   when there is no main video or when ``media_type`` ended up in
   ``{"unknown", "other"}`` (the probe would tell us nothing useful).
 The return type is :class:`InspectedResult`, a frozen VO that bundles
 everything downstream callers need (``analyze_release`` tool,
 ``resolve_destination``, future workflow stages) without forcing them
 to redo the same four calls.
 Design notes:
 - **Application layer.** This module touches both domain
  (``parse_release``) and infrastructure (``MediaProber`` port). That
  is exactly application's job — orchestrate.
 - **Knowledge base is injected.** ``inspect_release`` takes ``kb`` and
  ``prober`` as parameters; no module-level singletons here. Callers
  (the tool wrapper, tests) decide what to plug in.
 - **Mutation is contained.** We still mutate ``parsed.media_type`` and
  let ``enrich_from_probe`` fill its ``None`` fields, because
  ``ParsedRelease`` is intentionally a mutable dataclass. The outer
  ``InspectedResult`` is frozen so the *bundle* is immutable from the
  caller's perspective.
 - **Never raises.** Filesystem / probe errors surface as ``None``
  fields on the result, never as exceptions — same contract as the
  underlying adapters.
 """
 from __future__ import annotations
 from dataclasses import dataclass, replace
 from pathlib import Path
 from alfred.application.release_TO_CHECK.detect_media_type import detect_media_type
 from alfred.application.release_TO_CHECK.enrich_from_probe import enrich_from_probe
 from alfred.application.release_TO_CHECK.supported_media import find_main_video
 from alfred.domain.releases_TO_CHECK.ports import ReleaseKnowledge
 from alfred.domain.releases_TO_CHECK.parser.services import parse_release
 from alfred.domain.release.value_objects import (
    MediaTypeToken,
    ParsedRelease,
    ParseReport,
 )
 from alfred.domain.shared_TO_CHECK.media import MediaInfo
 from alfred.domain.shared_TO_CHECK.ports import MediaProber
 # Media types for which a probe carries no useful information.
 _NON_PROBABLE_MEDIA_TYPES = frozenset({"unknown", "other"})
 # Media types for which there's nothing for the organizer to do.
 # ``other`` covers things like games / ISOs / archives sitting on the
 # downloads folder. ``unknown`` does NOT belong here — those need a
 # user decision, not a skip.
 _SKIPPABLE_MEDIA_TYPES = frozenset({"other"})
 # Roads that signal the parser couldn't reach a confident answer on its
 # own. ``Road`` values are kept as strings on the report to avoid a
 # cross-package import here.
 _ASK_USER_ROADS = frozenset({"path_of_pain"})
@dataclass(frozen=True)
 class InspectedResult:
    """The full picture of a release: parsed name + filesystem reality.
    Bundles everything the downstream pipeline needs after a single
    inspection pass:
    - ``parsed`` — :class:`ParsedRelease`, with ``media_type`` already
      refined by :func:`detect_media_type` and ``None`` tech fields
      filled in by :func:`enrich_from_probe` when a probe ran.
    - ``report`` — :class:`ParseReport` from the parser (confidence +
      road, untouched by inspection).
    - ``source_path`` — the path the inspector was pointed at (file or
      folder), as supplied by the caller.
    - ``main_video`` — the canonical video file inside ``source_path``,
      or ``None`` if no eligible file was found.
    - ``media_info`` — the :class:`MediaInfo` snapshot when a probe
      succeeded; ``None`` when no video was probed (no main video, or
      ``media_type`` in ``{"unknown", "other"}``) or when ffprobe
      failed.
    - ``probe_used`` — ``True`` iff ``media_info`` is non-``None`` and
      ``enrich_from_probe`` actually ran. Explicit flag so callers
      don't have to re-derive the condition.
    - ``recommended_action`` — derived hint for the orchestrator (see
      property docstring). Encodes the exclusion / clarification /
      go-ahead decision in one place so downstream callers don't
      re-implement the same checks.
    """
    parsed: ParsedRelease
    report: ParseReport
    source_path: Path
    main_video: Path | None
    media_info: MediaInfo | None
    probe_used: bool
    @property
    def recommended_action(self) -> str:
        """Return one of ``"skip"`` / ``"ask_user"`` / ``"process"``.
        - ``"skip"`` — nothing to organize:
            * the source has no main video file, **or**
            * ``media_type`` is ``"other"`` (games / ISOs / archives).
        - ``"ask_user"`` — a decision is required before any action:
            * ``media_type`` is ``"unknown"`` (parser couldn't classify), **or**
            * the parse landed on ``Road.PATH_OF_PAIN``
              (low-confidence, malformed name, etc.).
        - ``"process"`` — everything else: a confident parse with a
          usable media type and a main video on disk. The orchestrator
          can move straight to the planning step.
        The check ordering matters: ``"skip"`` wins over ``"ask_user"``
        because if there's no video to organize, no question to the
        user can change that. ``"ask_user"`` then wins over
        ``"process"`` because a confident parse alone isn't enough if
        the type or road still flag uncertainty.
        """
        if self.main_video is None:
            return "skip"
        if self.parsed.media_type.value in _SKIPPABLE_MEDIA_TYPES:
            return "skip"
        if self.parsed.media_type.value == "unknown":
            return "ask_user"
        if self.report.road in _ASK_USER_ROADS:
            return "ask_user"
        return "process"
 def inspect_release(
    release_name: str,
    source_path: Path,
    kb: ReleaseKnowledge,
    prober: MediaProber,
 ) -> InspectedResult:
    """Run the full inspection pipeline on ``release_name`` /
    ``source_path``.
    See module docstring for the four-step flow. ``kb`` and ``prober``
    are injected so the caller controls the knowledge base layering
    and the probe adapter (real ffprobe in production, stubs in tests).
    Never raises. A missing or unreadable ``source_path`` simply
    results in ``main_video=None`` and ``media_info=None``.
    """
    parsed, report = parse_release(release_name, kb)
    # Step 2: refine media_type from the on-disk extension mix.
    # detect_media_type tolerates non-existent paths (returns parsed.media_type
    # untouched), so no need to guard here. ParsedRelease is frozen — use
    # dataclasses.replace to rebind with the refined value.
    refined_media_type = MediaTypeToken(detect_media_type(parsed, source_path, kb))
    if refined_media_type != parsed.media_type:
        parsed = replace(parsed, media_type=refined_media_type)
    # Step 3: pick the canonical main video (top-level scan only).
    main_video = find_main_video(source_path, kb)
    # Step 4: probe + enrich, when it makes sense.
    media_info: MediaInfo | None = None
    probe_used = False
    if main_video is not None and parsed.media_type not in _NON_PROBABLE_MEDIA_TYPES:
        media_info = prober.probe(main_video)
        if media_info is not None:
            parsed = enrich_from_probe(parsed, media_info, kb)
            probe_used = True
    return InspectedResult(
        parsed=parsed,
        report=report,
        source_path=source_path,
        main_video=main_video,
        media_info=media_info,
        probe_used=probe_used,
    )
@@ -1,74 +0,0 @@
 """Pre-pipeline exclusion — decide which files are worth parsing.
 These helpers live one notch above the domain: they touch the
 filesystem (``Path.iterdir``, ``Path.suffix``) but carry no parsing
 logic of their own. The goal is to filter out non-video files and pick
 the canonical "main video" from a release folder *before* anything
 hits :func:`~alfred.domain.release.parse_release`.
 Design notes (Phase A bis, 2026-05-20):
 - **Extension is the sole eligibility criterion.** A file is supported
  iff its suffix is in ``kb.video_extensions``. No size threshold, no
  filename heuristics ("sample", "trailer", …). If a release packs a
  bloated featurette or names its sample alphabetically before the
  main feature, that's PATH_OF_PAIN territory — not this layer's job.
 - **Top-level scan only.** ``find_main_video`` does not descend into
  subdirectories. Releases that wrap the main video in ``Sample/`` or
  similar are non-scene-standard and handled by the orchestrator
  upstream.
 - **Lexicographic tie-break.** When several candidates qualify
  (legitimate for season packs), we return the first by alphabetical
  order. Deterministic, no size-based ranking.
 - **Direct ``Path`` I/O.** No ``FilesystemScanner`` port — this layer
  is application, not domain. If isolation becomes necessary for
  testing scale, we'll introduce a port then.
 """
 from __future__ import annotations
 from pathlib import Path
 from alfred.domain.releases_TO_CHECK.ports.knowledge import ReleaseKnowledge
 def is_supported_video(path: Path, kb: ReleaseKnowledge) -> bool:
    """Return True when ``path`` is a video file the parser should
    consider.
    The check is purely extension-based: ``path.suffix.lower()`` must
    belong to ``kb.video_extensions``. ``path`` must also be a regular
    file — directories and broken symlinks return False.
    """
    if not path.is_file():
        return False
    return path.suffix.lower() in kb.video_extensions
 def find_main_video(folder: Path, kb: ReleaseKnowledge) -> Path | None:
    """Return the canonical main video file inside ``folder``, or
    ``None`` if there isn't one.
    Behavior:
    - Top-level scan only — subdirectories are ignored.
    - Eligibility is :func:`is_supported_video`.
    - When several files qualify, the lexicographically first one wins.
    - When ``folder`` itself is a video file, it is returned as-is
      (single-file releases are valid).
    - When ``folder`` doesn't exist or isn't a directory (and isn't a
      video file either), returns ``None``.
    """
    if folder.is_file():
        return folder if is_supported_video(folder, kb) else None
    if not folder.is_dir():
        return None
    candidates = sorted(
        child for child in folder.iterdir() if is_supported_video(child, kb)
    )
    return candidates[0] if candidates else None
@@ -1,116 +0,0 @@
 """SubtitlePlacer — hard-links matched subtitle tracks next to the destination video."""
 import logging
 import os
 from dataclasses import dataclass
 from pathlib import Path
 from alfred.domain.subtitles_TO_CHECK.entities import SubtitleScanResult
 from alfred.domain.subtitles_TO_CHECK.value_objects import SubtitleType
 logger = logging.getLogger(__name__)
 def _build_dest_name(track: SubtitleScanResult, video_stem: str) -> str:
    """
    Build the destination filename for a subtitle track.
    Format: {video_stem}.{lang}.{ext}
            {video_stem}.{lang}.sdh.{ext}
            {video_stem}.{lang}.forced.{ext}
    """
    if not track.language or not track.format:
        raise ValueError("Cannot compute destination name: language or format missing")
    ext = track.format.extensions[0].lstrip(".")
    parts = [video_stem, track.language.code]
    if track.subtitle_type == SubtitleType.SDH:
        parts.append("sdh")
    elif track.subtitle_type == SubtitleType.FORCED:
        parts.append("forced")
    return ".".join(parts) + "." + ext
@dataclass
 class PlacedTrack:
    source: Path
    destination: Path
    filename: str
@dataclass
 class PlaceResult:
    placed: list[PlacedTrack]
    skipped: list[tuple[SubtitleScanResult, str]]  # (track, reason)
    @property
    def placed_count(self) -> int:
        return len(self.placed)
    @property
    def skipped_count(self) -> int:
        return len(self.skipped)
 class SubtitlePlacer:
    """
    Hard-links matched SubtitleScanResult files next to a destination video.
    Uses the same hard-link strategy as FileManager.copy_file:
    instant, no data duplication, qBittorrent keeps seeding.
    Embedded tracks are skipped — nothing to place on disk.
    """
    def place(
        self,
        tracks: list[SubtitleScanResult],
        destination_video: Path,
    ) -> PlaceResult:
        placed: list[PlacedTrack] = []
        skipped: list[tuple[SubtitleScanResult, str]] = []
        dest_dir = destination_video.parent
        for track in tracks:
            if track.is_embedded:
                logger.debug(f"SubtitlePlacer: skip embedded track ({track.language})")
                skipped.append((track, "embedded — no file to place"))
                continue
            if not track.file_path:
                skipped.append((track, "source file not set"))
                continue
            try:
                dest_name = _build_dest_name(track, destination_video.stem)
            except ValueError as e:
                skipped.append((track, str(e)))
                continue
            dest_path = dest_dir / dest_name
            try:
                os.link(track.file_path, dest_path)
                placed.append(
                    PlacedTrack(
                        source=track.file_path,
                        destination=dest_path,
                        filename=dest_name,
                    )
                )
                logger.info(f"SubtitlePlacer: placed {dest_name}")
            except FileNotFoundError:
                skipped.append((track, "source file not found"))
            except FileExistsError:
                logger.debug(f"SubtitlePlacer: skip {dest_name} — already exists")
                skipped.append((track, "destination already exists"))
            except OSError as e:
                logger.warning(f"SubtitlePlacer: failed to place {dest_name}: {e}")
                skipped.append((track, str(e)))
        logger.info(
            f"SubtitlePlacer: {len(placed)} placed, {len(skipped)} skipped "
            f"for {destination_video.name}"
        )
        return PlaceResult(placed=placed, skipped=skipped)
@@ -2,7 +2,7 @@
 import logging
-from alfred.infrastructure.api_TO_CHECK.qbittorrent import (
+from alfred.infrastructure.api.qbittorrent import (
    QBittorrentAPIError,
    QBittorrentAuthError,
    QBittorrentClient,
@@ -2,7 +2,7 @@
 import logging
-from alfred.infrastructure.api_TO_CHECK.knaben import (
+from alfred.infrastructure.api.knaben import (
    KnabenAPIError,
    KnabenClient,
    KnabenNotFoundError,
@@ -1,21 +0,0 @@
 """TV-show orchestrators — operate on the Alfred-managed TV library tree.
 The TV library is a directory of show folders (one per TV show), each
 holding season folders containing video files. Modules here walk this
 tree and reconstruct on-disk :class:`SeriesRelease` aggregates by
 reusing the existing release pipeline (``inspect_release``) rather
 than duplicating its parse/probe logic.
 """
 from .dto import SearchShowResponse, ShowHit
 from .search_show import SearchShowUseCase
 from .walker import SeasonFolder, ShowTree, walk_show
 __all__ = [
    "SearchShowResponse",
    "SearchShowUseCase",
    "SeasonFolder",
    "ShowHit",
    "ShowTree",
    "walk_show",
 ]
@@ -1,39 +0,0 @@
 """TV show application DTOs."""
 from dataclasses import dataclass, field
@dataclass(frozen=True)
 class ShowHit:
    """One TV-show hit, flattened for transport to the agent."""
    tmdb_id: int
    name: str
    first_air_year: int | None = None
    def to_dict(self) -> dict:
        out: dict = {"tmdb_id": self.tmdb_id, "name": self.name}
        if self.first_air_year is not None:
            out["first_air_year"] = self.first_air_year
        return out
@dataclass
 class SearchShowResponse:
    """Response from searching for a TV show."""
    status: str
    hits: list[ShowHit] = field(default_factory=list)
    error: str | None = None
    message: str | None = None
    def to_dict(self):
        result: dict = {"status": self.status}
        if self.error:
            result["error"] = self.error
            result["message"] = self.message
        else:
            result["hits"] = [h.to_dict() for h in self.hits]
        return result
@@ -1,59 +0,0 @@
 """Search TV show use case."""
 import logging
 from alfred.infrastructure.api_TO_CHECK.tmdb import (
    TMDBAPIError,
    TMDBClient,
    TMDBConfigurationError,
 )
 from .dto import SearchShowResponse, ShowHit
 logger = logging.getLogger(__name__)
 class SearchShowUseCase:
    """List TV shows matching a free-text query via TMDB ``/search/tv``.
    Symmetric to :class:`alfred.application.movies.SearchMovieUseCase`:
    thin orchestrator, flattens domain VOs into agent-friendly
    primitives, no ``imdb_id`` enrichment (caller follows up with
    :meth:`TMDBClient.get_tv_show_info` on a chosen ``tmdb_id``).
    """
    def __init__(self, tmdb_client: TMDBClient):
        self.tmdb_client = tmdb_client
    def execute(self, show_title: str) -> SearchShowResponse:
        try:
            results = self.tmdb_client.search_shows(show_title)
            hits = [
                ShowHit(
                    tmdb_id=r.tmdb_id.value,
                    name=r.name,
                    first_air_year=r.first_air_year,
                )
                for r in results
            ]
            logger.info(f"search_shows({show_title!r}) → {len(hits)} hits")
            return SearchShowResponse(status="ok", hits=hits)
        except TMDBConfigurationError as e:
            logger.error(f"TMDB configuration error: {e}")
            return SearchShowResponse(
                status="error", error="configuration_error", message=str(e)
            )
        except TMDBAPIError as e:
            logger.error(f"TMDB API error: {e}")
            return SearchShowResponse(
                status="error", error="api_error", message=str(e)
            )
        except ValueError as e:
            logger.error(f"Validation error: {e}")
            return SearchShowResponse(
                status="error", error="validation_failed", message=str(e)
            )
@@ -1,208 +0,0 @@
 """Show tree walker — minimal filesystem traversal of a TV show folder.
 The walker is intentionally dumb: it lists season folders, classifies
 each one as PACK or EPISODIC by **inspecting its filesystem
 structure**, and hands the orchestrator a flat list of video files
 per season. It does not parse release names, run ffprobe, or
 classify subtitle files. All of that intelligence lives in the
 existing release pipeline (``inspect_release`` + downstream
 services); the walker just hands the orchestrator the paths to feed
 into that pipeline.
 Folder convention
 -----------------
 Inside an Alfred-managed library, a show root looks like::
    Foundation/
        Foundation.S01.1080p.WEB-DL.x265-GROUP/        ← PACK season
            Foundation.S01E01.1080p.WEB-DL.x265.mkv    ← flat video
            Foundation.S01E02.1080p.WEB-DL.x265.mkv
            ...
        Foundation.S02/                                ← EPISODIC season
            Foundation.S02E01.1080p.WEB-DL.x265-GROUP/ ← episode subfolder
                Foundation.S02E01.1080p.WEB-DL.x265-GROUP.mkv
            Foundation.S02E02.1080p.WEB-DL.x265-OTHER/
                Foundation.S02E02.1080p.WEB-DL.x265-OTHER.mkv
 The walker recognizes a season folder by a ``Sxx`` token anywhere in
 its name (case-insensitive). It does **not** care about Plex-style
 names (``Season 01``, ``Specials``) — the Alfred library uses
 release-style folder names only.
 PACK vs EPISODIC is a **structural distinction**, not a naming one:
 * **PACK** — season folder contains N flat video files. No
  subfolders.
 * **EPISODIC** — season folder contains N subfolders, each holding
  exactly one video.
 A season folder that mixes the two layouts (some flat videos AND
 some subfolders) is malformed: the walker reports
 ``mode=None`` and an empty ``video_files`` tuple so the
 orchestrator can warn and skip it.
 """
 from __future__ import annotations
 import logging
 import re
 from dataclasses import dataclass
 from pathlib import Path
 from alfred.domain.releases_TO_CHECK.ports import ReleaseKnowledge
 from alfred.domain.releases_TO_CHECK.value_objects import ReleaseMode
 from alfred.domain.shared_TO_CHECK.ports import FilesystemScanner
 _LOG = logging.getLogger(__name__)
 # Matches any ``Sxx`` token (1-2 digits) bounded by non-alphanumerics.
 # Examples that match:  ``Foundation.S01.1080p`` , ``S2.Pack`` , ``BBC.s10.bluray``.
 # Examples that don't:  ``Sample`` , ``Soundtrack`` , ``2024.S0E1`` (no S+digits boundary).
 _SEASON_TOKEN_RE = re.compile(r"(?<![A-Za-z0-9])s(\d{1,2})(?![A-Za-z0-9])", re.IGNORECASE)
@dataclass(frozen=True)
 class SeasonFolder:
    """One season folder discovered inside a show root.
    ``mode`` is set by the walker from the FS structure:
    * :attr:`ReleaseMode.PACK` — ``video_files`` lists the season
      folder's flat videos.
    * :attr:`ReleaseMode.EPISODIC` — ``video_files`` lists each
      episode subfolder's single video.
    * ``None`` — the folder is empty, malformed (mixed layout), or
      otherwise unclassifiable. ``video_files`` is empty. The
      orchestrator decides whether to warn/skip.
    """
    season_dir: Path
    mode: ReleaseMode | None
    video_files: tuple[Path, ...]
@dataclass(frozen=True)
 class ShowTree:
    """The full structural snapshot of a show on disk."""
    show_root: Path
    season_folders: tuple[SeasonFolder, ...]
 def walk_show(
    show_root: Path,
    *,
    scanner: FilesystemScanner,
    kb: ReleaseKnowledge,
 ) -> ShowTree:
    """Walk ``show_root`` and return its structural tree.
    The walker:
    * lists direct children of ``show_root``,
    * keeps the directories whose name contains a ``Sxx`` token,
    * classifies each season folder as PACK / EPISODIC / unknown by
      inspecting its direct children (videos vs subfolders),
    * for EPISODIC, descends one extra level into each episode
      subfolder to collect its single video,
    * sorts season folders by name and video files by name within
      each folder.
    The walker never raises — empty / unreadable / malformed
    directories surface as a ``SeasonFolder`` with ``mode=None`` and
    an empty ``video_files`` tuple.
    """
    video_exts = {ext.lower() for ext in kb.video_extensions}
    season_folders: list[SeasonFolder] = []
    for entry in scanner.scan_dir(show_root):
        if not entry.is_dir or not _SEASON_TOKEN_RE.search(entry.name):
            continue
        season_folders.append(
            _classify_season(entry.path, scanner=scanner, video_exts=video_exts)
        )
    return ShowTree(
        show_root=show_root, season_folders=tuple(season_folders)
    )
 # --------------------------------------------------------------------------- #
 # Season-folder classification                                                #
 # --------------------------------------------------------------------------- #
 def _classify_season(
    season_dir: Path,
    *,
    scanner: FilesystemScanner,
    video_exts: set[str],
 ) -> SeasonFolder:
    """Inspect one season folder and decide PACK / EPISODIC / unknown.
    Looks only at direct children. For EPISODIC, descends one extra
    level into each subfolder to collect its single video. Mixed
    layouts (flat videos + subfolders) are reported as ``mode=None``
    so the orchestrator can skip them with a warning.
    """
    flat_videos: list[Path] = []
    subdirs: list[Path] = []
    for child in scanner.scan_dir(season_dir):
        if child.is_file and child.suffix.lower() in video_exts:
            flat_videos.append(child.path)
        elif child.is_dir:
            subdirs.append(child.path)
        # Anything else (non-video files like .nfo, .srt at the season
        # root) is ignored — it doesn't affect classification.
    has_flat = bool(flat_videos)
    has_subdirs = bool(subdirs)
    if has_flat and has_subdirs:
        _LOG.warning(
            "walker: season folder %s mixes flat videos and subfolders — "
            "malformed layout, skipping",
            season_dir,
        )
        return SeasonFolder(season_dir=season_dir, mode=None, video_files=())
    if has_flat:
        return SeasonFolder(
            season_dir=season_dir,
            mode=ReleaseMode.PACK,
            video_files=tuple(sorted(flat_videos)),
        )
    if has_subdirs:
        episode_videos: list[Path] = []
        for sub in sorted(subdirs):
            videos_in_sub = [
                child.path
                for child in scanner.scan_dir(sub)
                if child.is_file and child.suffix.lower() in video_exts
            ]
            if len(videos_in_sub) == 0:
                _LOG.warning(
                    "walker: episode subfolder %s contains no video — skipping",
                    sub,
                )
                continue
            if len(videos_in_sub) > 1:
                _LOG.warning(
                    "walker: episode subfolder %s contains %d videos — "
                    "malformed, skipping season %s",
                    sub,
                    len(videos_in_sub),
                    season_dir,
                )
                return SeasonFolder(
                    season_dir=season_dir, mode=None, video_files=()
                )
            episode_videos.append(videos_in_sub[0])
        return SeasonFolder(
            season_dir=season_dir,
            mode=ReleaseMode.EPISODIC,
            video_files=tuple(episode_videos),
        )
    # No flat videos, no subdirs → empty season folder.
    return SeasonFolder(season_dir=season_dir, mode=None, video_files=())
@@ -2,6 +2,7 @@
 from .entities import Movie
 from .exceptions import InvalidMovieData, MovieNotFound
 from .services import MovieService
 from .value_objects import MovieTitle, Quality, ReleaseYear
 __all__ = [
@@ -11,4 +12,5 @@ __all__ = [
    "Quality",
    "MovieNotFound",
    "InvalidMovieData",
    "MovieService",
 ]
@@ -0,0 +1,88 @@
 """Movie domain entities."""
 from dataclasses import dataclass, field
 from datetime import datetime
 from ..shared.value_objects import FilePath, FileSize, ImdbId
 from .value_objects import MovieTitle, Quality, ReleaseYear
@dataclass
 class Movie:
    """
    Movie entity representing a movie in the media library.
    This is the main aggregate root for the movies domain.
    """
    imdb_id: ImdbId
    title: MovieTitle
    release_year: ReleaseYear | None = None
    quality: Quality = Quality.UNKNOWN
    file_path: FilePath | None = None
    file_size: FileSize | None = None
    tmdb_id: int | None = None
    added_at: datetime = field(default_factory=datetime.now)
    def __post_init__(self):
        """Validate movie entity."""
        # Ensure ImdbId is actually an ImdbId instance
        if not isinstance(self.imdb_id, ImdbId):
            if isinstance(self.imdb_id, str):
                object.__setattr__(self, "imdb_id", ImdbId(self.imdb_id))
            else:
                raise ValueError(
                    f"imdb_id must be ImdbId or str, got {type(self.imdb_id)}"
                )
        # Ensure MovieTitle is actually a MovieTitle instance
        if not isinstance(self.title, MovieTitle):
            if isinstance(self.title, str):
                object.__setattr__(self, "title", MovieTitle(self.title))
            else:
                raise ValueError(
                    f"title must be MovieTitle or str, got {type(self.title)}"
                )
    def has_file(self) -> bool:
        """Check if the movie has an associated file."""
        return self.file_path is not None and self.file_path.exists()
    def is_downloaded(self) -> bool:
        """Check if the movie is downloaded (has a file)."""
        return self.has_file()
    def get_folder_name(self) -> str:
        """
        Get the folder name for this movie.
        Format: "Title (Year)"
        Example: "Inception (2010)"
        """
        if self.release_year:
            return f"{self.title.value} ({self.release_year.value})"
        return self.title.value
    def get_filename(self) -> str:
        """
        Get the suggested filename for this movie.
        Format: "Title.Year.Quality.ext"
        Example: "Inception.2010.1080p.mkv"
        """
        parts = [self.title.normalized()]
        if self.release_year:
            parts.append(str(self.release_year.value))
        if self.quality != Quality.UNKNOWN:
            parts.append(self.quality.value)
        # Extension will be added based on actual file
        return ".".join(parts)
    def __str__(self) -> str:
        return f"{self.title.value} ({self.release_year.value if self.release_year else 'Unknown'})"
    def __repr__(self) -> str:
        return f"Movie(imdb_id={self.imdb_id}, title='{self.title.value}')"
@@ -1,6 +1,6 @@
 """Movie domain exceptions."""
-from ..shared_TO_CHECK.exceptions import DomainException, NotFoundError
+from ..shared.exceptions import DomainException, NotFoundError
 class MovieNotFound(NotFoundError):
@@ -0,0 +1,73 @@
 """Movie repository interfaces (abstract)."""
 from abc import ABC, abstractmethod
 from ..shared.value_objects import ImdbId
 from .entities import Movie
 class MovieRepository(ABC):
    """
    Abstract repository for movie persistence.
    This defines the interface that infrastructure implementations must follow.
    """
    @abstractmethod
    def save(self, movie: Movie) -> None:
        """
        Save a movie to the repository.
        Args:
            movie: Movie entity to save
        """
        pass
    @abstractmethod
    def find_by_imdb_id(self, imdb_id: ImdbId) -> Movie | None:
        """
        Find a movie by its IMDb ID.
        Args:
            imdb_id: IMDb ID to search for
        Returns:
            Movie if found, None otherwise
        """
        pass
    @abstractmethod
    def find_all(self) -> list[Movie]:
        """
        Get all movies in the repository.
        Returns:
            List of all movies
        """
        pass
    @abstractmethod
    def delete(self, imdb_id: ImdbId) -> bool:
        """
        Delete a movie from the repository.
        Args:
            imdb_id: IMDb ID of the movie to delete
        Returns:
            True if deleted, False if not found
        """
        pass
    @abstractmethod
    def exists(self, imdb_id: ImdbId) -> bool:
        """
        Check if a movie exists in the repository.
        Args:
            imdb_id: IMDb ID to check
        Returns:
            True if exists, False otherwise
        """
        pass
@@ -0,0 +1,192 @@
 """Movie domain services - Business logic."""
 import logging
 import re
 from ..shared.value_objects import FilePath, ImdbId
 from .entities import Movie
 from .exceptions import MovieAlreadyExists, MovieNotFound
 from .repositories import MovieRepository
 from .value_objects import Quality
 logger = logging.getLogger(__name__)
 class MovieService:
    """
    Domain service for movie-related business logic.
    This service contains business rules that don't naturally fit
    within a single entity.
    """
    def __init__(self, repository: MovieRepository):
        """
        Initialize movie service.
        Args:
            repository: Movie repository for persistence
        """
        self.repository = repository
    def add_movie(self, movie: Movie) -> None:
        """
        Add a new movie to the library.
        Args:
            movie: Movie entity to add
        Raises:
            MovieAlreadyExists: If movie with same IMDb ID already exists
        """
        if self.repository.exists(movie.imdb_id):
            raise MovieAlreadyExists(
                f"Movie with IMDb ID {movie.imdb_id} already exists"
            )
        self.repository.save(movie)
        logger.info(f"Added movie: {movie.title.value} ({movie.imdb_id})")
    def get_movie(self, imdb_id: ImdbId) -> Movie:
        """
        Get a movie by IMDb ID.
        Args:
            imdb_id: IMDb ID of the movie
        Returns:
            Movie entity
        Raises:
            MovieNotFound: If movie not found
        """
        movie = self.repository.find_by_imdb_id(imdb_id)
        if not movie:
            raise MovieNotFound(f"Movie with IMDb ID {imdb_id} not found")
        return movie
    def get_all_movies(self) -> list[Movie]:
        """
        Get all movies in the library.
        Returns:
            List of all movies
        """
        return self.repository.find_all()
    def update_movie(self, movie: Movie) -> None:
        """
        Update an existing movie.
        Args:
            movie: Movie entity with updated data
        Raises:
            MovieNotFound: If movie doesn't exist
        """
        if not self.repository.exists(movie.imdb_id):
            raise MovieNotFound(f"Movie with IMDb ID {movie.imdb_id} not found")
        self.repository.save(movie)
        logger.info(f"Updated movie: {movie.title.value} ({movie.imdb_id})")
    def remove_movie(self, imdb_id: ImdbId) -> None:
        """
        Remove a movie from the library.
        Args:
            imdb_id: IMDb ID of the movie to remove
        Raises:
            MovieNotFound: If movie not found
        """
        if not self.repository.delete(imdb_id):
            raise MovieNotFound(f"Movie with IMDb ID {imdb_id} not found")
        logger.info(f"Removed movie with IMDb ID: {imdb_id}")
    def detect_quality_from_filename(self, filename: str) -> Quality:
        """
        Detect video quality from filename.
        Args:
            filename: Filename to analyze
        Returns:
            Detected quality or UNKNOWN
        """
        filename_lower = filename.lower()
        # Check for quality indicators
        if "2160p" in filename_lower or "4k" in filename_lower:
            return Quality.UHD_4K
        elif "1080p" in filename_lower:
            return Quality.FULL_HD
        elif "720p" in filename_lower:
            return Quality.HD
        elif "480p" in filename_lower:
            return Quality.SD
        return Quality.UNKNOWN
    def extract_year_from_filename(self, filename: str) -> int | None:
        """
        Extract release year from filename.
        Args:
            filename: Filename to analyze
        Returns:
            Year if found, None otherwise
        """
        # Look for 4-digit year in parentheses or standalone
        # Examples: "Movie (2010)", "Movie.2010.1080p"
        patterns = [
            r"\((\d{4})\)",  # (2010)
            r"\.(\d{4})\.",  # .2010.
            r"\s(\d{4})\s",  # 2010
        ]
        for pattern in patterns:
            match = re.search(pattern, filename)
            if match:
                year = int(match.group(1))
                # Validate year is reasonable
                if 1888 <= year <= 2100:
                    return year
        return None
    def validate_movie_file(self, file_path: FilePath) -> bool:
        """
        Validate that a file is a valid movie file.
        Args:
            file_path: Path to the file
        Returns:
            True if valid movie file, False otherwise
        """
        if not file_path.exists():
            logger.warning(f"File does not exist: {file_path}")
            return False
        if not file_path.is_file():
            logger.warning(f"Path is not a file: {file_path}")
            return False
        # Check file extension
        valid_extensions = {".mkv", ".mp4", ".avi", ".mov", ".wmv", ".flv", ".webm"}
        if file_path.value.suffix.lower() not in valid_extensions:
            logger.warning(f"Invalid file extension: {file_path.value.suffix}")
            return False
        # Check file size (should be at least 100 MB for a movie)
        min_size = 100 * 1024 * 1024  # 100 MB
        if file_path.value.stat().st_size < min_size:
            logger.warning(
                f"File too small to be a movie: {file_path.value.stat().st_size} bytes"
            )
            return False
        return True
@@ -1,9 +1,10 @@
 """Movie domain value objects."""
 import re
 from dataclasses import dataclass
 from enum import Enum
-from ..shared_TO_CHECK.exceptions import ValidationError
+from ..shared.exceptions import ValidationError
 class Quality(Enum):
@@ -16,7 +17,7 @@ class Quality(Enum):
    UNKNOWN = "unknown"
    @classmethod
-    def from_string(cls, quality_str: str) -> Quality:
+    def from_string(cls, quality_str: str) -> "Quality":
        """
        Parse quality from string.
@@ -55,11 +56,22 @@ class MovieTitle:
                f"Movie title must be a string, got {type(self.value)}"
            )
-        if len(self.value) > 150:
+        if len(self.value) > 500:
            raise ValidationError(
-                f"Movie title too long: {len(self.value)} characters (max 150)"
+                f"Movie title too long: {len(self.value)} characters (max 500)"
            )
    def normalized(self) -> str:
        """
        Return normalized title for file system usage.
        Removes special characters and replaces spaces with dots.
        """
        # Remove special characters except spaces, dots, and hyphens
        cleaned = re.sub(r"[^\w\s\.\-]", "", self.value)
        # Replace spaces with dots
        normalized = cleaned.replace(" ", ".")
        return normalized
    def __str__(self) -> str:
        return self.value
@@ -85,6 +97,10 @@ class ReleaseYear:
                f"Release year must be an integer, got {type(self.value)}"
            )
        # Movies started around 1888, and we shouldn't have movies from the future
        if self.value < 1888 or self.value > 2100:
            raise ValidationError(f"Invalid release year: {self.value}")
    def __str__(self) -> str:
        return str(self.value)
@@ -1,91 +0,0 @@
 """Movie domain entities."""
 from dataclasses import dataclass
 from ..shared_TO_CHECK.value_objects import ImdbId, TmdbId
 from .value_objects import MovieTitle, ReleaseYear
@dataclass(frozen=True, eq=False)
 class Movie:
    """
    Movie aggregate root for the movies domain.
    TMDB-only aggregate: carries identity (``tmdb_id`` + optional
    ``imdb_id``) plus the catalog facts that come from TMDB (``title``,
    ``release_year``). Filesystem-side concerns (file path, quality,
    tracks, ``added_at``) live on :class:`alfred.domain.releases.entities.
    MovieRelease`, the per-movie release aggregate persisted alongside.
    Frozen: rebuild via ``dataclasses.replace`` to project metadata
    updates (e.g. a TMDB refresh) onto a new instance.
    Equality is identity-based on ``tmdb_id``: two ``Movie`` instances
    are equal iff they share the same primary key. ``imdb_id`` is a
    secondary anchor and not part of the identity.
    """
    tmdb_id: TmdbId
    title: MovieTitle
    imdb_id: ImdbId | None = None
    release_year: ReleaseYear | None = None
    def __post_init__(self) -> None:
        if not isinstance(self.tmdb_id, TmdbId):
            raise ValueError(
                f"tmdb_id must be TmdbId, got {type(self.tmdb_id)}"
            )
        if not isinstance(self.title, MovieTitle):
            if isinstance(self.title, str):
                object.__setattr__(self, "title", MovieTitle(self.title))
            else:
                raise ValueError(
                    f"title must be MovieTitle or str, got {type(self.title)}"
                )
        if self.imdb_id is not None and not isinstance(self.imdb_id, ImdbId):
            raise ValueError(
                f"imdb_id must be ImdbId or None, got {type(self.imdb_id)}"
            )
    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Movie):
            return NotImplemented
        return self.tmdb_id == other.tmdb_id
    def __hash__(self) -> int:
        return hash(self.tmdb_id)
    # WRONG
    def get_folder_name(self) -> str:
        """
        Get the folder name for this movie.
        Format: "Title (Year)"
        Example: "Inception (2010)"
        """
        if self.release_year:
            return f"{self.title.value} ({self.release_year.value})"
        return self.title.value
    # WRONG
    def get_filename(self) -> str:
        """
        Get the suggested base filename (without extension) for this movie.
        Format: ``Title.Year`` (quality lives on
        :class:`alfred.domain.releases.entities.MovieRelease` now and is
        appended by the release-aware caller — typically the rescan /
        organize flow, after Phase 4).
        Example: ``Inception.2010``.
        """
        parts = [self.title.normalized()]
        if self.release_year:
            parts.append(str(self.release_year.value))
        return ".".join(parts)
    def __str__(self) -> str:
        return f"{self.title.value} ({self.release_year.value if self.release_year else 'Unknown'})"
    def __repr__(self) -> str:
        return f"Movie(tmdb_id={self.tmdb_id}, title='{self.title.value}')"
@@ -1,38 +0,0 @@
 """Filesystem release aggregates — what the user owns on disk.
 This bounded context is intentionally separated from
 ``alfred.domain.tv_shows`` / ``alfred.domain.movies`` (TMDB identity).
 A :class:`SeriesRelease` describes the physical files on disk for one
 show; a :class:`TVShow` describes the work as catalogued by TMDB. The
 two are linked by :class:`~alfred.domain.shared.value_objects.TmdbId`
 in the persistence layer, never by direct reference.
 Not to be confused with ``alfred.domain.release`` (singular) which
 parses release **names** (strings → tokens). The two packages may be
 merged later; for now they coexist as separate concerns.
 """
 from .builders import SeasonReleaseBuilder, SeriesReleaseBuilder
 from .entities import (
    EpisodeRelease,
    MovieRelease,
    SeasonRelease,
    SeriesRelease,
    TrackProfile,
 )
 from .repositories import MovieReleaseRepository, SeriesReleaseRepository
 from .value_objects import EpisodeRange, ReleaseMode
 __all__ = [
    "EpisodeRange",
    "EpisodeRelease",
    "MovieRelease",
    "MovieReleaseRepository",
    "ReleaseMode",
    "SeasonRelease",
    "SeasonReleaseBuilder",
    "SeriesRelease",
    "SeriesReleaseBuilder",
    "SeriesReleaseRepository",
    "TrackProfile",
 ]
--- a/Show More
+++ b/Show More
		`@@ -1,3 +0,0 @@`
			`from .loader import WorkflowLoader`

			`__all__ = ["WorkflowLoader"]`