Dev v2

.env.sample

@@ -1,84 +1,120 @@
-# Azure Search for storing the processed documents
-AZURE_SEARCH_SERVICE=
-AZURE_SEARCH_INDEX=
-AZURE_SEARCH_KEY=
-AZURE_SEARCH_USE_SEMANTIC_SEARCH=False
-AZURE_SEARCH_SEMANTIC_SEARCH_CONFIG=default
-AZURE_SEARCH_TOP_K=5
-AZURE_SEARCH_ENABLE_IN_DOMAIN=False
-AZURE_SEARCH_FIELDS_ID=id
-AZURE_SEARCH_CONTENT_COLUMN=content
-AZURE_SEARCH_CONTENT_VECTOR_COLUMN=content_vector
-AZURE_SEARCH_DIMENSIONS=1536
-AZURE_SEARCH_FIELDS_TAG=tag
-AZURE_SEARCH_FIELDS_METADATA=metadata
-AZURE_SEARCH_FILENAME_COLUMN=filepath
-AZURE_SEARCH_TITLE_COLUMN=title
-AZURE_SEARCH_SOURCE_COLUMN=source
-AZURE_SEARCH_TEXT_COLUMN=text
-AZURE_SEARCH_LAYOUT_TEXT_COLUMN=layoutText
-AZURE_SEARCH_URL_COLUMN=url
-AZURE_SEARCH_CONVERSATIONS_LOG_INDEX=conversations-log
-AZURE_SEARCH_USE_INTEGRATED_VECTORIZATION=false
-AZURE_SEARCH_INDEXER_NAME=
-AZURE_SEARCH_DATASOURCE_NAME=
-# Azure OpenAI for generating the answer and computing the embedding of the documents
-AZURE_OPENAI_RESOURCE=
-AZURE_OPENAI_API_KEY=
-AZURE_OPENAI_MODEL=gpt-4o
-AZURE_OPENAI_MODEL_NAME=gpt-4o
-AZURE_OPENAI_EMBEDDING_MODEL=text-embedding-3-small
-AZURE_OPENAI_TEMPERATURE=0
-AZURE_OPENAI_TOP_P=1.0
-AZURE_OPENAI_MAX_TOKENS=1000
-AZURE_OPENAI_STOP_SEQUENCE=
-AZURE_OPENAI_SYSTEM_MESSAGE=You are an AI assistant that helps people find information.
-AZURE_OPENAI_API_VERSION=2024-02-01
-AZURE_OPENAI_STREAM=True
-# Backend for processing the documents and application logging in the app
-AzureWebJobsStorage=
-BACKEND_URL=http://localhost:7071
+# CWYD v2 local dev environment template.
+#
+# Copy to .env (gitignored) and fill in values for any external services you
+# want to hit. Every variable name below matches the canonical AppSettings field
+# in src/backend/core/settings.py and the corresponding Bicep output in
+# infra/main.bicep -- no v1 aliases. Pydantic-settings ignores unknown
+# variables, so a typo here silently does nothing; double-check spelling.
+#
+# Single source of truth at repo root (CU-008a, 2026-05-05). The previous
+# docker/.env.dev.example file was deleted; do not recreate it.
+#
+# Defaults: docker-compose.dev.yml hard-codes the local stack (azurite + a
+# pgvector-enabled postgres container) by overriding AZURE_DB_TYPE,
+# AZURE_INDEX_STORE, AZURE_POSTGRES_ENDPOINT, AZURE_STORAGE_BLOB_URL, and
+# AZURE_STORAGE_QUEUE_URL on the backend service. Setting those four here has
+# no effect on the default profile -- only matters if you override compose.
 
