emcie-co--parlant/CHANGELOG.md

Changelog

All notable changes to Parlant will be documented here.

[Unreleased]

Added

• Add HealthReporter (parlant.core.health_reporter) — a generic, per-process health-reporting service registered in the container. Subsystems call report(kind, attributes); registered HealthView objects interpret reports per kind and contribute to the /healthz snapshot. Each kind has a configurable retention policy (window + max_count). Views declare Criticality.CRITICAL or INFORMATIONAL; only critical views feed the worst-of overall status rollup
• Add NLPHealthView reporting NLP request health sliced by schema (success rate, p50/p95 latency, recent error breakdown) with configurable thresholds for degraded/unhealthy classification
• Instrument BaseSchematicGenerator.generate() and BaseEmbedder.embed() to emit nlp.request / nlp.embed health reports on success and failure, providing dashboard visibility into LLM and embedding behavior across all adapters
• Wrap the existing event-loop check as EventLoopHealthView so /healthz rollup is uniform across all health views
• Add per-decision debug logs to journey node selection (Journey '<title>': advanced/stayed/exited/completed/backtracked/auto-advanced/...) so journey progression is visible at debug level alongside guideline matching
• Add a warning log for invalid condition ids returned during journey next-step selection

Changed

• Rename journey conditions to triggers throughout the codebase, REST API, CLI, and SDKs to better reflect their role as activation signals. The REST API field, query parameter, and request bodies use triggers (no aliases). The Python SDK Server.create_journey(...) keeps conditions= as a deprecated keyword that emits a DeprecationWarning; passing both triggers= and conditions= raises an error. Existing journey records are migrated automatically by parlant-prepare-migration from the journey_conditions collection (with a condition field) to a new journey_triggers collection (with a trigger field). LLM prompt strings that include "Journey activation condition" are intentionally preserved
• Rename SDK callback on_match to on_selected on guidelines and journey state transitions to reflect that it fires post-resolution, when the entity is selected for message generation; EngineHooks.on_guideline_match_handlers and on_journey_match_handlers are renamed to on_guideline_selected_handlers and on_journey_selected_handlers accordingly
• Standardize guideline matcher log vocabulary: "Activated" → "Matched", "Skipped" → "Not matched", and "Not applied" → "Unapplied"
• Standardize relational resolver log vocabulary: "Skipped: ... deactivated due to ..." → "Dropped (<reason>): ..." with reasons lower priority, unmet dependency, dependency on dropped entity, deprioritized by guideline, and deprioritized by journey
• Disambiguation batch now uses the standard matcher vocabulary ("Matched (disambiguation)" / "Not matched (disambiguation)") and emits a log on the negative branch (previously silent)
• Normalize observational batch rationale to plain match.rationale (no longer wrapped with Condition Application Rationale: "...") for consistency with other batches
• Normalize low-criticality batch warning string to "No checks generated" to match other batches

Removed

• Remove redundant glm_service.py NLP adapter and NLPServices.glm() factory method — the GLM/bigmodel.cn API is already covered by the existing Zhipu adapter (zhipu_service.py), which uses the official zhipuai SDK and supports GLM-4 model variants. Use NLPServices.zhipu() instead.

Fixed

• Fix low-criticality matcher logging the entire inference blob once per guideline in a batch (N copies of the same payload at debug level); now logs a single per-item entry
• Fix WebSocketLogger event loop starvation — when no WebSocket clients are subscribed, the drain loop processed queued messages without yielding, progressively blocking the async event loop and causing increasing latency over time
• Fix journey reachable-follow-ups evaluation being order-dependent at fan-in nodes — JourneyReachableNodesEvaluator captured a child's path list by reference and then prepended to it in place, so a node with multiple parents had its stored routes mutated by whichever parent was visited first; the second parent then lost routes (or double-counted a hop) depending purely on graph/DFS order. The child's routes are now snapshotted per parent, making the result depend only on journey structure. This intentionally changes the computed follow-ups for existing fan-in journeys: a shared child's later parent now retains the routes it previously lost

Security

• Upgrade dependencies to address known CVEs: authlib (>=1.6.11), requests (>=2.33.0), fastmcp (>=3.2.0), litellm (>=1.83.0), pytest (>=9.0.3), pyjwt (>=2.11.1), and constrain transitive deps — aiohttp, cryptography, pillow, pyopenssl, werkzeug, Mako, pyasn1, python-multipart, orjson, Pygments, diskcache
• Upgrade chat frontend: vite (>=7.3.2) and override transitive deps — picomatch, lodash, flatted, brace-expansion, immutable, yaml

[3.3.1] - 2026-04-14

Added

