@ethogram/core 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,23 @@
+# Ethogram core
+
+The code-first authoring contract for Ethogram Agents, Stories, behavioral matchers, and consumer-owned local execution profiles.
+
+This package is prepared as `@ethogram/core@0.1.0-alpha.0` but has not been published yet.
+
+## Public API
+
+Runtime values:
+
+- `defineAgent`
+- `defineStory`
+- `defineExecutionProfile`
+
+Public types cover Agent and Story authoring, legacy and structured GIVEN values, `tool-called` and `tool-not-called` matchers, the generic external execution-profile/tool contract, and framework-neutral verdict-free external execution evidence.
+
+Stories use `given`, `when`, and canonical `expectations`. `then` remains a backward-compatible alias for the alpha.
+
+Execution profiles always declare `tools`, including `tools: {}` when a third-party framework owns tool dispatch. A completed profile may return optional `ExternalExecutionEvidence`; Ethogram retains ownership of canonical observation normalization and behavioral evaluation.
+
+Story expectations declare required behavior. They never contain behavioral verdicts.
+
+The current matchers are `tool-called` and `tool-not-called`. Node.js 20.9 or newer is required. See the repository documentation for the framework-owned evidence contract and alpha limitations.

package/dist/index.cjs

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAgent = defineAgent;
+exports.defineStory = defineStory;
+exports.defineExecutionProfile = defineExecutionProfile;
+const forbiddenExpectationVerdictKeys = ['passed', 'failed', 'status', 'verdict'];
+function requiredText(value, field) {
+    if (!value.trim())
+        throw new Error(`${field} is required.`);
+}
+function assertVerdictFreeExpectations(expectations) {
+    for (const expectation of expectations) {
+        for (const key of forbiddenExpectationVerdictKeys) {
+            if (Object.prototype.hasOwnProperty.call(expectation, key)) {
+                throw new Error(`Story expectation "${expectation.id}" must not contain behavioral verdict field "${key}".`);
+            }
+        }
+    }
+}
+function assertStructuredGivenValue(value, location, ancestors) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error(`${location} must contain only finite numbers.`);
+        return;
+    }
+    if (typeof value !== 'object') {
+        throw new Error(`${location} contains unsupported value type "${typeof value}".`);
+    }
+    if (ancestors.has(value))
+        throw new Error(`${location} must not contain cyclic values.`);
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index += 1) {
+                if (!Object.prototype.hasOwnProperty.call(value, index)) {
+                    throw new Error(`${location}[${index}] must not be undefined or sparse.`);
+                }
+                assertStructuredGivenValue(value[index], `${location}[${index}]`, ancestors);
+            }
+            return;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new Error(`${location} must contain only plain records and arrays.`);
+        }
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== 'string')
+                throw new Error(`${location} must not contain symbol keys.`);
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || descriptor.get || descriptor.set) {
+                throw new Error(`${location}.${key} must be a plain data property.`);
+            }
+            assertStructuredGivenValue(descriptor.value, `${location}.${key}`, ancestors);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+    }
+    return value;
+}
+function validatedGiven(given) {
+    if (given === undefined)
+        return [];
+    if (Array.isArray(given)) {
+        for (const [index, value] of given.entries()) {
+            if (typeof value !== 'string')
+                throw new Error(`Story given[${index}] must be a string.`);
+        }
+        return given;
+    }
+    assertStructuredGivenValue(given, 'Story given', new Set());
+    return deepFreeze(structuredClone(given));
+}
+function defineAgent(agent) {
+    requiredText(agent.id, 'Agent id');
+    requiredText(agent.name, 'Agent name');
+    return agent;
+}
+function defineStory(input) {
+    requiredText(input.id, 'Story id');
+    requiredText(input.name, 'Story name');
+    const prompt = (input.prompt ?? input.when);
+    const expectations = (input.expectations ?? input.then);
+    requiredText(prompt, 'Story prompt');
+    assertVerdictFreeExpectations(expectations);
+    return {
+        __ethogramType: 'story',
+        id: input.id,
+        name: input.name,
+        agent: input.agent,
+        description: input.description,
+        given: validatedGiven(input.given),
+        prompt,
+        expectations,
+        ...(input.execution === undefined ? {} : { execution: input.execution }),
+    };
+}
+function defineExecutionProfile(profile) {
+    requiredText(profile.id, 'Execution profile id');
+    return { __ethogramType: 'execution-profile', ...profile };
+}

