@reallyartificial/grain 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,388 @@
+/**
+ * AgentSpec TypeScript type definitions.
+ * Aligned with spec/agentspec.schema.json (source of truth).
+ */
+export interface AgentSpec {
+    $schema?: string;
+    specVersion: "1.0";
+    id: string;
+    version: string;
+    extends?: string | {
+        id: string;
+        version: string;
+    };
+    meta: AgentMeta;
+    identity: AgentIdentity;
+    voice: AgentVoice;
+    cognition: AgentCognition;
+    capabilities: AgentCapabilities;
+    behavior: AgentBehavior;
+    memory: AgentMemory;
+    communication: AgentCommunication;
+    adaptation: AgentAdaptation;
+    observability: AgentObservability;
+}
+export interface AgentMeta {
+    name: string;
+    description: string;
+    author?: string;
+    license?: string;
+    tags?: string[];
+    url?: string;
+    model?: ModelPreference;
+}
+export interface ModelPreference {
+    minimumTier: "small" | "medium" | "large" | "frontier";
+    preferredProvider?: string;
+    preferredModel?: string;
+    minimumContext?: number;
+    requiresToolCalling?: boolean;
+    requiresMultimodal?: boolean;
+}
+export interface AgentIdentity {
+    name: string;
+    role: string;
+    purpose: {
+        primary: string;
+        secondary?: string[];
+    };
+    expertise: DomainExpertise[];
+    relationships?: AgentRelationship[];
+}
+export interface DomainExpertise {
+    domain: string;
+    proficiency: number;
+    subtopics?: string[];
+}
+export interface AgentRelationship {
+    target: string;
+    type: "reports-to" | "delegates-to" | "collaborates-with" | "supervises" | "escalates-to";
+    permissions?: ("read" | "write" | "execute" | "delegate")[];
+}
+export interface AgentVoice {
+    personality: PersonalityVector;
+    language: LanguageStyle;
+    channelOverrides?: Record<string, Partial<PersonalityVector & LanguageStyle>>;
+}
+export interface PersonalityVector {
+    formality: number;
+    warmth: number;
+    humor: number;
+    assertiveness: number;
+    verbosity: number;
+    confidence: number;
+    concreteness: number;
+    urgency: number;
+}
+export interface LanguageStyle {
+    locale: string;
+    sentenceLength: "short" | "medium" | "long";
+    jargonLevel: "none" | "moderate" | "heavy";
+    emojiUsage: "never" | "sparingly" | "frequently";
+    structure: "prose" | "bullets" | "mixed";
+    usesAnalogies: boolean;
+    addressing: "first-person" | "third-person" | "neutral";
+}
+/**
+ * Big Five (OCEAN) personality mapping.
+ * Optional — provides scientific grounding for the 8-dimension model.
+ * See SPECIFICATION.md for mapping details.
+ */
+export interface BigFiveMapping {
+    openness: number;
+    conscientiousness: number;
+    extraversion: number;
+    agreeableness: number;
+    neuroticism: number;
+}
+/**
+ * Derives approximate Big Five scores from a PersonalityVector.
+ */
+export declare function toBigFive(p: PersonalityVector): BigFiveMapping;
+export interface AgentCognition {
+    reasoningStyle: ReasoningStyle;
+    decisionMaking: DecisionMaking;
+    uncertainty: UncertaintyHandling;
+    taskStrategy: TaskStrategy;
+}
+export interface ReasoningStyle {
+    primary: "analytical" | "creative" | "systematic" | "intuitive" | "socratic";
+    showReasoning: boolean;
+    analysisDepth: "surface" | "moderate" | "deep" | "exhaustive";
+    multiPerspective: boolean;
+}
+export interface DecisionMaking {
+    speed: number;
+    evidenceThreshold: number;
+    reversibilityPreference: "prefer-reversible" | "neutral" | "bias-to-action";
+    autonomy: "always-ask" | "ask-for-major" | "decide-unless-ambiguous" | "fully-autonomous";
+}
+export interface UncertaintyHandling {
+    lowConfidenceAction: "ask" | "hedge" | "state-assumption" | "refuse";
+    confidenceFloor: number;
+    communicateUncertainty: boolean;
+    conflictResolution: "ask-user" | "use-most-recent" | "use-most-authoritative" | "present-both";
+}
+export interface TaskStrategy {
+    decomposition: "top-down" | "bottom-up" | "iterative";
+    maxParallelism: number;
+    checkpointing: boolean;
+    blockingStrategy: "wait" | "skip-and-return" | "find-alternative" | "escalate";
+}
+export interface AgentCapabilities {
+    tools?: ToolCapability[];
+    skills?: SkillDefinition[];
+    knowledge?: KnowledgeSource[];
+    outputFormats?: OutputFormat[];
+}
+export interface ToolCapability {
+    id: string;
+    usage: string;
+    requiresConfirmation?: boolean;
+    rateLimit?: {
+        max: number;
+        per: "message" | "conversation" | "hour";
+    };
+}
+export interface SkillDefinition {
+    name: string;
+    description: string;
+    requiredTools?: string[];
+    steps?: string[];
+    successCriteria?: string[];
+}
+export interface KnowledgeSource {
+    id: string;
+    type: "embedded" | "retrieval" | "api" | "file-system" | "database";
+    domain: string;
+    freshness?: "static" | "daily" | "real-time";
+    priority?: number;
+}
+export interface OutputFormat {
+    format: string;
+    condition?: string;
+}
+export interface AgentBehavior {
+    rules: BehaviorRule[];
+    boundaries: Boundary[];
+    triggers?: BehaviorTrigger[];
+    escalation?: EscalationPolicy;
+}
+export interface BehaviorRule {
+    id: string;
+    condition: RuleCondition;
+    action: RuleAction;
+    priority?: number;
+    overridable?: boolean;
+}
+export type RuleCondition = {
+    type: "always";
+} | {
+    type: "when-topic";
+    topics: string[];
+} | {
+    type: "when-sentiment";
+    sentiment: "positive" | "negative" | "neutral" | "frustrated";
+} | {
+    type: "when-context";
+    context: string;
+} | {
+    type: "when-user-role";
+    roles: string[];
+} | {
+    type: "when-capability-missing";
+    capability: string;
+} | {
+    type: "when-confidence-below";
+    threshold: number;
+} | {
+    type: "compound";
+    operator: "and" | "or";
+    conditions: RuleCondition[];
+};
+export type RuleAction = {
+    type: "respond-with-style";
+    style: Partial<PersonalityVector>;
+} | {
+    type: "use-tool";
+    tool: string;
+    params?: Record<string, unknown>;
+} | {
+    type: "escalate";
+    target: string;
+    reason: string;
+} | {
+    type: "refuse";
+    message: string;
+} | {
+    type: "redirect";
+    target: string;
+} | {
+    type: "adjust-depth";
+    depth: "surface" | "moderate" | "deep";
+} | {
+    type: "require-confirmation";
+} | {
+    type: "log-event";
+    event: string;
+    level: "info" | "warn" | "error";
+} | {
+    type: "custom";
+    handler: string;
+    params?: Record<string, unknown>;
+};
+export interface Boundary {
+    description: string;
+    category: "content" | "action" | "data" | "scope" | "safety";
+    enforcement: "hard" | "soft";
+    onViolation: "refuse" | "warn" | "redirect" | "escalate";
+    message?: string;
+}
+export interface BehaviorTrigger {
+    event: TriggerEvent;
+    action: RuleAction;
+    cooldown?: number;
+}
+export type TriggerEvent = {
+    type: "keyword";
+    keywords: string[];
+} | {
+    type: "intent";
+    intents: string[];
+} | {
+    type: "silence";
+    durationSeconds: number;
+} | {
+    type: "error";
+    errorType?: string;
+} | {
+    type: "threshold";
+    metric: string;
+    operator: "gt" | "lt" | "eq";
+    value: number;
+} | {
+    type: "schedule";
+    cron: string;
+};
+export interface EscalationPolicy {
+    conditions: EscalationCondition[];
+    defaultTarget: string;
+    handoffStrategy: "full-transcript" | "summary" | "structured-handoff";
+    maxRetries?: number;
+}
+export interface EscalationCondition {
+    trigger: "confidence-low" | "user-frustrated" | "out-of-scope" | "safety-concern" | "repeated-failure" | "explicit-request";
+    threshold?: number;
+    target?: string;
+}
+export interface AgentMemory {
+    retention: RetentionPolicy[];
+    contextStrategy: ContextStrategy;
+    persistentState?: StateSchema[];
+}
+export interface RetentionPolicy {
+    category: "user-preferences" | "conversation-history" | "task-state" | "learned-patterns" | "corrections" | "facts";
+    duration: "conversation" | "session" | "days" | "permanent";
+    days?: number;
+    maxItems?: number;
+    priority?: number;
+}
+export interface ContextStrategy {
+    overflow: "summarize" | "sliding-window" | "smart-select" | "truncate";
+    prioritize: ("recent" | "user-stated" | "task-relevant" | "corrections")[];
+    autoSummarize: boolean;
+}
+export interface StateSchema {
+    key: string;
+    type: "string" | "number" | "boolean" | "array" | "object";
+    description: string;
+    defaultValue?: unknown;
+    agentWritable: boolean;
+}
+export interface AgentCommunication {
+    channels: ChannelConfig[];
+    input: InputProcessing;
+    output: OutputProcessing;
+    interAgent?: InterAgentConfig;
+}
+export interface ChannelConfig {
+    channel: string;
+    enabled: boolean;
+    voiceOverrides?: Partial<PersonalityVector & LanguageStyle>;
+    constraints?: {
+        maxLength?: number;
+        supportsMarkdown?: boolean;
+        supportsImages?: boolean;
+        supportsButtons?: boolean;
+    };
+}
+export interface InputProcessing {
+    languages: string[];
+    typoTolerance: boolean;
+    ambiguityResolution: "ask" | "best-guess" | "ask-if-high-stakes";
+    modalities: ("text" | "image" | "audio" | "file")[];
+}
+export interface OutputProcessing {
+    defaultFormat: "text" | "markdown" | "html" | "json";
+    citations: "always" | "when-available" | "never";
+    maxLength?: {
+        value: number;
+        unit: "tokens" | "characters";
+    };
+    structuredOutput: boolean;
+}
+export interface InterAgentConfig {
+    protocols: ("a2a" | "mcp" | "custom")[];
+    exposedCapabilities: string[];
+    requestableCapabilities: string[];
+    auth?: "none" | "token" | "mutual-tls" | "oauth";
+}
+export interface AgentAdaptation {
+    enabled: boolean;
+    driftBounds?: DriftBound[];
+    learning?: LearningConfig;
+    feedback?: FeedbackConfig;
+}
+export interface DriftBound {
+    parameter: string;
+    maxDrift: number;
+    driftRate: "immediate" | "gradual" | "slow";
+    resetsPerConversation: boolean;
+}
+export interface LearningConfig {
+    sources: ("user-feedback" | "task-outcomes" | "corrections" | "examples")[];
+    minSamples: number;
+    requiresApproval: boolean;
+}
+export interface FeedbackConfig {
+    collection: "explicit-ask" | "implicit-signals" | "both";
+    application: "immediate" | "batched" | "manual-review";
+    conflictResolution: "latest-wins" | "majority-wins" | "ask-user";
+}
+export interface AgentObservability {
+    logging: LoggingConfig;
+    metrics: MetricDefinition[];
+    successCriteria: SuccessCriterion[];
+}
+export interface LoggingConfig {
+    level: "debug" | "info" | "warn" | "error";
+    alwaysLog: ("tool-use" | "escalation" | "boundary-hit" | "error" | "rule-fired")[];
+    conversationLogging: "full" | "summary" | "none";
+    piiHandling: "redact" | "hash" | "allow";
+}
+export interface MetricDefinition {
+    name: string;
+    description: string;
+    type: "counter" | "gauge" | "histogram" | "rate";
+    event: string;
+}
+export interface SuccessCriterion {
+    description: string;
+    metric: string;
+    target: {
+        operator: "gt" | "lt" | "eq" | "gte" | "lte";
+        value: number;
+    };
+    window?: "per-conversation" | "per-day" | "per-week";
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,17 @@
+/**
+ * AgentSpec TypeScript type definitions.
+ * Aligned with spec/agentspec.schema.json (source of truth).
+ */
+/**
+ * Derives approximate Big Five scores from a PersonalityVector.
+ */
+export function toBigFive(p) {
+    return {
+        openness: (p.humor + (1 - p.concreteness)) / 2,
+        conscientiousness: (p.formality + (1 - p.urgency) + p.concreteness) / 3,
+        extraversion: (p.warmth + p.assertiveness + p.verbosity) / 3,
+        agreeableness: (p.warmth + (1 - p.assertiveness)) / 2,
+        neuroticism: ((1 - p.confidence) + p.urgency) / 2,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsHH;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,CAAoB;IAC5C,OAAO;QACL,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC;QAC9C,iBAAiB,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC;QACvE,YAAY,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC;QAC5D,aAAa,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC;QACrD,WAAW,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;KAClD,CAAA;AACH,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,15 @@
+export interface ValidationError {
+    path: string;
+    message: string;
+    severity: "error" | "warning";
+}
+/**
+ * Validate an AgentSpec object against the JSON Schema.
+ * Returns an array of validation errors (empty = valid).
+ */
+export declare function validateSpec(data: unknown): ValidationError[];
+/**
+ * Validate and throw if invalid.
+ */
+export declare function assertValid(data: unknown): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;CAC9B;AAgCD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,EAAE,CAW7D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAM/C"}

package/dist/validate.js

@@ -0,0 +1,59 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Load schema — try package-local first (npm install), then monorepo path (development)
+const schemaPath = (() => {
+    const packageLocal = join(__dirname, "..", "agentspec.schema.json");
+    const monorepo = join(__dirname, "..", "..", "..", "spec", "agentspec.schema.json");
+    try {
+        readFileSync(packageLocal, "utf-8");
+        return packageLocal;
+    }
+    catch {
+        return monorepo;
+    }
+})();
+let _schema = null;
+function getSchema() {
+    if (!_schema) {
+        _schema = JSON.parse(readFileSync(schemaPath, "utf-8"));
+    }
+    return _schema;
+}
+let _validateFn = null;
+function getValidator() {
+    if (!_validateFn) {
+        const ajv = new Ajv2020({ allErrors: true, strict: false });
+        _validateFn = ajv.compile(getSchema());
+    }
+    return _validateFn;
+}
+/**
+ * Validate an AgentSpec object against the JSON Schema.
+ * Returns an array of validation errors (empty = valid).
+ */
+export function validateSpec(data) {
+    const validate = getValidator();
+    const valid = validate(data);
+    if (valid)
+        return [];
+    return (validate.errors ?? []).map(err => ({
+        path: err.instancePath || "/",
+        message: err.message ?? "Unknown validation error",
+        severity: "error",
+    }));
+}
+/**
+ * Validate and throw if invalid.
+ */
+export function assertValid(data) {
+    const errors = validateSpec(data);
+    if (errors.length > 0) {
+        const messages = errors.map(e => `  ${e.path}: ${e.message}`).join("\n");
+        throw new Error(`AgentSpec validation failed:\n${messages}`);
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,kBAAkB,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACjD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;AAQrC,wFAAwF;AACxF,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE;IACvB,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,uBAAuB,CAAC,CAAA;IACnE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,uBAAuB,CAAC,CAAA;IACnF,IAAI,CAAC;QACH,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;QACnC,OAAO,YAAY,CAAA;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAA;IACjB,CAAC;AACH,CAAC,CAAC,EAAE,CAAA;AACJ,IAAI,OAAO,GAAkB,IAAI,CAAA;AAEjC,SAAS,SAAS;IAChB,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAA;IACzD,CAAC;IACD,OAAO,OAAQ,CAAA;AACjB,CAAC;AAED,IAAI,WAAW,GAA0C,IAAI,CAAA;AAE7D,SAAS,YAAY;IACnB,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;QAC3D,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAA;IACxC,CAAC;IACD,OAAO,WAAW,CAAA;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAA;IAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;IAE5B,IAAI,KAAK;QAAE,OAAO,EAAE,CAAA;IAEpB,OAAO,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzC,IAAI,EAAE,GAAG,CAAC,YAAY,IAAI,GAAG;QAC7B,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,0BAA0B;QAClD,QAAQ,EAAE,OAAgB;KAC3B,CAAC,CAAC,CAAA;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;IACjC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACxE,MAAM,IAAI,KAAK,CAAC,iCAAiC,QAAQ,EAAE,CAAC,CAAA;IAC9D,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@reallyartificial/grain",
+  "version": "0.2.0",
+  "description": "Grain — a structured data format for describing AI agents.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "grain": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "agentspec.schema.json"
+  ],
+  "scripts": {
+    "prebuild": "cp ../../spec/agentspec.schema.json ./agentspec.schema.json 2>/dev/null || true",
+    "build": "tsc",
+    "test": "vitest run --dir src",
+    "prepublishOnly": "npm run build && npm test",
+    "validate": "tsx src/load.ts"
+  },
+  "keywords": [
+    "agent",
+    "ai-agent",
+    "llm",
+    "persona",
+    "grain",
+    "structured-data"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/grain",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://github.com/anthropics/grain#readme",
+  "bugs": {
+    "url": "https://github.com/anthropics/grain/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "ajv": "^8.17.0",
+    "ajv-formats": "^3.0.1",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.5"
+  }
+}