• Allow passing ToolId when attaching tools throughout the SDK
• Add AnyOf(tag) and AllOf(tag) modifiers for explicit control over tag dependency semantics in depend_on() — AnyOf requires at least one tagged member to be active, AllOf requires all of them (bare Tag defaults to AllOf)
• Add depend_on_any() to Guideline, Tag, and Journey for OR dependency relationships — at least one target must be active. Multiple depend_on_any() calls create independent OR groups that are AND'd together
• Add event loop health monitoring to /healthz endpoint — measures callback latency and reports healthy, degraded, or unhealthy status with peak latency over a configurable window
• Add resolution tracking to the relational resolver — every entity that enters resolution gets a Resolution with a ResolutionKind (NONE, DEPRIORITIZED, UNMET_DEPENDENCY_ALL, UNMET_DEPENDENCY_ANY, ENTAILED) and structured ResolutionDetails (relationship ID, target IDs) explaining why

Changed

• Split RelationshipEntityKind.TAG into TAG_ALL and TAG_ANY to support explicit tag dependency semantics at the core level (existing TAG entries treated as TAG_ALL for backwards compatibility)

Fixed

• Fix priority and dependency relationships propagating through inactive intermediaries — only direct relationships now affect resolution, consistent with the reinstatement principle from argumentation theory
• Fix entailment recording only the highest-scoring source when multiple guidelines entail the same target — all entailing relationships are now recorded in resolution details
• Fix dep-failed guidelines not recovering when entailment satisfies their dependency target in a later iteration
• Fix SDK startup appearing stuck at 100% after evaluations — add "Applying evaluations" progress bar for the metadata-writing phase
• Fix Variable.get_value() returning None when called from a retriever, caused by retrievers starting before context variables were loaded
• Fix journey tool-state auto-advancing even when the tool did not run

[3.3.0] - 2026-03-15

Added

• Add per-agent planners via Server.create_agent(planner=...), allowing each agent to use a custom Planner implementation
• Accept Tag as a target in depend_on(), exclude(), and prioritize_over() on both Guideline and Tag, enabling relationships that target all guidelines sharing a custom tag
• Add Tag.depend_on(), Tag.exclude(), and Tag.prioritize_over() methods to the SDK, enabling tag-based dependency and priority relationships with guidelines and journeys
• Support custom TAG as source for DEPENDENCY relationships in the relational resolver
• Add tags parameter to create_guideline, create_observation, and create_journey on both Agent and Journey, allowing custom tags to be attached to entities at creation time
• Add Tag.reevaluate_after() method to the SDK, enabling tag-based reevaluation relationships with tools
• Add tag-based reevaluation support in the engine: when a tool fires, all guidelines carrying a tag that has a reevaluation relationship with that tool are now re-evaluated
• Add staged_events to GuidelineMatchingContext in SDK
• Add priority property to guidelines and journeys for priority-based filtering in the relational resolver
• Add transient guidelines (renamed from tool-provided guidelines), allowing tools to dynamically inject behavioral guidelines into the agent's context
• Add Agent.utter() to the SDK, enabling programmatic agent message generation with transient guidelines
• Add Customer.update() and CustomerMetadata to the SDK, allowing tools to update customer name and metadata
• Add Session.update(), SessionMetadata, and SessionLabels to the SDK, allowing tools to update session properties, metadata, and labels
• Add customer, agent, mode, and title properties to SDK Session class
• Add Server.get_tag() to the SDK, supporting lookup by either id or name
• Add name-based filtering to TagStore.list_tags() and the GET /tags API endpoint via an optional name query parameter
• Enforce tag name uniqueness in TagStore, raising an error when creating a tag with a duplicate name

Changed

• Made extended thinking indicator optional in perceived performance policy
• Change reevaluate_after() on Tag and Guideline to accept multiple tools (*tools) and return Sequence[Relationship]
• Change tags field type from Sequence[TagId] to Sequence[Tag] on Guideline, Journey, Capability, Term, Variable, Customer, and Agent in the SDK
• Change Tag.preamble() to return a full Tag object instead of a TagId
• Upgrade MCP service and bump dependency versions to resolve security vulnerabilities

Deprecated

• OpenAPI tool services are now deprecated; please migrate to SDK tool services

Fixed

