mcp_profile library

MCP Profile — Profile evaluation runtime for MCP applications.

0.2.0 public surface per docs/02_SDD/SDD.md v0.2.0.

The public surface exposes:

  1. The five capability-named standard port adapters under src/adapters/ — these implement the mcp_bundle contracts MetricsPort, AppraisalPort, DecisionPort, ExpressionPort and ProfileSummariesPort. They are the only port types hosts should wire.
  2. The unified ProfileRuntime and its execution context / stacking / conflict-resolution support types.
  3. The internal engine contracts (AppraisalEnginePort, DecisionEnginePort, ExpressionEnginePort, EnginePorts). These are re-exported because custom engine implementations and tests need them — external hosts should not depend on their details directly.
  4. The domain model (Profile, AppraisalMetricDef, DecisionPolicy, ExpressionPolicy, etc.).
  5. Feature modules (cache, versioning, concurrency, factgraph integration).

Classes

AggregationConfig
Configuration for aggregating multiple metrics.
AlwaysTrueCondition
A condition that always evaluates to true (for default case).
AppraisalCacheConfig
Configuration for caching appraisal port behavior.
AppraisalEngine
Engine for computing appraisal metrics at runtime.
AppraisalEnginePort
Engine contract for appraisal metric computation.
AppraisalMetadata
Metadata about the appraisal computation.
AppraisalMetricDef
Definition of an appraisal metric.
AppraisalPortAdapter
Adapter implementing bundle.AppraisalPort.
AppraisalResult
Complete result of appraisal metric computation.
AppraisalSection
Section defining metrics and their aggregation.
AudienceConfig
Configuration for audience adaptation.
AudiencePreferences
Audience preferences.
BooleanNormalization
Boolean normalization: converts truthy/falsy to 1.0/0.0. Threshold determines the boundary (default: 0.5). Values >= threshold → 1.0, values < threshold → 0.0.
CachingAppraisalEnginePort
AppraisalEnginePort decorator that adds caching.
Capability
A capability that a profile can have.
CapabilityBuilder
Fluent builder for creating capabilities.
Clock
Clock abstraction for testability.
CompatConfig
Compatibility requirements for a profile.
CompositeCondition
Composite condition combining multiple conditions.
ComputedSource
Source that computes metric from other metrics using expression.
ConcurrentEvaluationConfig
Configuration for concurrent policy evaluation.
ConditionDetail
Detail about a single condition.
ConditionEvaluationResult
Result of evaluating a single policy condition.
ConfidenceThresholdConfig
Configuration for confidence threshold behavior in appraisal.
ConflictResolver
Abstract conflict resolver using strategy pattern.
CustomNormalization
Custom normalization using expression. Expression should contain 'value' variable and return 0-1.
DateTimeRange
A time range with start and end.
DecisionEnginePort
Engine contract for decision policy evaluation.
DecisionGuidance
Guidance returned when a policy condition matches.
DecisionModifier
Additional modifier for a decision.
DecisionPolicy
A single decision policy.
DecisionPolicyEvaluator
Evaluator that matches policies against appraisal results.
DecisionPolicySection
Section containing decision policies.
DecisionPortAdapter
Adapter implementing bundle.DecisionPort.
DecisionResult
Decision result wrapper type per design/02-ports.md §6. Wraps DecisionGuidance with evaluation metadata for downstream consumers.
DefaultDecisionEnginePort
Default sequential evaluator backed by condition matching.
DefaultPolicyConditionEvaluator
Default condition evaluator using PolicyCondition's built-in evaluate method.
DefaultRuntimeContext
Default implementation of RuntimeProfileContext.
EnginePorts
Container for the three internal engine contracts plus the optional consumed standard ports (FactsPort/PatternsPort/SummariesPort/LlmPort).
ExpressionCondition
Complex condition using expression language.
ExpressionEnginePort
Engine contract for expression formatting and condition evaluation.
ExpressionError
Expression evaluation error.
ExpressionEvaluator
Evaluates template expressions in profile content.
ExpressionPolicy
A single expression policy.
ExpressionPolicyEvaluator
Evaluator that matches expression policies and applies styles.
ExpressionPolicySection
Section containing expression policies.
ExpressionPortAdapter
Adapter implementing mcp_bundle's bundle.ExpressionPort.
ExpressionResult
Result of expression policy evaluation.
ExpressionResultMetadata
Metadata about expression evaluation.
ExpressionStyle
Complete expression style configuration.
ExpressionStyleFormatter
Formatter that applies expression style to raw content.
FactGraphSource
Source that queries FactGraph for facts/events and computes metric.
FirstMatchResolver
First match resolver.
FixedClock
Fixed clock for deterministic tests.
FormatConfig
Configuration for response format.
FormattedResponse
Formatted response from expression processing.
GrammarConfig
Grammar configuration.
HedgingConfig
Configuration for hedging language.
HedgingPhrases
Custom hedging phrases.
HighestPriorityResolver
Highest priority resolver.
LanguageConfig
Configuration for language and localization.
LlmDerivedSource
Source that uses LLM for complex analysis.
LogNormalization
Logarithmic normalization: log(value + 1) / scale, clamped to 0, 1.
MergeResolver
Merge resolver.
MergeStackingPolicy
Merge all profiles into one combined profile.
MetricCacheConfig
Configuration for the metric caching service.
MetricCacheEntry
A cached metric computation result.
MetricCachingService
Three-level metric caching service.
MetricComputeResult
Internal computation result carrier (pre-normalization output).
MetricResult
Result for a single computed metric.
MetricResultConverter
Utility for converting compute results to output MetricResults.
MetricSource
Definition of how to compute a metric value.
MetricsPortAdapter
Adapter implementing bundle.MetricsPort.
MetricTrendAnalysis
Analysis of metric trends over time.
MigrationInfo
Migration information for a profile version per §2.
MigrationResult
Result of a migration operation.
MigrationScriptRunner
Interface for running migration scripts per §4.
MigrationStep
A single step in a migration path.
MinMaxNormalization
MinMax normalization: scale value from min, max to 0, 1.
MostRestrictiveResolver
Most restrictive resolver.
NoOpApplicationHook
No-op hook for default behavior.
NormalizationConfig
Configuration for normalizing raw metric values to 0-1 range.
ParallelPolicyEvaluator
Evaluates policies concurrently with configurable batching and conflict resolution per design/06-concurrency.md §3.
PassthroughExpressionEnginePort
Identity engine port: returns content unchanged.
PassthroughNormalization
Passthrough normalization: value is already in 0-1 range, just clamp.
Policy
Base interface for all policy types (Decision, Expression).
PolicyCondition
Condition for when a policy applies.
PolicyConditionEvaluator
Interface for evaluating policy conditions per §3.
PolicyEvaluationError
Error during policy evaluation.
PolicyEvaluationExplanation
Explanation of a policy evaluation.
PolicyEvaluationMetadata
Metadata about the evaluation process.
PolicyEvaluationResult<P>
Result of parallel policy evaluation.
PolicyMatch<P>
A matching policy with evaluation metadata.
Profile
Represents an AI profile/persona definition.
ProfileApplicationMetadata
Metadata for profile application execution per design/03-runtime.md §5.
ProfileApplicationResult
Complete profile application result per design/03-runtime.md §5.
ProfileBuilder
Fluent builder for creating profiles.
ProfileContext
Profile context for runtime evaluation.
ProfileGroup
Profile group for organizing related profiles.
ProfileManifest
Identity and metadata for a profile bundle.
ProfileMigration
Describes a migration between two profile versions.
ProfileQueryCriteria
Criteria for querying profile history.
ProfileQueryPort
Port for querying profile history.
ProfileRegistry
Registry for managing profiles.
ProfileRenderer
Renders profiles into prompts.
ProfileRenderOptions
Options for profile rendering.
ProfileRun
Profile evaluation run entity for persistence.
ProfileRuntime
Profile application runtime per docs/03_DDD/core-runtime.md v0.2.0.
ProfileRuntimeHook
Hook for runtime events per design/03-runtime.md §6.
ProfileSection
A section within a profile.
ProfileStackConfig
Configuration for profile stacking behavior.
ProfileStackingPolicy
Policy for stacking profiles.
ProfileSummariesPortAdapter
Adapter implementing bundle.ProfileSummariesPort.
ProfileVersion
Parsed semantic version per design/05-versioning.md §2.
ProfileVersionMigrator
Handles migration of profile data between versions per §4.
ProfileVersionResolver
Resolves profile versions based on constraints and lifecycle per §3.
RenderedSection
A rendered section.
ReplaceStackingPolicy
Highest-priority profile wins entirely (no merging).
RuntimeContextBuilder
Fluent builder for RuntimeProfileContext.
RuntimeProfileContext
Immutable context for profile evaluation.
SectionBuilder
Fluent builder for creating sections.
ShortCircuitConfig
Short-circuit optimization configuration.
SigmoidNormalization
Sigmoid normalization: smooth S-curve transition around midpoint.
SpecProfileBundle
Spec-compliant profile bundle per schema v0.1.0.
StackedEvaluationResult<P>
Result of evaluating policies across multiple stacked profiles.
StackedPolicyEvaluator
Evaluates policies across multiple stacked profiles concurrently per §5.
StackingProfileRuntime
Runtime that supports multiple profiles via stacking.
StackStackingPolicy
Evaluate all profiles in sequence, accumulate results.
StandardCapabilities
Standard capability IDs.
StandardExpressionPolicies
Standard expression policies per §10.
StandardMetrics
Standard metric definitions as per §6.
StandardPolicies
Standard decision policies as per §7.
StaticSource
Source with a fixed constant value.
StepMigrationResult
Result of a single migration step.
StubAppraisalEnginePort
Stub engine port returning stable defaults (test/bootstrap use).
StubDecisionEnginePort
Stub engine port that always returns defaultProceed.
StubProfileQueryPort
Stub implementation for testing.
SystemClock
System clock implementation.
TemplateVariable
A template variable within section content.
ThresholdCondition
Simple metric threshold comparison.
ToneConfig
Configuration for communication tone.
VersionCompatibility
Compatibility information for a profile version per §2.
VersionConstraint
Version constraint specification per §2.
VersionConstraintParsed
Parsed version constraint details per §2.
VersionedProfile
Lightweight container pairing a version string with its lifecycle status.
VersionedProfileRegistry
Versioned profile registry.
VersionResolutionConfig
Configuration for version resolution behavior.
VocabularyConfig
Vocabulary configuration.
ZScoreNormalization
ZScore normalization: standardize using mean and standard deviation. Output is clamped to 0, 1 using sigmoid on z-score.

