@traits-dev/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Hambleton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @traits-dev/core
+
+Core SDK for traits.dev personality profiles: validate, compile, inject, and evaluate.
+
+## Install
+
+```bash
+pnpm add @traits-dev/core
+```
+
+## Basic Usage
+
+```ts
+import { compileProfile, validateProfile } from "@traits-dev/core";
+
+const profilePath = "profiles/resolve.yaml";
+const validation = validateProfile(profilePath);
+if (validation.exitCode !== 0) throw new Error("Invalid profile");
+
+const compiled = compileProfile(profilePath, {
+  model: "gpt-4o",
+  bundledProfilesDir: "profiles",
+  knowledgeBaseDir: "knowledge-base"
+});
+
+console.log(compiled.text);
+```
+
+Public API is exported from `@traits-dev/core`. Monorepo/internal helpers are exported from `@traits-dev/core/internal`.

package/dist/index-CkGiIKnu.d.cts

@@ -0,0 +1,352 @@
+type Level = "very-low" | "low" | "medium" | "high" | "very-high";
+type DimensionName = "formality" | "warmth" | "verbosity" | "directness" | "empathy" | "humor";
+type HumorStyle = "none" | "dry" | "subtle-wit" | "playful";
+type DimensionShorthand = Level;
+type DimensionObject = {
+    target: Level;
+    adapt?: boolean;
+    floor?: Level;
+    ceiling?: Level;
+};
+type HumorDimensionObject = DimensionObject & {
+    style?: HumorStyle;
+};
+type DimensionValue = DimensionShorthand | DimensionObject;
+type HumorDimensionValue = DimensionShorthand | HumorDimensionObject;
+interface VocabularyConstraints {
+    preferred_terms?: string[];
+    forbidden_terms?: string[];
+    preferred_terms_remove?: string[];
+    forbidden_terms_remove?: string[];
+}
+interface ContextAdaptation {
+    when: string;
+    adjustments?: Partial<Record<DimensionName, DimensionValue | HumorDimensionValue>>;
+    inject?: string[];
+    priority?: number;
+}
+interface PersonalityProfile {
+    schema: string;
+    meta: {
+        name: string;
+        version: string;
+        description: string;
+        tags?: string[];
+        target_audience?: string;
+        [key: string]: unknown;
+    };
+    identity: {
+        role: string;
+        backstory?: string;
+        expertise_domains?: string[];
+        [key: string]: unknown;
+    };
+    voice: {
+        formality: DimensionValue;
+        warmth: DimensionValue;
+        verbosity: DimensionValue;
+        directness: DimensionValue;
+        empathy: DimensionValue;
+        humor: HumorDimensionValue;
+        [key: string]: DimensionValue | HumorDimensionValue | undefined;
+    };
+    vocabulary?: VocabularyConstraints;
+    behavioral_rules?: string[];
+    context_adaptations?: ContextAdaptation[];
+    localization?: Record<string, unknown>;
+    channel_adaptations?: Record<string, unknown>;
+    extends?: string;
+    behavioral_rules_remove?: string[];
+    context_adaptations_remove?: string[];
+    [key: string]: unknown;
+}
+interface ValidationDiagnostic {
+    code: string;
+    severity: "warning" | "error";
+    message: string;
+    location?: string;
+    promotedFrom?: string;
+    details?: unknown;
+}
+interface ValidationCheckSummary {
+    status: "pass" | "warning" | "error";
+    errors: number;
+    warnings: number;
+}
+interface ValidationResult {
+    profilePath?: string;
+    parentPath: string | null;
+    profile: PersonalityProfile | null;
+    strict: boolean;
+    warnings: ValidationDiagnostic[];
+    errors: ValidationDiagnostic[];
+    promotedWarnings: ValidationDiagnostic[];
+    effectiveErrors: ValidationDiagnostic[];
+    constraintCount: number;
+    constraintBreakdown: {
+        behavioral_rules: number;
+        vocabulary_preferred_terms: number;
+        vocabulary_forbidden_terms: number;
+        context_adaptations: number;
+        [key: string]: number;
+    };
+    checks: Record<string, ValidationCheckSummary>;
+    isValid: boolean;
+    exitCode: number;
+}
+interface CompiledPersonality {
+    text: string;
+    placement: {
+        model: string;
+        recommended_position: "start" | "after_tools" | "end";
+        rationale: string;
+    };
+    metadata: {
+        profile: string;
+        version: string;
+        schema_version: string;
+        model_target: string;
+        token_count: number;
+        safety_floor_included: boolean;
+        adaptive_dimensions: string[];
+        humor_style: string | null;
+        compilation_timestamp: string;
+    };
+    trace?: {
+        context_matches: string[];
+        adjustments_applied: Record<string, unknown>;
+        inject_rules: string[];
+        protected_refusal_terms_restored: string[];
+        pattern_selections: unknown[];
+        interaction_patterns: unknown[];
+    };
+    validation?: {
+        warnings: ValidationDiagnostic[];
+        errors: ValidationDiagnostic[];
+        strict: boolean;
+    };
+}
+interface ExtendsDiagnostics {
+    warnings: ValidationDiagnostic[];
+    errors: ValidationDiagnostic[];
+}
+interface ExtendsResult {
+    profile: PersonalityProfile;
+    parentPath: string | null;
+    diagnostics: ExtendsDiagnostics;
+}
+interface ContextResolution {
+    matched: ContextAdaptation[];
+    resolvedAdjustments: Record<string, DimensionValue>;
+    injectRules: string[];
+}
+
+type ResolveOptions = {
+    bundledProfilesDir?: string;
+};
+
+declare function loadProfileFile(filePath: string): PersonalityProfile;
+
+declare function resolveExtends(profilePath: string, options?: ResolveOptions): ExtendsResult;
+
+declare function normalizeProfile(profilePath: string, options?: ResolveOptions): PersonalityProfile;
+
+declare function resolveActiveContext(profile: PersonalityProfile, context?: Record<string, unknown>): ContextResolution;
+
+declare function validateResolvedProfile(profile: PersonalityProfile, options?: {
+    strict?: boolean;
+}): ValidationResult;
+declare function validateProfile(profilePath: string, options?: {
+    strict?: boolean;
+    bundledProfilesDir?: string;
+}): ValidationResult;
+
+type CompileOptions = {
+    model?: string;
+    context?: Record<string, unknown>;
+    explain?: boolean;
+    strict?: boolean;
+    bundledProfilesDir?: string;
+    knowledgeBaseDir?: string;
+};
+declare function compileResolvedProfile(profile: PersonalityProfile, options?: CompileOptions): CompiledPersonality;
+declare function compileProfile(profilePath: string, options?: CompileOptions): CompiledPersonality;
+
+type CompiledLike = string | Pick<CompiledPersonality, "text" | "placement">;
+declare function injectPersonality({ compiledPersonality, system, model }: {
+    compiledPersonality: CompiledLike;
+    system?: string;
+    model?: string;
+}): string;
+
+type EvalSample = {
+    id?: string;
+    prompt?: string;
+    response?: string;
+};
+declare function validateEvalScenario(scenario: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+declare function validateEvalScenarios(scenarios: unknown): {
+    valid: boolean;
+    count: number;
+    invalid: Array<{
+        index: number;
+        id: string | null;
+        errors: string[];
+    }>;
+};
+
+type Tier1Options = {
+    includeHelpfulness?: boolean;
+    strict?: boolean;
+    bundledProfilesDir?: string;
+};
+declare function evaluateTier1Response(profile: PersonalityProfile, responseText: string, options?: Tier1Options): {
+    score: number;
+    checks: {
+        vocabulary: {
+            preferred_total: number;
+            preferred_matched: number;
+            forbidden_total: number;
+            forbidden_matched: number;
+            pass: boolean;
+        };
+        structure: {
+            behavioral_rule_count: number;
+            response_non_empty: boolean;
+            pass: boolean;
+        };
+        helpfulness: {
+            char_count: number;
+            pass: boolean;
+            skipped: boolean;
+        };
+    };
+};
+declare function runTier1Evaluation(profile: PersonalityProfile, samples: EvalSample[], options?: Tier1Options): {
+    tier: number;
+    sample_count: number;
+    average_score: number;
+    samples: Array<{
+        id: string;
+        score: number;
+        checks: ReturnType<typeof evaluateTier1Response>["checks"];
+    }>;
+};
+declare function runTier1EvaluationForProfile(profilePath: string, samples: EvalSample[], options?: Tier1Options): {
+    validation: ValidationResult;
+    report: ReturnType<typeof runTier1Evaluation>;
+};
+
+type Tier2Options = {
+    includeHelpfulness?: boolean;
+    strict?: boolean;
+    bundledProfilesDir?: string;
+    openaiApiKey?: string;
+    embeddingModel?: string;
+    openaiBaseUrl?: string;
+    openAIBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+    fetchTimeoutMs?: number;
+    fetchMaxRetries?: number;
+    fetchRetryBaseMs?: number;
+    embeddingFn?: (text: string) => Promise<number[]>;
+    knowledgeBaseDir?: string;
+    modelTarget?: string;
+};
+declare function runTier2Evaluation(profile: PersonalityProfile, samples: EvalSample[], options?: Tier2Options): Promise<{
+    tier: number;
+    provider: string;
+    helpfulness_included: boolean;
+    sample_count: number;
+    average_score: number;
+    dimension_averages: Record<string, number>;
+    helpfulness_average: number | null;
+    samples: Array<{
+        id: string;
+        score: number;
+        dimension_scores: Record<string, number>;
+        helpfulness_score: number | null;
+    }>;
+}>;
+declare function runTier2EvaluationForProfile(profilePath: string, samples: EvalSample[], options?: Tier2Options): Promise<{
+    validation: ValidationResult;
+    report: Awaited<ReturnType<typeof runTier2Evaluation>>;
+}>;
+
+type Tier3Options = {
+    includeHelpfulness?: boolean;
+    strict?: boolean;
+    bundledProfilesDir?: string;
+    provider?: string;
+    judgeFn?: (args: {
+        systemPrompt: string;
+        userPrompt: string;
+    }) => Promise<string>;
+    openaiApiKey?: string;
+    anthropicApiKey?: string;
+    judgeModel?: string;
+    openaiBaseUrl?: string;
+    openAIBaseUrl?: string;
+    anthropicBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+    fetchTimeoutMs?: number;
+    fetchMaxRetries?: number;
+    fetchRetryBaseMs?: number;
+};
+declare function runTier3Evaluation(profile: PersonalityProfile, samples: EvalSample[], options?: Tier3Options): Promise<{
+    tier: number;
+    provider: string;
+    helpfulness_included: boolean;
+    sample_count: number;
+    average_score: number;
+    samples: Array<{
+        id: string;
+        score: number;
+        dimension_average: number;
+        formality: number;
+        warmth: number;
+        verbosity: number;
+        directness: number;
+        empathy: number;
+        humor: number;
+        helpfulness: number | null;
+        rationale: string;
+    }>;
+}>;
+declare function runTier3EvaluationForProfile(profilePath: string, samples: EvalSample[], options?: Tier3Options): Promise<{
+    validation: ValidationResult;
+    report: Awaited<ReturnType<typeof runTier3Evaluation>>;
+}>;
+
+type ImportOptions = {
+    provider?: string;
+    analysisFn?: (args: {
+        systemPrompt: string;
+        userPrompt: string;
+    }) => Promise<unknown>;
+    openaiApiKey?: string;
+    anthropicApiKey?: string;
+    model?: string;
+    openaiBaseUrl?: string;
+    openAIBaseUrl?: string;
+    anthropicBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+    fetchTimeoutMs?: number;
+    fetchMaxRetries?: number;
+    fetchRetryBaseMs?: number;
+    profileName?: string;
+    description?: string;
+};
+declare function mapImportAnalysisToProfile(analysis: unknown, options?: ImportOptions): PersonalityProfile;
+declare function renderImportedProfileYAML(profile: PersonalityProfile): string;
+declare function runImportAnalysis(promptText: unknown, options?: ImportOptions): Promise<{
+    provider: string;
+    analysis: Record<string, unknown>;
+    profile: PersonalityProfile;
+    yaml: string;
+}>;
+
+export { runImportAnalysis as A, runTier1EvaluationForProfile as B, type CompileOptions as C, type DimensionName as D, type EvalSample as E, runTier2Evaluation as F, runTier2EvaluationForProfile as G, type HumorDimensionObject as H, type ImportOptions as I, runTier3Evaluation as J, runTier3EvaluationForProfile as K, type Level as L, validateEvalScenario as M, validateEvalScenarios as N, validateProfile as O, type PersonalityProfile as P, validateResolvedProfile as Q, type Tier1Options as T, type ValidationResult as V, type ValidationCheckSummary as a, type ValidationDiagnostic as b, type CompiledPersonality as c, type ContextAdaptation as d, type ContextResolution as e, type DimensionObject as f, type DimensionShorthand as g, type DimensionValue as h, type ExtendsDiagnostics as i, type ExtendsResult as j, type HumorDimensionValue as k, type HumorStyle as l, type Tier2Options as m, type Tier3Options as n, type VocabularyConstraints as o, compileProfile as p, compileResolvedProfile as q, runTier1Evaluation as r, evaluateTier1Response as s, injectPersonality as t, loadProfileFile as u, mapImportAnalysisToProfile as v, normalizeProfile as w, renderImportedProfileYAML as x, resolveActiveContext as y, resolveExtends as z };