-# Enhanced logging configuration (optional)
-LOGLEVEL=INFO
-PACKAGE_LOGGING_LEVEL=WARNING
-# AZURE_LOGGING_PACKAGES=azure.core,azure.identity
-DOCUMENT_PROCESSING_QUEUE_NAME=
-AZURE_BLOB_ACCOUNT_NAME=
-AZURE_BLOB_ACCOUNT_KEY=
-AZURE_BLOB_CONTAINER_NAME=
-# Azure Form Recognizer for extracting the text from the documents
-AZURE_FORM_RECOGNIZER_ENDPOINT=
-AZURE_FORM_RECOGNIZER_KEY=
-# Azure AI Content Safety for filtering out the inappropriate questions or answers
-AZURE_CONTENT_SAFETY_ENDPOINT=
-AZURE_CONTENT_SAFETY_KEY=
-# Orchestration strategy. Use Azure OpenAI Functions (openai_function), Semantic Kernel (semantic_kernel), LangChain (langchain) or Prompt Flow (prompt_flow) for messages orchestration. If you are using a new model version 0613 select any strategy, if you are using a 0314 model version select "langchain". Note that both `openai_function` and `semantic_kernel` use OpenAI function calling.
-ORCHESTRATION_STRATEGY=openai_function
-# If selected Prompt Flow as orchestration strategy, please provide the following environment variables. Note that Prompt Flow does not support RBAC authentication currently.
-AZURE_ML_WORKSPACE_NAME=
-PROMPT_FLOW_DEPLOYMENT_NAME=
-PROMPT_FLOW_ENDPOINT_NAME=
-#Speech-to-text feature
-AZURE_SPEECH_SERVICE_KEY=
+# --- Azure AI / Foundry IQ (required for real LLM calls; mocked otherwise) ---
+# FoundrySettings.services_endpoint -- host of the unified AI Services account
+# (kind=AIServices). Drives the Document Intelligence ingestion parser
+# (Functions batch_push) and the Foundry IQ embeddings client. MUST be a
+# non-empty https:// URL or PDF/DOCX ingestion fails fast with an actionable
+# error (BUG-0034). Bicep output: AZURE_AI_SERVICES_ENDPOINT in infra/main.bicep.
+AZURE_AI_SERVICES_ENDPOINT=
+# FoundrySettings.project_endpoint -- Agent Framework + LangGraph both use this.
+AZURE_AI_PROJECT_ENDPOINT=
+# OpenAISettings.* -- model deployment names exposed via the Foundry account.
+AZURE_OPENAI_GPT_DEPLOYMENT=gpt-5.1
+AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-3-large
+AZURE_OPENAI_API_VERSION=2024-12-01-preview
+
+# --- Azure AI Search (cosmosdb-mode only; ignored in pgvector dev default) ---
+# SearchSettings.endpoint -- full https URL of the search service.
+AZURE_AI_SEARCH_ENDPOINT=
+AZURE_AI_SEARCH_INDEX=cwyd-index
+# SearchSettings.knowledge_base_* -- Foundry IQ Knowledge Base over the index
+# (grounds the agent_framework orchestrator). The KB REST API version is pinned
+# here so it can be bumped without a code change.
+AZURE_AI_SEARCH_KNOWLEDGE_BASE_NAME=cwyd-kb
+AZURE_AI_SEARCH_KNOWLEDGE_SOURCE_NAME=cwyd-index-ks
+AZURE_AI_SEARCH_KNOWLEDGE_BASE_API_VERSION=2025-11-01-preview
+
+# --- Identity (optional locally; uses AzureCliCredential when unset) ---
+# IdentitySettings.* -- AppSettings reads AZURE_TENANT_ID + AZURE_UAMI_CLIENT_ID.
+AZURE_TENANT_ID=
+AZURE_UAMI_CLIENT_ID=
+
+# --- Orchestrator selection (runtime-tunable; CWYD_ namespace by design) ---
+# OrchestratorSettings.name -- "langgraph" or "agent_framework". Both
+# orchestrators ground on either index store and are switchable from the admin
+# UI without a redeploy. On pgvector (AZURE_DB_TYPE=postgresql) both run
+# app-side RAG over the pgvector index; on Azure AI Search (cosmosdb mode)
+# agent_framework additionally grounds on a Foundry IQ Knowledge Base over that
+# index, while langgraph runs client-side RAG. ADR 0027 supersedes the ADR 0022
+# pgvector + agent_framework block, so neither pairing is rejected. The local
+# dev compose default database is pgvector.
+CWYD_ORCHESTRATOR_NAME=agent_framework
+#
+# Foundry agent identity is NOT configured here (CU-009, ADR 0008).
+# Agents are bootstrapped lazily on first request and cached in the
+# application database (Cosmos in cosmosdb mode, Postgres in postgresql
+# mode). To force re-creation, delete the row in the `agents` table.
+# See v2/docs/agents.md for details.
+
+# --- Observability ---
+# ObservabilitySettings.log_level -- AppSettings env_prefix is AZURE_, so the
+# var name is AZURE_LOG_LEVEL (bare LOG_LEVEL in v1 is silently ignored).
+AZURE_LOG_LEVEL=INFO
+# ObservabilitySettings.app_insights_connection_string -- when set,
+# azure-monitor-opentelemetry exports directly to App Insights. AppSettings
+# reads the AZURE_-prefixed name (env_prefix=AZURE_); the legacy bare
+# `APPLICATIONINSIGHTS_CONNECTION_STRING` is intentionally not honored
+# post-CU-002b -- use the typed name only.
+AZURE_APP_INSIGHTS_CONNECTION_STRING=
+
+# --- Backend HTTP (CORS, etc.) ---
+# Comma-separated list of allowed origins for the FastAPI CORSMiddleware.
+# Wired into NetworkSettings.cors_origins via CU-002.
+BACKEND_CORS_ORIGINS=http://localhost:5173
+
+# --- Speech-to-text (S1 / SPEECH-MVP, optional) ---
+# Populate to enable the `/api/speech` route used by the browser
+# microphone button. Empty -> route returns 503 (feature disabled).
+# AAD-only: the workload identity (UAMI in production, AzureCli /
+# DefaultAzureCredential locally) must hold `Cognitive Services Speech
+# User` on the Speech account. NO subscription key (Hard Rule #2).
+AZURE_SPEECH_SERVICE_NAME=
 AZURE_SPEECH_SERVICE_REGION=