Enums

AggregationMethod
Aggregation methods (§7).
AudienceContext
Audience context.
CacheLevel
Cache hierarchy levels.
ComparisonOperator
Comparison operators for threshold conditions.
ConflictResolution
Conflict resolution strategies.
DecisionAction
Actions that can be recommended by a decision policy.
Directness
Directness levels.
Empathy
Empathy levels.
Expertise
Expertise levels.
ExpressionErrorType
Expression error types.
ExpressionSyntax
Expression syntax types.
FactAggregation
Aggregation functions for fact queries.
Formality
Formality levels.
HedgingLevel
Hedging levels.
HedgingPosition
Hedging position.
JargonLevel
Jargon levels.
Length
Response length types.
LlmOutputType
LLM output types for llm_derived source.
MetricSourceType
Source type for metric computation.
ModifierType
Types of decision modifiers.
ProfileRunStatus
Status of a profile evaluation run.
ProfileScope
Application scope for a profile.
ProfileStackMode
Stacking mode determines how multiple profiles are combined.
ProfileVersionStatus
Version lifecycle states.
SectionOrdering
Section ordering strategies.
SectionType
Types of profile sections.
SentenceComplexity
Sentence complexity.
Structure
Response structure types.
ToneConfidence
Tone confidence levels.
TrendDirection
Trend direction for metric analysis.
VersionConstraintType
Version constraint types.
VisualPreference
Visual preference.
VoicePreference
Voice preference.