package/dist/index.d.ts

@@ -0,0 +1,134 @@
+type AgentIcon = 'headset' | 'target' | 'search';
+export type Agent = {
+    id: string;
+    name: string;
+    description: string;
+    icon: AgentIcon;
+};
+export type ToolCalledMatcher = {
+    kind: 'tool-called';
+    tool: string;
+};
+export type ToolNotCalledMatcher = {
+    kind: 'tool-not-called';
+    tool: string;
+};
+export type ExpectationMatcher = ToolCalledMatcher | ToolNotCalledMatcher;
+export type StoryExpectation = {
+    id: string;
+    description: string;
+    failureDescription?: string;
+    matcher: ExpectationMatcher;
+    passed?: never;
+    failed?: never;
+    status?: never;
+    verdict?: never;
+};
+type StoryExecutionCapability = {
+    kind: 'external-profile';
+    profile: string;
+};
+export type StoryGivenValue = string | number | boolean | null | readonly StoryGivenValue[] | {
+    readonly [key: string]: StoryGivenValue;
+};
+export type StoryGiven = string[] | Readonly<Record<string, StoryGivenValue>>;
+export type Story = {
+    readonly __ethogramType: 'story';
+    id: string;
+    name: string;
+    agent: Agent;
+    description: string;
+    given: StoryGiven;
+    prompt: string;
+    expectations: StoryExpectation[];
+    execution?: StoryExecutionCapability;
+};
+type PromptInput = {
+    prompt: string;
+    when?: never;
+} | {
+    when: string;
+    prompt?: never;
+};
+type ExpectationsInput = {
+    expectations: StoryExpectation[];
+    then?: never;
+} | {
+    then: StoryExpectation[];
+    expectations?: never;
+};
+export type StoryInput = {
+    id: string;
+    name: string;
+    agent: Agent;
+    description: string;
+    given?: StoryGiven;
+    execution?: StoryExecutionCapability;
+} & PromptInput & ExpectationsInput;
+type ExternalToolInput = Readonly<Record<string, unknown>>;
+type ExternalToolOutput = Readonly<Record<string, unknown>>;
+export type ExternalExecutionEvidenceValue = string | number | boolean | null | readonly ExternalExecutionEvidenceValue[] | {
+    readonly [key: string]: ExternalExecutionEvidenceValue;
+};
+type ExternalToolCallEvidenceBase = {
+    callId: string;
+    name: string;
+    input: ExternalExecutionEvidenceValue;
+    sequence: number;
+    step?: number;
+    startedAt?: string;
+    endedAt?: string;
+    durationMs?: number;
+};
+export type ExternalToolCallEvidence = (ExternalToolCallEvidenceBase & {
+    status: 'success';
+    output?: ExternalExecutionEvidenceValue;
+    error?: never;
+}) | (ExternalToolCallEvidenceBase & {
+    status: 'error';
+    output?: never;
+    error?: {
+        name?: string;
+        message: string;
+    };
+});
+export type ExternalExecutionEvidence = {
+    source: string;
+    toolCalls: readonly ExternalToolCallEvidence[];
+    provider?: string;
+    model?: string;
+    startedAt?: string;
+    endedAt?: string;
+    latencyMs?: number;
+    finishReason?: string;
+    tokenUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        reasoningTokens?: number;
+    };
+};
+export type ExternalToolDefinition = {
+    description: string;
+    execute(input: ExternalToolInput): ExternalToolOutput | Promise<ExternalToolOutput>;
+};
+export type ExternalToolSet = Readonly<Record<string, ExternalToolDefinition>>;
+export type ExternalExecutionOutcome = {
+    decision: string;
+    finalResponse: string;
+    evidence?: ExternalExecutionEvidence;
+};
+export type ExternalExecutionContext = {
+    story: Story;
+    callTool(toolName: string, input: ExternalToolInput): Promise<ExternalToolOutput>;
+};
+export type ExternalExecutionProfile = {
+    readonly __ethogramType: 'execution-profile';
+    id: string;
+    tools: ExternalToolSet;
+    execute(context: ExternalExecutionContext): Promise<ExternalExecutionOutcome>;
+};
+export declare function defineAgent<const TAgent extends Agent>(agent: TAgent): TAgent;
+export declare function defineStory(input: StoryInput): Story;
+export declare function defineExecutionProfile(profile: Omit<ExternalExecutionProfile, '__ethogramType'>): ExternalExecutionProfile;
+export {};