-# Auth type environment variables.
-# When AZURE_AUTH_TYPE=rbac, please make sure variable USE_KEY_VAULT=false
-# When USE_KEY_VAULT=true, please make sure to set AZURE_KEY_VAULT_ENDPOINT
-AZURE_AUTH_TYPE=keys
-USE_KEY_VAULT=true
-AZURE_KEY_VAULT_ENDPOINT=
-# Application environment (e.g., dev, prod)
-APP_ENV="dev"
-# Chat conversation type to decide between custom or byod (bring your own data) conversation type
-CONVERSATION_FLOW=
-# Chat History CosmosDB Integration Settings
-AZURE_COSMOSDB_ACCOUNT_NAME=
-AZURE_COSMOSDB_ACCOUNT_KEY=
-AZURE_COSMOSDB_DATABASE_NAME=
-AZURE_COSMOSDB_CONVERSATIONS_CONTAINER_NAME=
-AZURE_COSMOSDB_ENABLE_FEEDBACK=
-AZURE_POSTGRESQL_HOST_NAME=
-AZURE_POSTGRESQL_DATABASE_NAME=
-AZURE_POSTGRESQL_USER=
-DATABASE_TYPE="CosmosDB"
+# Full ARM resource id of the Speech account; goes in the
+# `x-ms-cognitiveservices-resource-id` header during AAD token mint.
+AZURE_SPEECH_ACCOUNT_RESOURCE_ID=
+# Comma-separated BCP-47 language tags the recognizer auto-detects.
+AZURE_SPEECH_RECOGNIZER_LANGUAGES=en-US,fr-FR,de-DE,it-IT
+
+# --- Content Safety (PARITY-IMPL, optional) ---
+# Wires the prompt-shielding guard the chat pipeline runs before every
+# Foundry IQ call (`ContentSafetyGuard.screen()` posts to the
+# `AnalyzeText` REST endpoint). Empty endpoint -> lifespan leaves
+# `app.state.content_safety_client = None` and `get_content_safety_guard`
+# returns None so the pipeline runs unguarded (mirrors v1
+# `enable_content_safety: false` default).
+# AAD-only: the workload identity must hold `Cognitive Services User`
+# (a97b65f3-24c7-4388-baec-2e87135dc908) on the account. NO
+# subscription key (Hard Rule #2).
+AZURE_CONTENT_SAFETY_ENDPOINT=
+# Defaults to true (secure-by-default). Both `enabled=true` AND a
+# non-empty endpoint are required to construct the client at lifespan
+# start, so this stays inert until AZURE_CONTENT_SAFETY_ENDPOINT is
+# set above. Operators flip the guard OFF per-request via
+# `PATCH /api/admin/config {"content_safety_enabled": false}`
+# (`RuntimeConfig` override; `false` short-circuits to None even when
+# the lifespan client is present).
+AZURE_CONTENT_SAFETY_ENABLED=true
+# Inclusive lower bound at which Content Safety verdicts trip. Azure
+# reports severity 0/2/4/6 (0=safe, 2=low, 4=medium, 6=high); default
+# 4 matches v1's `enable_content_safety: true` behavior. Range 0-7.
+AZURE_CONTENT_SAFETY_SEVERITY_THRESHOLD=4
+
+# --- Frontend (consumed by the frontend container build) ---
+VITE_BACKEND_URL=http://localhost:8000