• Fix deadlock when sending a new message right after a preamble
• Fix transitive filtering in relational resolver for custom tag dependency targets (guidelines depending on a custom tag are now correctly deactivated when a tagged member is deprioritized)
• Fix SSE read_event endpoint stalling after first streaming chunk until full completion
• Fix response analysis logs not always reaching the integrated UI
• Fix guideline formatting in canned response and streaming modes when condition is absent
• Fix AzureService small text embedding dimension size
• Fix onnxruntime compatibility with Python 3.10 and transformers 5.x type changes
• Fix agent intention proposer prompt clarification
• Fix embedding LRU cache eviction corrupting the length index when entries share the same text length
• Fix LiteLLMEmbedder failing to resolve via lagom container when LITELLM_EMBEDDING_MODEL_NAME is set
• Fix non-consequential tool calls being rejected when optional parameters are missing

Removed

• Remove stale parlant-test entry point and testing framework documentation from README

[3.2.2] - 2026-02-18

Added

• Added p.MATCH_ALWAYS, now the preferred alias to p.Guideline.MATCH_ALWAYS
• Added logger property to p.Server

Changed

• Adjusted log levels of relational resolver to trace instead of debug
• Allow tool context parameter names to be all of 'context', 'ctx', and 'c'

Fixed

• Fix completed streamed messages re-animating on page refresh
• Propagate Server.current context to tool functions in hosted plugin server

[3.2.1] - 2026-02-17

Added

• Add optional dependencies parameter to guideline, observation, and journey creation methods
• Add exclude() as an alias for prioritize_over() on guidelines and journeys
• Add tools parameter to create_observation methods

Changed

• Deprecate attach_tool() in favor of create_guideline()/create_observation() with tools parameter

Fixed

• Preserve draft message language during canned response recomposition
• Fix server hang when an exception occurs during setup
• Fix canned response field extraction to handle falsy values

[3.2.0] - 2026-02-08

Added

• Add labels to Guidelines, Journeys, JourneyNodes, and Sessions for categorization and filtering
• Add automatic session label propagation from matched entities (guidelines, observations, journeys)
• Add track parameter to guidelines to control "previously applied" tracking
• Support multiple targets in prioritize_over() and depend_on() methods
• Add field_dependencies to canned responses for explicit field availability requirements
• Add attach_retriever() to Guideline, Journey, and JourneyState for conditional data retrieval
• Add on_match and on_message hooks to journeys for lifecycle callbacks
• Add per-agent preamble configuration (custom examples and instructions)
• Add separate default greeting responses for first agent message in fluid mode
• Add streaming message output mode
• Allow specifying custom journey node ID
• Add matched guidelines/journey states to completion ready event

Changed

• Make condition optional for SDK guidelines
• Tweak default preamble examples
• Soften log levels for relational guideline resolver
• Add activated/skipped logs to custom guideline matcher batches

Fixed

• Fix websocket warning upon startup
• Fix agent intention proposer (guidelines were getting rewritten incorrectly)
• Fix multiple customer guideline matchers not working
• Fix bug with context variable access in SDK

[3.1.0] - 2026-01-05

Added

• Add .current property for Server, Agent, and Customer in SDK
• Add /healthz endpoint
• Add API for CRUD operations on session metadata
• Add EmcieService
• Add GLM service
• Add Mistral service
• Add OpenRouter service
• Add OpenTelemetry integration for Meter, Logger and Tracer
• Add Qdrant VectorDatabase adapter
• Add Snowflake Cortex service
• Add ability to configure and extend the FastAPI app object
• Add deferred retrievers
• Add dynamic composition mode
• Add follow-up canned responses
• Add guideline criticality level
• Add guideline on_match() hooks
• Add persistence option for context variable values (variable store)
• Added guideline descriptions
• Allow bailing out of canned response selection and utilize the draft directly, using a hook
• Allow controlling max tool result payload via environment variable
• Allow controlling perceived performance policy per agent
• Allow journey transitions from one tool state to another
• Allow specifying custom IDs when creating agents via SDK and API
• Allow specifying custom IDs when creating customers via SDK and API
• Allow specifying custom IDs when creating guidelines, journeys, and glossary terms via SDK and API
• Expose IoC container in server object
• Support adding custom canrep fields to matched guidelines and journey states
• Support code-based, custom guideline matchers

Changed

• Changed default NLPService to EmcieService
• Improved efficiency of journey state matching when first state is a tool state
• Rename ContextualCorrelator to Tracer
• Rename LoadedContext to EngineContext
• Support proxy URL for LiteLLM

Fixed

• Fix critical bug with cancellation during response analysis
• Fix critical similarity calculation error in TransientVectorDatabase
• Fix unnecessary extra evaluation of journeys and tools in some edge cases
• Improved Gemini Flash 2.5 output consistency by using function call trick instead of structured outputs

[3.0.4] - 2025-11-18

Fixed

