@elsikora/ai-core

Unified AI runtime for ElsiKora packages and CLIs.

What this package provides

• Single adapter for generation across providers.
• profile mode for module-based runtime configuration.
• Interactive configuration wizard for first-time setup.
• Typed profile readiness contract (inspectProfile, ensureProfile).
• Fail-fast typed errors for missing or invalid profile state.

Install

npm install @elsikora/ai-core

Configuration

Create .elsikora/ai-core.config.js in your project:

export default {
    modules: {
        "your-module-id": {
            model: "gpt-4o",
            provider: "openai",
            reasoning: {
                effort: "medium",
            },
            responseFormat: {
                isStrict: true,
                name: "commit_message",
                schema: {
                    type: "object",
                    properties: {
                        message: { type: "string" },
                    },
                    required: ["message"],
                },
                type: "json_schema",
            },
            retries: 3,
            shouldRepromptCredentialOnAuthenticationFailure: true,
            shouldUseParallelToolCalls: true,
            validationRetries: 3,
        },
    },
};

Credentials are resolved from environment variables by provider (for example OPENAI_API_KEY).

Runtime generation options

Profiles and direct generation requests accept provider-neutral controls such as maxTokens, temperature, topP, topK, seed, stopSequences, timeoutMs, reasoning, responseFormat, tools, toolChoice, shouldUseParallelToolCalls, and shouldRepromptCredentialOnAuthenticationFailure.

Set shouldRepromptCredentialOnAuthenticationFailure: true when an interactive CLI should ask for a replacement credential if the current runtime credential, including one resolved from the environment, is rejected by the provider.

Provider-specific options live under providerOptions and are mapped only inside infrastructure adapters. Examples include OpenAI apiMode, serviceTier, textVerbosity, and shouldStore; Anthropic speed, serviceTier, and thinking; Google thinkingConfig; AWS Bedrock guardrail and performance options; Cerebras reasoning/logprob options; Ollama reasoning controls; and Vercel AI Gateway provider options.

Public adapter API

import { AiCoreAdapter, EGenerateMode } from "@elsikora/ai-core";

const adapter = AiCoreAdapter.create();

const inspection = await adapter.inspectProfile("your-module-id");
const profile = await adapter.ensureProfile("your-module-id");

const result = await adapter.generate({
    mode: EGenerateMode.PROFILE,
    moduleId: "your-module-id",
    prompt: "Generate a concise commit message",
});

Profile readiness behavior

• inspectProfile(moduleId) never prompts and returns a typed status:
  • ready
  • missing_profile
  • missing_credential
  • invalid_profile
• ensureProfile(moduleId) applies canonical orchestration:
  • missing profile + TTY -> run full interactive configure
  • missing credential + TTY -> prompt credential only
  • non-TTY missing state -> throw typed ProfileResolutionError

Typed profile errors

ProfileResolutionError exposes:

• code: missing_profile | missing_credential | invalid_profile
• moduleId
• provider (when known)
• environmentVariableName (when known)

Validation scripts

• npm run validate:fast
• npm run validate:pr
• npm run validate:heavy