.flake8

@@ -2,4 +2,4 @@
 max-line-length = 88
 extend-ignore = E501
 exclude = .venv
-ignore = E203, W503
+ignore = E203, W503, E704

.github/agents/cwyd-implementer.agent.md

@@ -0,0 +1,61 @@
+---
+description: "Single-unit code writer for CWYD v2. Implements EXACTLY one class OR one method per invocation, plus a matching test stub. Refuses batch edits. Use when: a Work Order from cwyd-planner is ready, or the user explicitly requests one-unit implementation."
+tools: ["read_file", "list_dir", "file_search", "grep_search", "semantic_search", "create_file", "replace_string_in_file", "multi_replace_string_in_file", "get_errors", "vscode_listCodeUsages", "memory", "manage_todo_list"]
+---
+
+# cwyd-implementer
+
+You are the **implementer** for CWYD v2. You write **exactly one class OR one method** per invocation, plus a matching test stub. Nothing else.
+
+## Required reading (every invocation)
+
+1. The Work Order produced by `cwyd-planner` (must exist; if not, refuse and ask the user to run the planner).
+2. `.github/copilot-instructions.md`
+3. `.github/instructions/v2-workflow.instructions.md`
+4. The per-area instruction matching the target file.
+5. `v2/docs/bugs.md` + today's `v2/docs/worklog/YYYY-MM-DD.md` (durable tracking, Hard Rule #19).
+
+## Procedure
+
+1. Read the Work Order. Confirm scope is a single unit. If it lists more, implement only the first; flag the rest for follow-up.
+2. Read the target file (or create it with the pillar/phase header if new).
+3. Implement the unit:
+   - Add the pillar/phase docstring header if the file is new.
+   - Keep the public surface to what the Work Order specified.
+   - No "while I'm here" refactors.
+4. Add or extend the test file specified in the Work Order with a **stub** that:
+   - Imports the new unit.
+   - Has the test function signatures for happy path / failure / edge case.
+   - Each function body is a `# TODO(cwyd-tester): <one line>` followed by a single failing `assert False, "not implemented"` so the test runner reports it as failing (not skipped).
+5. Run `get_errors` on the edited files. Fix only compile/lint errors caused by your edit.
+6. Report:
+   - File(s) edited.
+   - The unit's signature.
+   - Path to the test stub.
+   - Any planner assumption that turned out wrong (do not silently change scope).
+7. Durable tracking (Hard Rule #19): append a one-line entry for this unit to the day's worklog `v2/docs/worklog/YYYY-MM-DD.md` under **Done**; if you discovered a defect, record it in `v2/docs/bugs.md` with the next sequential `BUG-####` id.
+
+## Hard rules
+
+- **One class OR one method.** Not both. Not two methods. If a class needs an `__init__` and the Work Order specifies the class, the `__init__` counts as part of that single class — but no other methods.
+- **No edits outside the target file and its test file** — the sole exception is the two durable-tracking files (`v2/docs/worklog/YYYY-MM-DD.md` and `v2/docs/bugs.md`), updated per Hard Rule #19. If a *code* dependency must change, stop and request a new Work Order.
+- **Pillar/phase header required** on every new file in `src/**`.
+- **No banned imports** (see `v2-workflow.instructions.md`). If you find one already present in the touched file, flag it but do not fix it in this turn.
+- **Do not write real test bodies.** That is `cwyd-tester`'s job.
+
+## Refusal cases
+
+Refuse and explain when:
+
+- No Work Order is provided.
+- The Work Order asks for more than one unit.
+- The Work Order is missing a `Pillar:` declaration or a `Phase:` / dev_plan task # citation.
+- The Work Order's `Structural change:` field describes a new folder/package/dependency without a `user-confirmed on <date>` note. Stop and request a planner pass to obtain user confirmation.
+- The target file would require imports or refactors beyond the unit's scope.
+- A banned dependency is required (see `v2-workflow.instructions.md` § Banned in v2).
+- Implementing the unit would break the plug-and-play contract (backend-only or frontend-only profile would no longer boot).
+- The Work Order or your implementation would add a container, sidecar, package, abstraction, or config file format **not cited from [v2/docs/development_plan.md](../../v2/docs/development_plan.md) §3.4/§4**. Stop and request a planner pass to amend the plan first. Never fall back to "how v1 did it" — v1 is the spaghetti being replaced.
+
+## Stop condition
+
+After the unit + test stub are saved and `get_errors` is clean, stop. Hand off to `cwyd-tester`.