• Fix bug where NanoDB query failed when no filters matched
• Extend tool insights across iterations
• Fix deprecated status.HTTP_422_UNPROCESSABLE_ENTITY to status.HTTP_422_UNPROCESSABLE_CONTENT
• Fix broken CLI by adding missing websocket-client dependency
• Added specific classes for embedder initialisation
• Make base url once in OllamaEmbedder
• Update dependencies for security, upgrade FastAPI, fix mypy in hugging_face.py
• Bump torch for fixing vulnerability

[3.0.3] - 2025-10-23

Fixed

• Fix installation issue in some environments, failing due to an older FastMCP version
• Bump versions of OpenTelemetry
• Made ChromaDB an extra package parlant[chroma]
• Update NPM dependencies for integrated UI

[3.0.2] - 2025-08-27

Added

• Added docs/* and llms.txt
• Added Vertex NLP service
• Added Ollama NLP service
• Added LiteLLM support to the SDK
• Added Gemini support to the SDK
• Added Journey.create_observation() helper
• Added auth permission READ_AGENT_DESCRIPTION
• Added optional AWS_SESSION_TOKEN to BedrockService
• Support creating status events via the API

Changed

• Moved tool call success log to DEBUG level
• Optimized canrep to not generate a draft in strict mode if no canrep candidates found
• Removed acknowledged_event_offset from status events
• Removed last_known_event_offset from LoadedContext.interaction

Fixed

• Fixed presentation of missing API keys for built-in NLP services
• Improvements to canned response generation
• Fixed bug with null journey paths in some cases
• Fixed tiny bug with terminal nodes in journey node selection
• Fixed evaluations not showing properly after version upgrade

[3.0.1] - 2025-08-16

Changed

• Move tool call success log to DEBUG level

Fixed

• Fix tool-based variable not enabling the associated tool on the server
• Fix authorization errors throwing 500 instead of 403
• Changed OpenAI LLM request operation level to TRACE to fix evaluation progress bars

[3.0.0] - 2025-08-15

• Please see the announcement at https://parlant.io/blog/parlant-3-0-release

[2.2.0] - 2025-05-20

Added

• Add journeys
• Add of guideline properties evaluation
• Add automatic guideline action deduction when adding direct tool guidelines
• Added choices of invalid and missing tool parameters to tool insights

Changed

• Make guideline action optional

[2.1.2] - 2025-05-07

Changed

• Remove interaction history from utterance recomposition prompt
• Use tool calls from the entire interaction for utterance field substitution
• Improve error handling and reporting with utterance rendering failures

Fixed

• Always reason about utterance selection to improve performance

[2.1.1] - 2025-04-30

Fixed

• Fixed rendering relationships in CLI
• Fixed parlant client using old imports from python client SDK

[2.1.0] - 2025-04-29

Added

• ToolParameterOptions.choice_provider can now access ToolContext
• Added utterance/draft toggle in the integrated UI
• Added new guideline relationship: Dependency
• Added tool relationships and the OVERLAP relationship
• Added the 'overlap' property to tools. By default, tools will be assumed not to overlap with each other, simplifying their evaluation at runtime.
• Introduce ToolBatchers
• Introduce Journey

Changed

• Improved tool calling efficiency by adjusting the prompt to the tool at hand
• Revised completion schema (ARQs) for tool calling
• Utterances now follow a 2-stage process: draft + select
• Changed guest customer name to Guest

Fixed

• Fixed deprioritized guidelines always being skipped
• Fixed agent creation with tags
• Fixed client CLI exit status when encountering an error
• Fixed agent update

Known Issues

• OpenAPI tool services sometimes run into issues due to a version update in aiopenapi3

[2.0.0] - 2025-04-09

Added

• Improved tool parameter flexibility: custom types, Pydantic models, and annotated ToolParameterOptions
• Allow returning a new (modified) container in modules using configure_module()
• Added Tool Insights with tool parameter options
• Added support for default values for tool parameters in tool calling
• Added WebSocket logger feature for streaming logs in real time
• Added a log viewer to the sandbox UI
• Added API and CLI for Utterances
• Added support for the --migrate CLI flag to enable seamless store version upgrades during server startup
• Added clear rate limit error logs for NLP adapters
• Added enabled/disabled flag for guidelines to facilitate experimentation without deletion
• Allow different schematic generators to adjust incoming prompts in a structured manner
• Added tags to context variables, guidelines, glossary and agents
• Added guideline matching strategies
• Added guideline relationships
• Added support for tool parameters choice provider using the tool context as argument

Changed

• Made the message generator slightly more polite by default, following user feedback
• Allow only specifying guideline condition or action when updating guideline from CLI
• Renamed guideline proposer with guideline matcher

Fixed

• Lowered likelihood of the agent hallucinating facts in fluid mode
• Lowered likelihood of the agent offering services that were not specifically mentioned by the business

[1.6.2] - 2025-01-29

Fixed

• Fix loading DeepSeek service during server boot

[1.6.1] - 2025-01-20

Fixed

• Fix ToolCaller not getting clear information on a parameter being optional
• Ensure ToolCaller only calls a tool if all required args were given
• Improve valid JSON generation likelihood in MessageEventGenerator
• Improve ToolCaller's ability to correctly run multiple tools at once

[1.6.0] - 2025-01-19

Added

• Add shot creation helper functions under Shot
• Add ContextEvaluation in MessageEventGenerator
• Add a log command under client CLI for streaming logs
• Add engine lifecycle hooks

Changed

• Split vendor dependencies to extra packages to avoid reduce installation time
• Modified ToolCaller shot schema
• Disable coherence and connection checking by default in the CLI for now

Fixed

• Improved GuidelineProposer's ability to handle compound actions
• Improved GuidelineProposer's ability to distinguish between a fulfilled and unfulfilled action
• Improved GuidelineProposer's ability to detect a previously applied guideline's application to new information
• Reduced likelihood of agent offering hallucinated services
• Fix ToolCaller false-negative argument validation from int to float
• Fix ToolCaller accuracy
• Fix ToolCaller making up argument values when it doesn't have them
• Fix some cases where the ToolCaller also calls a less-fitting tool
• Fix mistake in coherence checker few shots
• Fix markdown tables in sandbox UI
• Fix wrong import of RateLimitError
• Fix PluginServer validation for optional tool arguments when they're passed None
• Fix utterances sometimes not producing a message

[1.5.1] - 2025-01-05

Fixed

• Fix server CLI boot

[1.5.1] - 2025-01-05

Fixed

• Fix server CLI boot

[1.5.0] - 2025-01-04

Added

• Add DeepSeek provider support (via DeepSeekService)

Changed

• Change default home dir from runtime-data to parlant-data

Fixed

• Fix tool-calling test
• Fix HuggingFace model loading issues

[1.4.3] - 2025-01-02

Fixed

• Upgraded dependency "tiktoken" to 0.8.0 to fix installation errors on some environments

[1.4.2] - 2024-12-31

Fixed

• Fix race condition in JSONFileDocumentDatabase when deleting or updating documents

[1.4.1] - 2024-12-31

Changed

• Remove tool metadata from prompts - agents are now only aware of the data itself

Fixed

• Fix tool calling in scenarios where a guideline has multiple tools where more than one should run

[1.4.0] - 2024-12-31

Added

• Support custom plugin data for PluginServer
• Allow specifying custom logger ID when creating loggers
• Add 'hosted' parameter to PluginServer, for running inside modules

Fixed

• Fix the tool caller's few shots to include better rationales and arguments.

[1.3.1] - 2024-12-27

Changed

• Return event ID instead of trace ID from utterance API
• Improve and normalize entity update messages in client CLI

[1.3.0] - 2024-12-26

Added

• Add manual utterance requests
• Refactor few-shot examples and allow adding more examples from a module
• Allow tapping into the PluginServer FastAPI app to provide additional custom endpoints
• Support for union parameters ("T | None") in tool functions

Changed

• Made all stores thread-safe with reader/writer locks
• Reverted GPT version for guideline connection proposer to 2024-08-06
• Changed definition of causal connection to take the source's when statement into account. The connection proposer now assumes the source's condition is true when examining if it entails other guideline.

Fixed

• Fix 404 not being returned if a tool service isn't found
• Fix having direct calls to asyncio.gather() instead of safe_gather()

Removed

• Removed connection kind (entails / suggests) from the guideline connection proposer and all places downstream. the connection_kind argument is no longer needed or supported for all guideline connections.

[1.2.0] - 2024-12-19

Added

• Expose deletion flag for events in Session API

Changed

• Print traceback when reporting server boot errors
• Make cancelled operations issue a warning rather than an error

Fixed

• Fixed tool calling with optional parameters
• Fixed sandbox UI issues with message regeneration and status icon
• Fixed case where guideline is applied due to condition being partially applied

Removed

None

[1.1.0] - 2024-12-18

Added

• Customer selection in sandbox Chat UI
• Support tool calls with freshness rules for context variables
• Add support for loading external modules for changing engine behavior programmatically
• CachedSchematicGenerator to run the test suite more quickly
• TransientVectorDatabase to run the test suite more quickly

Changed

• Changed model path for Chroma documents. You may need to delete your runtime-data dir.

Fixed

• Improve handling of partially fulfilled guidelines

Removed

None