Functions

createResolver(ConflictResolution strategy) → ConflictResolver
Factory to create a resolver from a ConflictResolution strategy.
mergeDecisionPolicies(List<SpecProfileBundle> profiles) → DecisionPolicySection?
Merge decision policies from multiple profiles (§7.3). Policies are prefixed with profile ID and boosted by profile priority.
mergeExpressionPolicies(List<SpecProfileBundle> profiles) → ExpressionPolicySection?
Merge expression policies from multiple profiles.
mergeExpressionStyles(List<ExpressionStyle> styles) → ExpressionStyle
Merge expression styles from multiple policies (§7.4).
mergeMetrics(List<SpecProfileBundle> profiles) → List<AppraisalMetricDef>
Merge metrics from multiple profiles (§7.2). First occurrence wins (profiles are assumed sorted by priority).
resolveConflictingGuidance(List<DecisionGuidance> matches, ConflictResolution strategy) → DecisionGuidance
Resolve conflicting guidance from multiple matched policies.

Typedefs

ConflictResolutionStrategy = ConflictResolution
Alias for use in stacking/resolution contexts.
DefaultProfileContext = DefaultRuntimeContext
Alias for DefaultRuntimeContext.
ExpressionFilter = dynamic Function(dynamic value, List<String> args)
A filter that transforms values in expressions.
ExpressionFunction = dynamic Function(List args, ProfileContext context)
A function that can be called from expressions.
ProfileApplicationHook = ProfileRuntimeHook
Alias for backward compatibility.
ProfileContextBuilder = RuntimeContextBuilder
Alias for RuntimeContextBuilder.

Exceptions / Errors

MigrationScriptRequiredException
Exception thrown when a breaking migration requires a script.
NoMigrationPathException
Exception thrown when no migration path exists between versions.
PolicyEvaluationException
Exception thrown when policy evaluation fails with failOnError.
PolicyNotFoundException
Exception thrown when a policy is not found.
ProfileNotFoundException
Exception thrown when a profile is not found.
VersionConstraintException
Exception thrown when no version matches a constraint.