package/dist/index.js

@@ -0,0 +1,105 @@
+const forbiddenExpectationVerdictKeys = ['passed', 'failed', 'status', 'verdict'];
+function requiredText(value, field) {
+    if (!value.trim())
+        throw new Error(`${field} is required.`);
+}
+function assertVerdictFreeExpectations(expectations) {
+    for (const expectation of expectations) {
+        for (const key of forbiddenExpectationVerdictKeys) {
+            if (Object.prototype.hasOwnProperty.call(expectation, key)) {
+                throw new Error(`Story expectation "${expectation.id}" must not contain behavioral verdict field "${key}".`);
+            }
+        }
+    }
+}
+function assertStructuredGivenValue(value, location, ancestors) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error(`${location} must contain only finite numbers.`);
+        return;
+    }
+    if (typeof value !== 'object') {
+        throw new Error(`${location} contains unsupported value type "${typeof value}".`);
+    }
+    if (ancestors.has(value))
+        throw new Error(`${location} must not contain cyclic values.`);
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index += 1) {
+                if (!Object.prototype.hasOwnProperty.call(value, index)) {
+                    throw new Error(`${location}[${index}] must not be undefined or sparse.`);
+                }
+                assertStructuredGivenValue(value[index], `${location}[${index}]`, ancestors);
+            }
+            return;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new Error(`${location} must contain only plain records and arrays.`);
+        }
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== 'string')
+                throw new Error(`${location} must not contain symbol keys.`);
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || descriptor.get || descriptor.set) {
+                throw new Error(`${location}.${key} must be a plain data property.`);
+            }
+            assertStructuredGivenValue(descriptor.value, `${location}.${key}`, ancestors);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+    }
+    return value;
+}
+function validatedGiven(given) {
+    if (given === undefined)
+        return [];
+    if (Array.isArray(given)) {
+        for (const [index, value] of given.entries()) {
+            if (typeof value !== 'string')
+                throw new Error(`Story given[${index}] must be a string.`);
+        }
+        return given;
+    }
+    assertStructuredGivenValue(given, 'Story given', new Set());
+    return deepFreeze(structuredClone(given));
+}
+export function defineAgent(agent) {
+    requiredText(agent.id, 'Agent id');
+    requiredText(agent.name, 'Agent name');
+    return agent;
+}
+export function defineStory(input) {
+    requiredText(input.id, 'Story id');
+    requiredText(input.name, 'Story name');
+    const prompt = (input.prompt ?? input.when);
+    const expectations = (input.expectations ?? input.then);
+    requiredText(prompt, 'Story prompt');
+    assertVerdictFreeExpectations(expectations);
+    return {
+        __ethogramType: 'story',
+        id: input.id,
+        name: input.name,
+        agent: input.agent,
+        description: input.description,
+        given: validatedGiven(input.given),
+        prompt,
+        expectations,
+        ...(input.execution === undefined ? {} : { execution: input.execution }),
+    };
+}
+export function defineExecutionProfile(profile) {
+    requiredText(profile.id, 'Execution profile id');
+    return { __ethogramType: 'execution-profile', ...profile };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ethogram/core",
+  "version": "0.1.0-alpha.0",
+  "description": "Code-first Agent and Story authoring contracts for Ethogram.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leonardocamacho1983/ethogram.git",
+    "directory": "packages/agentbook"
+  },
+  "homepage": "https://github.com/leonardocamacho1983/ethogram#readme",
+  "bugs": {
+    "url": "https://github.com/leonardocamacho1983/ethogram/issues"
+  },
+  "keywords": ["ai-agents", "behavioral-testing", "typescript", "developer-tools"],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.9"
+  }
+}