rasa-pro 3.19.0.dev3__tar.gz → 3.19.0.dev4__tar.gz

{rasa_pro-3.19.0.dev3 → rasa_pro-3.19.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: rasa-pro
-Version: 3.19.0.dev3
+Version: 3.19.0.dev4
 Summary: State-of-the-art open-core Conversational AI framework for Enterprises that natively leverages generative AI for effortless assistant development.
 Keywords: nlp,machine-learning,machine-learning-library,bot,bots,botkit,rasa conversational-agents,conversational-ai,chatbot,chatbot-framework,bot-framework
 Author: Rasa Technologies GmbH

{rasa_pro-3.19.0.dev3 → rasa_pro-3.19.0.dev4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "rasa-pro"
-version = "3.19.0.dev3"
+version = "3.19.0.dev4"
 description = "State-of-the-art open-core Conversational AI framework for Enterprises that natively leverages generative AI for effortless assistant development."
 authors = [ "Rasa Technologies GmbH <hi@rasa.com>",]
 maintainers = [ "Tom Bocklisch <tom@rasa.com>",]
@@ -659,6 +659,7 @@ convention = "google"
 
 
 
+
 [tool.poetry.group.dev.dependencies]
 ruff = ">=0.3.5,<0.4.0"
 docker = "~7.1.0"

rasa_pro-3.19.0.dev4/rasa/calm_v2/README-INTERNAL.md

@@ -0,0 +1,428 @@
+# CALM v2 — Internal Developer Guide
+
+Internal, developer-facing notes for working on the **CALM v2 (Maestro)** engine. This is
+the engineering companion to the customer-facing Maestro docs — it covers *how we build and
+ship*, not how to author agents.
+
+- **Engine code:** [`rasa/calm_v2/`](.) (you are here)
+- **Engine tests:** [`tests/calm_v2/`](../../tests/calm_v2/)
+- **Docs (customer-facing):** [`maestro-docs/`](../../maestro-docs/) — [rendered publicly](https://rasa-2f7eb63d.mintlify.site/) straight off the `calm-v2` branch
+- **Branch:** all CALM v2 code and docs live on `calm-v2`, **not** `main`. Branch off `calm-v2` and PR back into it.
+
+> This guide lives on the `calm-v2` branch alongside the code it describes. Keep it current in
+> the same PR as the change it documents.
+
+## Contents
+
+- [Overview](#overview)
+- [Local setup](#local-setup)
+- [Architecture](#architecture)
+- [Developer workflow](#developer-workflow) — **the main section**
+- [Testing](#testing)
+- [Release process](#release-process)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+**CALM v2 (Maestro)** is Rasa's LLM-native dialogue engine: you describe agent behaviour
+in natural-language **skills** (`skill.md`, tools, memory), and the orchestrator runs the
+conversation — routing, tool calls, digressions, and progressive control (ordered blocks,
+constraints) when you need guarantees. That differs from **CALM v1**, which centres on
+flows, NLU, and the classic policy / domain graph (`config.yml`, `domain/`, `data/`).
+Maestro projects use `agent.yml` + `integrations.yml` + `skills/` instead.
+
+Customer-facing concepts (skills, progressive control, the runtime loop) are documented in
+the [Maestro docs](https://rasa-2f7eb63d.mintlify.site/) (source: [`maestro-docs/`](../../maestro-docs/)).
+This guide is the engineering companion — how the engine is built, tested, and released.
+
+## Local setup
+
+### Install Rasa
+
+Maestro / CALM v2 ships in the main `rasa` package (no separate Poetry extra). You can
+either install the shared **dev release** or work from this repo.
+
+#### Option A — `rasa-pro` 3.19.0.dev2 (first shared Maestro dev release)
+
+For trying Maestro or building agents without editing engine code, install the published
+dev build from the private registry:
+
+```bash
+pip install "rasa-pro==3.19.0.dev2" \
+  --extra-index-url=https://europe-west3-python.pkg.dev/rasa-releases/rasa-pro-python/simple/
+```
+
+You need registry access; see [`README-INTERNAL.md`](../../README-INTERNAL.md) for
+auth / registry notes.
+
+#### Option B — from this repo (engine development)
+
+On the `calm-v2` branch, use **>=Python 3.10, <3.14** (e.g. via [pyenv](https://github.com/pyenv/pyenv)),
+install [Poetry](https://python-poetry.org/docs/#installation), then from the repo root:
+
+```bash
+make install
+```
+
+That installs dependencies and `rasa` in editable mode. Optional extras
+(`make install-full`) are for NLU / TensorFlow / etc. and are **not** required for
+Maestro engine development. Full packaging notes live in [`README-INTERNAL.md`](../../README-INTERNAL.md).
+
+### Create a first Maestro agent
+
+From any empty directory (with `rasa` on your `PATH`):
+
+```bash
+rasa init --engine maestro
+```
+
+`--engine maestro` selects the Maestro (CALM v2) scaffold. Without it, interactive
+`rasa init` defaults to CALM v1; with `--no-prompt` and no `--engine`, it scaffolds
+CALM v1 as well — always pass `--engine maestro` when you want a Maestro project.
+
+What the command does:
+
+1. **Copies the Maestro project template** (`rasa/cli/project_templates/maestro/`) into
+   the target directory — typically `agent.yml`, `integrations.yml`, a demo skill
+   (`skills/view_transactions/` with `skill.md`, mock `tools.py`, and `memory.yml`),
+   and an `AGENTS.md` for coding agents.
+2. **Collects secrets** (`RASA_LICENSE`, `OPENAI_API_KEY`) from the environment or
+   interactive prompts and writes them to a project `.env` (mode `0600` on POSIX).
+3. **Installs IDE skills** for Cursor and Claude Code (`rasa skills install maestro`
+   equivalent).
+4. **Optionally validates, trains, and opens Inspector** so you can chat with the
+   starter agent immediately.
+
+Non-interactive example:
+
+```bash
+export RASA_LICENSE=...
+export OPENAI_API_KEY=...
+rasa init --engine maestro --no-prompt --init-dir ./my-agent
+```
+
+Use `--no-train` if you only want the scaffold and skills installed.
+
+### What you need to run the init agent
+
+From the project directory:
+
+| Requirement | Why |
+|---|---|
+| **`RASA_LICENSE`** in `.env` (or the environment) | Required for `rasa train` / `rasa inspect`. `RASA_PRO_LICENSE` is still accepted as a read fallback; Maestro writes `RASA_LICENSE`. |
+| **`OPENAI_API_KEY`** in `.env` | Default LLM in the scaffolded `integrations.yml`. |
+| **`rasa train`** | Validates the project and packages a model archive into `models/`. |
+| **`rasa inspect`** | Opens the Inspector UI to talk to the agent (chat; use voice Inspector for voice work). |
+
+```bash
+cd my-agent
+rasa train
+rasa inspect
+```
+
+Re-run `rasa train` after editing `agent.yml`, `integrations.yml`, or any skill.
+Customer-facing getting-started notes live in [`maestro-docs/getting-started.mdx`](../../maestro-docs/getting-started.mdx).
+
+## Architecture
+
+Maestro (CALM v2) runs one user turn as an **orchestrator loop**: advance any
+deterministic skill steps, and when those hand off, build a prompt and call the LLM.
+Tool calls and stack/memory updates go through `SkillExecutor` onto an append-only
+tracker. The same outer loop covers autonomous and hybrid skills — the difference is
+what `advance_steps` does before each LLM call and what the prompt exposes.
+
+| Component | Role |
+|---|---|
+| `Orchestrator` | Owns the per-turn LLM iteration loop (up to 10 iterations) |
+| `SkillExecutor` | Advances deterministic steps; dispatches tool calls; owns skill lifecycle |
+| `TrackerHandle` | Single read/write surface for stack + events (append-only tracker) |
+| `MemoryManager` | Schema-aware memory read/write over tracker slots |
+| `PromptConstructor` | Builds system + history + user messages from `PromptContext` |
+
+### Shared turn loop (example)
+
+The sequence diagram below shows **one iteration** of a turn where the engine needs to
+**call a tool** and the **user does not interrupt**. `advance_steps` returns `None` (hand
+off to the LLM), the orchestrator builds the prompt, calls the LLM, sends filler text,
+dispatches the tool, then starts the next iteration. Other outcomes (`WAIT`, `CONTINUE`,
+rephrase, text-only, barge-in, digression, RAG, …) are covered on
+[Maestro — Sequence Diagrams](https://www.notion.so/rasa/Maestro-Sequence-Diagrams-3acb9c0d544a80b3b861ccf9b51da985).
+
+```mermaid
+sequenceDiagram
+    participant Orch as Orchestrator
+    participant TC as TurnContext
+    participant SE as SkillExecutor
+    participant TH as TrackerHandle
+    participant MM as MemoryManager
+    participant PC as PromptConstructor
+    participant LLM
+
+    Note over Orch,LLM: One iteration — tool call needed, no user interrupt
+    Orch->>SE: advance_steps
+    SE-->>Orch: None
+    Orch->>SE: current_memory_entries / settable_fields
+    SE->>MM: read_all
+    MM-->>SE: memory entries
+    SE-->>Orch: memory entries
+    Orch->>PC: build_messages
+    PC-->>Orch: messages
+    Orch->>LLM: acompletion (with tools)
+    LLM-->>Orch: text + tool call
+    Orch->>TC: send filler text
+    Orch->>SE: dispatch_tool_call
+    Orch->>TH: apply_events
+    Note over Orch: start next iteration
+```
+
+### Where to find what
+
+All paths below are under the root package **`rasa/calm_v2/`**.
+
+| Path | What belongs here |
+|---|---|
+| `processor.py` | Message-processor entry for CALM v2 — wires a user message into a turn and the orchestrator (kept separate from the CALM v1 / NLU processor). |
+| `inspector.py` | Wire contract for Inspector NextGen (skill catalog + per-tracker skill state JSON). Change in lock-step with the Inspector frontend Zod schemas. |
+| `orchestration/` | Turn loop and lifecycle execution: `orchestrator.py` (LLM iterations), `skill_executor.py` (advance steps / dispatch tools / stack), `turn_context.py` (ambient send + cancellation), plus correction / post-write hooks / responses. |
+| `skills/` | Skill authoring model and compile path: markdown skills → catalog, prose vs ordered blocks, conditions, steps, validation. Not the per-turn runtime loop. |
+| `state/` | Tracker façade for the engine: `tracker_handle.py`, stack/frame helpers, pending tool confirmation, turn helpers. Events stay append-only. |
+| `memory/` | Memory field schema, discovery, and `MemoryManager` read/write over slots. |
+| `tools/` | `@tool` decorator, loading skill tools, tool results / validation. |
+| `llm/` | LLM client, tool schemas offered each iteration, call logging. |
+| `prompts/` | System-prompt assembly (`system_prompt.py`, `constructor.py`) and Jinja snippets under `prompts/templates/`. Prompt text lives here — not in the orchestrator. |
+| `config/` | Engine-side config shapes (e.g. integrations / MCP). |
+| `model_archive/` | Packaging / bootstrap of a trained Maestro model archive. |
+| `default_skills/` | Built-in engine-managed skills (e.g. continue-interrupted, completed wrap-up). |
+| `validation.py` | Project validation before train / package. |
+
+---
+
+## Developer workflow
+
+This is the end-to-end loop for making a change to CALM v2, from writing code through to it
+landing on `calm-v2` and staying healthy. Confidence is built in layers: cheap, fast, local
+checks first, then progressively heavier evaluation. Each evaluation gate feeds back into
+development — if it surfaces a problem, you go back and fix it before moving on.
+
+```mermaid
+flowchart TD
+    Dev["<b>Develop</b><br/>write code + docs + changelog"]
+    Inspector["<b>1. Manual test in Inspector</b><br/>chat / voice · local"]
+    Subset["<b>2. Local subset eval</b><br/>a few relevant scenarios · no W&amp;B"]
+    Full["<b>3. Full eval on the PR</b><br/>GHA · logs to W&amp;B · vs nightly baseline"]
+    Merge(["Merge to calm-v2"])
+    Nightly["<b>4. Nightly full run</b> on calm-v2<br/>Slack alert on regression"]
+    Rota{"Regression?"}
+    Triage["Regression rota triages<br/>small fix → straight in<br/>larger issue → ticket"]
+
+    Dev --> Inspector
+    Inspector -->|looks wrong| Dev
+    Inspector -->|looks good| Subset
+    Subset -->|fails / off| Dev
+    Subset -->|2–3 convos look good| Full
+    Subset -.->|small / trivial change| Merge
+    Full -->|regressions| Dev
+    Full -->|green enough| Merge
+    Merge --> Nightly
+    Nightly --> Rota
+    Rota -->|yes| Triage
+    Triage --> Dev
+    Rota -->|no| Nightly
+```
+
+### 1. Manual testing with Inspector (local)
+
+Talk to the bot locally as you develop — the **voice Inspector** for voice changes, the **chat
+Inspector** otherwise. This is the first-pass sanity check on every change, before you spend
+time on any eval run.
+
+### 2. Run a subset of scenarios locally (quick feedback)
+
+Pick a handful of scenarios relevant to what you're changing and run them against your branch.
+The point is to **eyeball 2–3 conversations** — this step does **not** log to Weights & Biases.
+
+**Preferred:** run against
+[maestro-benchmarking-agents](https://github.com/RasaHQ/maestro-benchmarking-agents)
+with `make eval-maestro-agents`. That Make target sets `RASA_ROOT` to **this checkout** and
+invokes the external suite runner (default: Maestro smoke — hybrid + autonomous, two happy
+paths).
+
+Prerequisites:
+
+1. Clone `maestro-benchmarking-agents` as a **sibling of your main rasa checkout** (not under
+   `.agents/worktrees/`). Override with `MAESTRO_BENCHMARKING_ROOT` if needed.
+2. Repo-root `.env` (gitignored) with `RASA_LICENSE` / `RASA_PRO_LICENSE` and `OPENAI_API_KEY`
+   (you can copy keys from `examples/.env.example`). The default smoke suite reads
+   `${RASA_ROOT}/.env` even for `--dry-run`.
+3. A working Poetry venv (`.venv`, `.venv-current`, or `.venv3.11`).
+
+```bash
+make eval-maestro-agents                         # Maestro smoke suite
+make eval-maestro-agents EVAL_ARGS="--dry-run"   # validate wiring, no LLM spend
+make eval-maestro-agents EVAL_ARGS="--no-parallel"
+```
+
+Agent/scenario selection is via **suite YAML** in the benchmarking repo (not `--agents` /
+`--scenarios`):
+
+| Command | What runs |
+|---|---|
+| `make eval-maestro-agents` | `benchmarks/maestro-smoke-suite.yml` (default) |
+| `make eval-maestro-agents SUITE=benchmarks/two-scenario-suite.yml` | All 4 engines × 2 happy paths |
+| `make eval-maestro-agents SUITE=benchmarks/all-scenarios-suite-maestro-only.yml` | Maestro only, all scenarios (expensive) |
+
+Artifacts land under the benchmarking repo at `eval_runs/<suite-name>/<timestamp>/`. Any soft
+commit pin in that repo’s README is a compatibility reference only — this Make target always
+uses the checkout you run from.
+
+**Legacy (being retired):** packaged example agents via `make eval-examples` — see
+[`examples/calm-v2-eval.md`](../../examples/calm-v2-eval.md). Prefer the benchmarking target
+above for engine changes.
+
+### 3. Run the full eval suite via GitHub Action before merging
+
+Before merging anything non-trivial and/or requesting review, run the Maestro
+benchmarking suite against your branch. Trigger it by labelling the PR
+`run-maestro-evals` (when it touches `rasa/calm_v2/**`), or by dispatching the
+workflow manually with your `rasa-private` branch as input.
+
+- Agents: **maestro-hybrid** and **maestro-autonomous**, all scenarios.
+- Results go to **Weights & Biases**; regressions (≥ 5% vs the fixed baseline) alert
+  `#project-calm-v2`.
+
+How to run, schedule, baselines, and troubleshooting:
+[WORKFLOW_README.md](https://github.com/RasaHQ/maestro-benchmarking-agents/blob/main/WORKFLOW_README.md)
+in `RasaHQ/maestro-benchmarking-agents`.
+
+**Skip rule:** genuinely small changes (one-liners, trivial refactors) can skip this if steps 1
+and 2 already gave enough confidence. Otherwise, run it.
+
+### 4. Nightly full run + regression rota
+
+The full suite runs **nightly on `calm-v2`** and posts to Slack if there's a regression. A
+**weekly rota** owns triage: the person on rota picks up the alerts — a
+small fix goes straight in, a larger issue becomes a ticket. Rota shifts are tracked on the Jira
+board so the capacity hit is visible.
+
+### Incorporating evaluation feedback
+
+When reading eval results:
+
+- **Trust the binary pass/fail assertions** baked into scenarios — those are the signal to act
+  on.
+- **Don't over-read the LLM-judged 0–5 Likert scores** (e.g. naturalness 3.6 vs 3.8). They are
+  not statistically robust, so small movements are noise rather than a regression.
+- Prefer **deterministic assertions** in scenarios wherever possible.
+
+### 5. Docs
+
+Docs live in `maestro-docs/` on the `calm-v2` branch and the public Maestro docs render straight
+off it — anything merged is immediately what customers see. **When your PR changes behaviour,
+update the docs in the same PR.**
+
+### 6. Changelog
+
+There is **no separate per-PR changelog fragment** for CALM v2. Instead, add your changelog line
+directly to the single docs changelog file
+[`maestro-docs/changelog.mdx`](../../maestro-docs/changelog.mdx), under the **"Unreleased"** heading, in the **same PR** as the code and docs.
+
+When a dev release is cut, that heading is renamed to the version number and a fresh "Unreleased"
+section is opened above it. Changelog discipline starts from the
+first shared dev release (Fri **2026-08-07**).
+
+### Codifying this for coding agents
+
+This workflow is being captured as **skills / rules / slash-commands in `rasa-private`** so that
+coding agents pick it up automatically rather than each dev hunting through Notion/Slack. If you
+change the workflow, update those alongside this guide.
+
+---
+
+## Testing
+
+Engine unit / integration tests live under [`tests/calm_v2/`](../../tests/calm_v2/) and
+mirror the package layout (`orchestration/`, `skills/`, `state/`, `memory/`, `prompts/`,
+`tools/`, `llm/`, processor / Inspector / validation, …). They are marked
+`category_calm_v2` and run in a dedicated CI job.
+
+**These are not the scenario / eval suites** from the
+[developer workflow](#developer-workflow). Unit tests assert engine behaviour in-process
+(stack, memory, prompts, tool dispatch). Subset evals and the full Maestro benchmarking
+GHA exercise multi-turn conversations against example or benchmarking agents.
+
+### How to run
+
+From the repo root (with the editable install from [Local setup](#local-setup)):
+
+```bash
+# Full CALM v2 suite (same marker set as CI)
+make test-calm-v2
+
+# Targeted path while iterating
+poetry run pytest tests/calm_v2/orchestration/<file>.py -x -v
+```
+
+After code changes, also run `make lint` and `make types` (or `make static-checks`) before
+opening a PR — pre-commit expects them.
+
+### What a change should cover
+
+- Add or update tests next to the behaviour you change under `tests/calm_v2/`.
+- Cover the **happy path**, **error / failure paths**, and **boundaries** for the code you
+  touch — not only the success case.
+- Prefer a **failing test first** for bug fixes.
+- Keep tests in sync when you change contracts (e.g. Inspector JSON in `inspector.py`,
+  prompt assembly, tool schemas).
+- Do **not** treat a green local subset eval or GHA benchmarking run as a substitute for
+  unit coverage of the engine change.
+
+## Release process
+
+Maestro / CALM v2 is currently shipped as **dev releases** cut from the `calm-v2`
+branch (treated like a long-lived feature branch for pre-release purposes). The
+first externally shared Maestro build was **`rasa-pro` 3.19.0.dev2**
+(Fri **2026-08-07**).
+
+Follow
+[Cutting a Pre release version](../../README-INTERNAL.md#cutting-a-pre-release-version)
+in the repo [`README-INTERNAL.md`](../../README-INTERNAL.md). In short, for a
+dev release from `calm-v2`:
+
+1. Checkout `calm-v2` (or the feature branch you are releasing from) and run
+   `make release`, choosing a **dev** version (e.g. `3.19.0.dev3`).
+2. From a feature branch, `prepare-release-pre-*` is **not** created
+   automatically — add the version bump as a commit on that branch (or create /
+   push a `prepare-release-pre-*` branch yourself) and open a PR if needed.
+3. **Manually create and push the version tag.** Auto-tagging from the
+   [release workflow](https://github.com/RasaHQ/rasa-private/actions/workflows/release.yml)
+   does **not** work for Maestro / calm-v2 **dev releases** in practice — even after
+   a successful `make release` / prepare-release PR — so you almost always need:
+
+   ```bash
+   git checkout calm-v2
+   git pull origin calm-v2
+   git tag 3.19.0.dev3 -m "next dev release"
+   git push origin 3.19.0.dev3 --tags
+   ```
+
+4. Confirm
+   [Release artifacts](https://github.com/RasaHQ/rasa-private/actions/workflows/release-artifacts-workflow.yml)
+   succeeds for that tag (publish to the private registry). Success / failure
+   also posts to Slack (`#release` / `#prodeng-internal`).
+5. Rotate the Maestro docs changelog: rename **"Unreleased"** in
+   [`maestro-docs/changelog.mdx`](../../maestro-docs/changelog.mdx) to the
+   released version and open a fresh Unreleased section above it.
+
+Pre-releases are not backported to `main`. For major / minor / patch releases
+and troubleshooting, use the main [Releases](../../README-INTERNAL.md#releases)
+section in `README-INTERNAL.md`.
+
+## Troubleshooting
+
+Common local failure notes (training, eval runner, Inspector, …) will be collected here
+over time as we hit them — nothing canonical yet.
+
+For now, give feedback and ask for help in Slack **`#maestro-feedback`**. That channel
+is also a good place to search for related issues and how they were fixed.

rasa_pro-3.19.0.dev4/rasa/calm_v2/config/tracing.py

@@ -0,0 +1,120 @@
+"""Tracing configuration loaded from ``integrations.yml``.
+
+Engine projects declare Langfuse tracing under a ``tracing:`` key alongside
+LLM and channel integrations. Legacy / v1 projects keep Langfuse (and backend
+Jaeger / OTLP tracers) in ``endpoints.yml``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping, Optional
+
+import structlog
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from rasa.shared.exceptions import RasaException
+from rasa.shared.project_structure import V2_INTEGRATIONS_FILE
+from rasa.shared.utils.yaml import read_yaml_file
+from rasa.tracing.constants import TRACING_TYPE_LANGFUSE
+
+structlogger = structlog.get_logger()
+
+TRACING_KEY = "tracing"
+TYPE_KEY = "type"
+
+
+class LangfuseTracingSettings(BaseModel):
+    """The ``tracing:`` section of ``integrations.yml`` for Langfuse.
+
+    Mirrors the Langfuse block historically authored under ``endpoints.yml``.
+    Required keys match :mod:`rasa.tracing.langfuse_config`; optional Langfuse
+    knobs (``timeout``, ``debug``, ``environment``, …) are passed through via
+    ``extra="allow"`` so the apply path can set the corresponding env vars.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="allow")
+
+    type: str = Field(min_length=1)
+    public_key: str = Field(min_length=1)
+    private_key: str = Field(min_length=1)
+    host: str = Field(min_length=1)
+
+    def as_config_dict(self) -> dict[str, Any]:
+        """Return a plain dict suitable for Langfuse apply helpers."""
+        return self.model_dump()
+
+
+def parse_tracing(raw_tracing: Mapping[str, Any]) -> LangfuseTracingSettings:
+    """Validate a raw ``tracing:`` mapping from ``integrations.yml``.
+
+    Args:
+        raw_tracing: The ``tracing:`` mapping as read from integrations.yml.
+
+    Returns:
+        A validated :class:`LangfuseTracingSettings` instance.
+
+    Raises:
+        RasaException: If the mapping is not Langfuse or fails schema validation.
+    """
+    tracing_type = raw_tracing.get(TYPE_KEY)
+    if tracing_type != TRACING_TYPE_LANGFUSE:
+        raise RasaException(
+            f"'{TRACING_KEY}' in '{V2_INTEGRATIONS_FILE}' only supports "
+            f"type '{TRACING_TYPE_LANGFUSE}', got '{tracing_type}'."
+        )
+
+    try:
+        return LangfuseTracingSettings.model_validate(dict(raw_tracing))
+    except ValidationError as error:
+        raise RasaException(
+            f"Invalid '{TRACING_KEY}' configuration in '{V2_INTEGRATIONS_FILE}': "
+            f"{error}"
+        ) from error
+
+
+def load_integration_tracing(
+    project_root: str | Path,
+) -> Optional[LangfuseTracingSettings]:
+    """Load Langfuse tracing configuration from a project's ``integrations.yml``.
+
+    Environment variables in ``integrations.yml`` are expanded for most sections at
+    read time. Langfuse ``public_key`` / ``private_key`` stay as ``${VAR}``
+    literals at parse time (deferred resolution) so the apply path can validate
+    syntax and resolve them when Langfuse configures at startup.
+
+    Args:
+        project_root: Directory expected to contain ``integrations.yml``.
+
+    Returns:
+        Validated Langfuse settings, or ``None`` if the file does not exist or
+        does not declare a ``tracing:`` block.
+
+    Raises:
+        RasaException: If ``tracing:`` is present but not a mapping, or fails
+            validation (including unsupported tracer types).
+    """
+    integration_file = Path(project_root) / V2_INTEGRATIONS_FILE
+    if not integration_file.is_file():
+        return None
+
+    raw = read_yaml_file(integration_file, expand_env_vars=True)
+    if not isinstance(raw, Mapping):
+        return None
+
+    raw_tracing = raw.get(TRACING_KEY)
+    if raw_tracing is None:
+        return None
+    if not isinstance(raw_tracing, Mapping):
+        raise RasaException(
+            f"'{TRACING_KEY}' in '{V2_INTEGRATIONS_FILE}' must be a mapping "
+            f"with Langfuse settings, but got '{type(raw_tracing).__name__}'."
+        )
+
+    settings = parse_tracing(raw_tracing)
+    structlogger.debug(
+        "calm_v2.tracing.loaded_from_integration",
+        tracing_type=settings.type,
+        host=settings.host,
+    )
+    return settings

{rasa_pro-3.19.0.dev3 → rasa_pro-3.19.0.dev4}/rasa/calm_v2/config/validation.py

@@ -21,11 +21,17 @@ from rasa.calm_v2.config.integrations import (
     KnowledgeStoreConfig,
     LlmIntegrationSettings,
 )
+from rasa.calm_v2.config.tracing import parse_tracing
 from rasa.calm_v2.validation_finding import ValidationFinding
 from rasa.exceptions import ValidationError as RasaValidationError
+from rasa.shared.exceptions import RasaException
 from rasa.shared.project_structure import V2_AGENT_FILE, V2_INTEGRATIONS_FILE
 from rasa.shared.providers._configs.model_group_config import ModelGroupConfig
 from rasa.shared.utils.yaml import read_yaml_file
+from rasa.tracing.exceptions import InvalidLangfuseConfigException
+from rasa.tracing.langfuse_config import validate_langfuse_config_mapping
+
+_INVALID_TRACING_CODE = "calm_v2.validation.config.invalid_tracing"
 
 
 def validate_agent(project_root: Path) -> list[ValidationFinding]:
@@ -96,10 +102,10 @@ def _format_pydantic_errors(error: PydanticValidationError, fallback_loc: str) -
 def validate_integrations(project_root: Path) -> list[ValidationFinding]:
     """Check ``integrations.yml`` exists and its sections are valid.
 
-    Dispatches to a per-section validator (currently ``llm:`` and
-    ``knowledge_stores:``); further sections (e.g. ``channels:``,
-    ``mcp_servers:``) get their own ``_validate_<section>`` helper here as they
-    gain authoring checks.
+    Dispatches to a per-section validator (currently ``llm:``,
+    ``knowledge_stores:``, ``model_groups:``, and ``tracing:``); further
+    sections (e.g. ``channels:``, ``mcp_servers:``) get their own
+    ``_validate_<section>`` helper here as they gain authoring checks.
     """
     integrations_path = project_root / V2_INTEGRATIONS_FILE
     if not integrations_path.is_file():
@@ -117,10 +123,12 @@ def validate_integrations(project_root: Path) -> list[ValidationFinding]:
     llm_section = raw.get("llm") if isinstance(raw, Mapping) else None
     knowledge_stores = raw.get("knowledge_stores") if isinstance(raw, Mapping) else None
     model_groups = raw.get("model_groups") if isinstance(raw, Mapping) else None
+    tracing_section = raw.get("tracing") if isinstance(raw, Mapping) else None
     return (
         _validate_llm_section(llm_section)
         + _validate_knowledge_stores_section(knowledge_stores)
         + _validate_model_groups_section(model_groups)
+        + _validate_tracing_section(tracing_section)
     )
 
 
@@ -275,3 +283,51 @@ def _validate_model_groups_section(model_groups: Any) -> list[ValidationFinding]
             )
         seen_ids.add(group.model_group_id)
     return findings
+
+
+def _validate_tracing_section(tracing_section: Any) -> list[ValidationFinding]:
+    """Validate the optional ``tracing:`` section of ``integrations.yml``.
+
+    Reuses :func:`~rasa.calm_v2.config.tracing.parse_tracing` for shape and
+    type checks, then
+    :func:`~rasa.tracing.langfuse_config.validate_langfuse_config_mapping` for
+    ``${VAR}`` key syntax and the optional environment name — the same rules
+    the runtime apply path enforces. A missing section is valid (tracing is
+    optional).
+    """
+    if tracing_section is None:
+        return []
+    if not isinstance(tracing_section, Mapping):
+        return [
+            ValidationFinding(
+                code=_INVALID_TRACING_CODE,
+                message=(
+                    f"The 'tracing:' section of '{V2_INTEGRATIONS_FILE}' must "
+                    "be a mapping with Langfuse settings."
+                ),
+            )
+        ]
+
+    try:
+        settings = parse_tracing(tracing_section)
+    except RasaException as error:
+        return [
+            ValidationFinding(
+                code=_INVALID_TRACING_CODE,
+                message=str(error),
+            )
+        ]
+
+    try:
+        validate_langfuse_config_mapping(settings.as_config_dict())
+    except InvalidLangfuseConfigException as error:
+        return [
+            ValidationFinding(
+                code=_INVALID_TRACING_CODE,
+                message=(
+                    f"The 'tracing:' section of '{V2_INTEGRATIONS_FILE}' is "
+                    f"invalid: {error}"
+                ),
+            )
+        ]
+    return []

{rasa_pro-3.19.0.dev3 → rasa_pro-3.19.0.dev4}/rasa/calm_v2/default_skills/default_continue_interrupted/skill.md

@@ -13,8 +13,9 @@ steps:
   # skip the resume ask on a repeat digression. The proper fix — resetting
   # skill memory when a (default) skill (re)activates, plus honouring
   # ask_before_filling — is tracked in ENG-2983
-  # (https://rasahq.atlassian.net/browse/ENG-2983). force_collection was the
-  # local workaround but it blocks deterministic completion, so it is not used.
+  # (https://rasahq.atlassian.net/browse/ENG-2983). Do not use
+  # ``force_collection``: that key was removed and skill load rejects it with a
+  # migration hint to ``ask_before_filling: true``.
   #
   # When this skill activates, the engine seeds public memory
   # ``interrupted_task_name`` with a human-readable label for the paused task.