import { MessageContent, CacheControl, LLMPort, LLMPriority } from '@llm-ports/core';
import { z } from 'zod';

/**
 * Shared utilities used by every capability factory.
 *
 * These helpers handle:
 *   - dynamic prompt fragment resolution (string-or-function fields)
 *   - safe hook invocation (errors in user hooks must not crash the call)
 *   - common system prompt assembly
 */

/**
 * A prompt fragment may be a literal string OR a function that returns one.
 * Functions can be sync or async; capabilities resolve them lazily so users
 * can plug in DB lookups, feature flags, or context-derived content.
 */
type Resolvable<TInput, TOutput> = TOutput | ((input: TInput) => TOutput | Promise<TOutput>);
interface CapabilityEvent<TOutput> {
    /** Human-readable capability name, e.g. "classify". */
    capability: string;
    /** Schema/operation name as configured by the user. */
    schemaName: string;
    /** Model id reported by the adapter. */
    modelId: string;
    /** Provider alias used. */
    providerAlias: string;
    /** Token usage and USD cost. */
    usage: {
        inputTokens: number;
        outputTokens: number;
        totalTokens: number;
    };
    /**
     * USD cost. `cacheSavingsUSD` is populated when the provider returned cache
     * telemetry on this call (so the consumer can attribute savings per-capability).
     * (alpha.19.1+)
     */
    cost: {
        inputUSD: number;
        outputUSD: number;
        totalUSD: number;
        cacheSavingsUSD?: number;
    };
    latencyMs: number;
    /** The validated output the capability returned. */
    output: TOutput;
    /** Number of attempts (>1 if retry-with-feedback fired). */
    validationAttempts?: number;
}

/**
 * createClassifier — pick one of N categories from input content.
 *
 * Returns a typed function that, given input content, returns a parsed
 * Zod-validated object (typically including the chosen category plus a
 * reasoning field). Configure once at app startup; call many times.
 */

interface ClassifyInput {
    content: MessageContent;
    /** Per-call context override; appended to systemContext. */
    contextOverride?: string;
    /** Cancellation signal for this specific call. Threaded to the port. (alpha.13+) */
    signal?: AbortSignal;
    /** Override task routing for this call only. (alpha.13+) */
    forceProviderAlias?: string;
    /** Per-call escape hatch for provider-specific request fields (vLLM chat_template_kwargs, SGLang regex, etc.). Threaded to the underlying port call. (alpha.16+) */
    providerExtras?: Record<string, unknown>;
    /** Per-call prompt cache configuration. Forwarded to the underlying port call. (alpha.19.1+) */
    cacheControl?: CacheControl;
    /**
     * Per-call override for strict-schema response_format mode. (alpha.21+)
     * Forwarded to the underlying port call. See `GenerateStructuredOptions.strict`.
     */
    strict?: boolean;
}
interface CreateClassifierConfig<TSchema extends z.ZodTypeAny> {
    /** The LLM port. Typically `registry.getPort()`. */
    port: LLMPort;
    /** The Zod schema the model's output must conform to. */
    schema: TSchema;
    /** Operation name used in logs and the model prompt. */
    schemaName: string;
    /** Optional rules text that defines the categories. */
    rubric?: Resolvable<ClassifyInput, string>;
    /** Optional boundary examples ("X is intent A; Y is intent B"). */
    boundaryExamples?: Resolvable<ClassifyInput, string>;
    /** Optional extra context (per-input) the model should consider. */
    systemContext?: Resolvable<ClassifyInput, string>;
    /** Task type for routing. Default: "classify". */
    taskType?: string;
    priority?: LLMPriority;
    /** Default 0 (deterministic). */
    temperature?: number;
    maxOutputTokens?: number;
    /**
     * Reasoning effort hint for o-series / gpt-5-nano / Groq gpt-oss-120b.
     * Applies to every call from this classifier. (alpha.13+)
     */
    reasoningEffort?: "low" | "medium" | "high";
    /** Hooks. Errors in hooks are caught and logged, never re-thrown. */
    onBeforeCall?: (input: ClassifyInput) => void | Promise<void>;
    onResult?: (event: CapabilityEvent<z.infer<TSchema>>) => void | Promise<void>;
    onError?: (error: Error, input: ClassifyInput) => void | Promise<void>;
}
/**
 * Create a configured classifier function.
 *
 * @example
 * const classify = createClassifier({
 *   port: llm,
 *   schema: z.object({
 *     intent: z.enum(["question", "request", "complaint"]),
 *     reasoning: z.string(),
 *   }),
 *   schemaName: "user-intent",
 *   rubric: "question: asking for info\nrequest: wants action\ncomplaint: reports problem",
 * });
 *
 * const result = await classify({ content: "Can I get a refund?" });
 * // { intent: "request", reasoning: "..." }
 */
declare function createClassifier<TSchema extends z.ZodTypeAny>(config: CreateClassifierConfig<TSchema>): (input: ClassifyInput) => Promise<z.infer<TSchema>>;

/**
 * createScorer — rate input against a rubric. Schema typically includes a
 * numerical score plus reasoning.
 */

interface ScoreInput {
    content: MessageContent;
    contextOverride?: string;
    /** Cancellation signal for this specific call. Threaded to the port. (alpha.13+) */
    signal?: AbortSignal;
    /** Override task routing for this call only. (alpha.13+) */
    forceProviderAlias?: string;
    /** Per-call escape hatch for provider-specific request fields (vLLM chat_template_kwargs, SGLang regex, etc.). Threaded to the underlying port call. (alpha.16+) */
    providerExtras?: Record<string, unknown>;
    /** Per-call prompt cache configuration. Forwarded to the underlying port call. (alpha.19.1+) */
    cacheControl?: CacheControl;
    /**
     * Per-call override for strict-schema response_format mode. (alpha.21+)
     * Forwarded to the underlying port call. See `GenerateStructuredOptions.strict`.
     */
    strict?: boolean;
}
interface CreateScorerConfig<TSchema extends z.ZodTypeAny> {
    port: LLMPort;
    schema: TSchema;
    schemaName: string;
    /** Required: the scoring rubric (what determines a high vs low score). */
    rubric: Resolvable<ScoreInput, string>;
    /** Optional examples of low/medium/high scored items. */
    examples?: Resolvable<ScoreInput, string>;
    systemContext?: Resolvable<ScoreInput, string>;
    taskType?: string;
    priority?: LLMPriority;
    /** Default 0.1 — slight randomness helps surface borderline cases consistently. */
    temperature?: number;
    maxOutputTokens?: number;
    /**
     * Reasoning effort hint for o-series / gpt-5-nano / Groq gpt-oss-120b.
     * Applies to every call from this scorer. (alpha.13+)
     */
    reasoningEffort?: "low" | "medium" | "high";
    onBeforeCall?: (input: ScoreInput) => void | Promise<void>;
    onResult?: (event: CapabilityEvent<z.infer<TSchema>>) => void | Promise<void>;
    onError?: (error: Error, input: ScoreInput) => void | Promise<void>;
}
declare function createScorer<TSchema extends z.ZodTypeAny>(config: CreateScorerConfig<TSchema>): (input: ScoreInput) => Promise<z.infer<TSchema>>;

/**
 * createExtractor — pull structured fields from unstructured input.
 *
 * Returns Zod-validated typed data. Useful for: parsing emails for action
 * items, extracting contact info from text, structured data from documents.
 */

interface ExtractInput {
    content: MessageContent;
    contextOverride?: string;
    /** Cancellation signal for this specific call. Threaded to the port. (alpha.13+) */
    signal?: AbortSignal;
    /** Override task routing for this call only. (alpha.13+) */
    forceProviderAlias?: string;
    /** Per-call escape hatch for provider-specific request fields (vLLM chat_template_kwargs, SGLang regex, etc.). Threaded to the underlying port call. (alpha.16+) */
    providerExtras?: Record<string, unknown>;
    /** Per-call prompt cache configuration. Forwarded to the underlying port call. (alpha.19.1+) */
    cacheControl?: CacheControl;
    /**
     * Per-call override for strict-schema response_format mode. (alpha.21+)
     * Forwarded to the underlying port call. See `GenerateStructuredOptions.strict`.
     */
    strict?: boolean;
}
interface CreateExtractorConfig<TSchema extends z.ZodTypeAny> {
    port: LLMPort;
    schema: TSchema;
    schemaName: string;
    /** What to extract (instructions describing each field). */
    fieldGuide?: Resolvable<ExtractInput, string>;
    /** Examples of input -> extracted output. */
    examples?: Resolvable<ExtractInput, string>;
    systemContext?: Resolvable<ExtractInput, string>;
    taskType?: string;
    priority?: LLMPriority;
    /** Default 0 (deterministic). */
    temperature?: number;
    maxOutputTokens?: number;
    /**
     * Reasoning effort hint for o-series / gpt-5-nano / Groq gpt-oss-120b.
     * Applies to every call from this extractor. (alpha.13+)
     */
    reasoningEffort?: "low" | "medium" | "high";
    onBeforeCall?: (input: ExtractInput) => void | Promise<void>;
    onResult?: (event: CapabilityEvent<z.infer<TSchema>>) => void | Promise<void>;
    onError?: (error: Error, input: ExtractInput) => void | Promise<void>;
}
declare function createExtractor<TSchema extends z.ZodTypeAny>(config: CreateExtractorConfig<TSchema>): (input: ExtractInput) => Promise<z.infer<TSchema>>;

/**
 * createSummarizer — compress input text while preserving the key meaning.
 *
 * Returns plain text. For structured summaries (e.g. bullet points + an
 * explicit list of action items), use createExtractor with a schema instead.
 */

interface SummarizeInput {
    content: MessageContent;
    contextOverride?: string;
    /** Cancellation signal for this specific call. Threaded to the port. (alpha.13+) */
    signal?: AbortSignal;
    /** Override task routing for this call only. (alpha.13+) */
    forceProviderAlias?: string;
    /** Per-call escape hatch for provider-specific request fields (vLLM chat_template_kwargs, SGLang regex, etc.). Threaded to the underlying port call. (alpha.16+) */
    providerExtras?: Record<string, unknown>;
    /** Per-call prompt cache configuration. Forwarded to the underlying port call. (alpha.19.1+) */
    cacheControl?: CacheControl;
}
interface CreateSummarizerConfig {
    port: LLMPort;
    /** Operation name used in logs. Default: "summarize". */
    schemaName?: string;
    /** Optional persona / focus instructions. */
    persona?: Resolvable<SummarizeInput, string>;
    /** Optional output style guide (e.g. "3-5 bullets, active voice"). */
    styleGuide?: Resolvable<SummarizeInput, string>;
    systemContext?: Resolvable<SummarizeInput, string>;
    /** Approximate target length in words. */
    targetWords?: number;
    taskType?: string;
    priority?: LLMPriority;
    /** Default 0.2. */
    temperature?: number;
    maxOutputTokens?: number;
    /**
     * Reasoning effort hint for o-series / gpt-5-nano / Groq gpt-oss-120b.
     * Applies to every call from this summarizer. (alpha.13+)
     */
    reasoningEffort?: "low" | "medium" | "high";
    onBeforeCall?: (input: SummarizeInput) => void | Promise<void>;
    onResult?: (event: CapabilityEvent<string>) => void | Promise<void>;
    onError?: (error: Error, input: SummarizeInput) => void | Promise<void>;
}
declare function createSummarizer(config: CreateSummarizerConfig): (input: SummarizeInput) => Promise<string>;

/**
 * createDrafter — generate new text in a specific persona/style.
 *
 * Returns plain text. The persona is the most important configuration: it
 * tells the model who is "writing." Channel constraints (e.g. SMS = 160
 * chars, email = 150-250 words) help the model size its output.
 */

interface DraftInput {
    /** Instruction for what to write (the user-facing intent). */
    instructions: string;
    /** Optional thread/conversation history the draft is responding to. */
    threadHistory?: MessageContent;
    /** Optional recipient context (e.g. CRM data, prior interactions). */
    recipientContext?: string;
    contextOverride?: string;
    /** Cancellation signal for this specific call. Threaded to the port. (alpha.13+) */
    signal?: AbortSignal;
    /** Override task routing for this call only. (alpha.13+) */
    forceProviderAlias?: string;
    /** Per-call escape hatch for provider-specific request fields (vLLM chat_template_kwargs, SGLang regex, etc.). Threaded to the underlying port call. (alpha.16+) */
    providerExtras?: Record<string, unknown>;
    /** Per-call prompt cache configuration. Forwarded to the underlying port call. (alpha.19.1+) */
    cacheControl?: CacheControl;
}
interface CreateDrafterConfig {
    port: LLMPort;
    /** Operation name used in logs. Default: "draft". */
    schemaName?: string;
    /** REQUIRED. The persona/voice the draft should adopt. Often a tone profile. */
    persona: Resolvable<DraftInput, string>;
    /** Optional channel constraint (e.g. SMS, email, LinkedIn DM). */
    channelConstraint?: Resolvable<DraftInput, string>;
    /** Optional anti-pattern blacklist (phrases to avoid). */
    antiPatterns?: Resolvable<DraftInput, string>;
    /** Optional examples of correctly-styled drafts. */
    writingSamples?: Resolvable<DraftInput, string>;
    systemContext?: Resolvable<DraftInput, string>;
    taskType?: string;
    priority?: LLMPriority;
    /** Default 0.4 (creative but controlled). */
    temperature?: number;
    /** Hard character cap; truncates output if exceeded. */
    maxLength?: number;
    maxOutputTokens?: number;
    /**
     * Reasoning effort hint for o-series / gpt-5-nano / Groq gpt-oss-120b.
     * Applies to every call from this drafter. (alpha.13+)
     */
    reasoningEffort?: "low" | "medium" | "high";
    onBeforeCall?: (input: DraftInput) => void | Promise<void>;
    onResult?: (event: CapabilityEvent<string>) => void | Promise<void>;
    onError?: (error: Error, input: DraftInput) => void | Promise<void>;
}
declare function createDrafter(config: CreateDrafterConfig): (input: DraftInput) => Promise<string>;

/**
 * createPlanner — decompose a goal into ordered or DAG-shaped steps.
 *
 * Returns Zod-validated structured output. The user supplies the schema
 * for what a "step" looks like (typically id + description + dependencies).
 */

interface PlanInput {
    goal: MessageContent;
    contextOverride?: string;
    /** Cancellation signal for this specific call. Threaded to the port. (alpha.13+) */
    signal?: AbortSignal;
    /** Override task routing for this call only. (alpha.13+) */
    forceProviderAlias?: string;
    /** Per-call escape hatch for provider-specific request fields (vLLM chat_template_kwargs, SGLang regex, etc.). Threaded to the underlying port call. (alpha.16+) */
    providerExtras?: Record<string, unknown>;
    /** Per-call prompt cache configuration. Forwarded to the underlying port call. (alpha.19.1+) */
    cacheControl?: CacheControl;
    /**
     * Per-call override for strict-schema response_format mode. (alpha.21+)
     * Forwarded to the underlying port call. See `GenerateStructuredOptions.strict`.
     */
    strict?: boolean;
}
interface CreatePlannerConfig<TSchema extends z.ZodTypeAny> {
    port: LLMPort;
    schema: TSchema;
    schemaName: string;
    /** Optional planning approach (e.g. "depth-first; minimize dependencies"). */
    strategy?: Resolvable<PlanInput, string>;
    /** Available tools / capabilities the plan may reference. */
    toolCatalog?: Resolvable<PlanInput, string>;
    /** Examples of well-formed plans for similar goals. */
    examples?: Resolvable<PlanInput, string>;
    systemContext?: Resolvable<PlanInput, string>;
    taskType?: string;
    priority?: LLMPriority;
    /** Default 0.2. */
    temperature?: number;
    maxOutputTokens?: number;
    /**
     * Reasoning effort hint for o-series / gpt-5-nano / Groq gpt-oss-120b.
     * Applies to every call from this planner. (alpha.13+)
     */
    reasoningEffort?: "low" | "medium" | "high";
    onBeforeCall?: (input: PlanInput) => void | Promise<void>;
    onResult?: (event: CapabilityEvent<z.infer<TSchema>>) => void | Promise<void>;
    onError?: (error: Error, input: PlanInput) => void | Promise<void>;
}
declare function createPlanner<TSchema extends z.ZodTypeAny>(config: CreatePlannerConfig<TSchema>): (input: PlanInput) => Promise<z.infer<TSchema>>;

/**
 * createAnalyzer — evaluate, critique, or compare. Returns Zod-validated
 * structured output. Use when the user wants a "what do you think about
 * this?" answer with explicit reasoning and recommendations.
 */

interface AnalyzeInput {
    content: MessageContent;
    /** Optional explicit question; if omitted, the analyzer's framework drives the analysis. */
    question?: string;
    contextOverride?: string;
    /** Cancellation signal for this specific call. Threaded to the port. (alpha.13+) */
    signal?: AbortSignal;
    /** Override task routing for this call only. (alpha.13+) */
    forceProviderAlias?: string;
    /** Per-call escape hatch for provider-specific request fields (vLLM chat_template_kwargs, SGLang regex, etc.). Threaded to the underlying port call. (alpha.16+) */
    providerExtras?: Record<string, unknown>;
    /** Per-call prompt cache configuration. Forwarded to the underlying port call. (alpha.19.1+) */
    cacheControl?: CacheControl;
    /**
     * Per-call override for strict-schema response_format mode. (alpha.21+)
     * Forwarded to the underlying port call. See `GenerateStructuredOptions.strict`.
     */
    strict?: boolean;
}
interface CreateAnalyzerConfig<TSchema extends z.ZodTypeAny> {
    port: LLMPort;
    schema: TSchema;
    schemaName: string;
    /** REQUIRED. The analytical framework (e.g. SWOT, pros/cons, root-cause). */
    framework: Resolvable<AnalyzeInput, string>;
    /** Optional examples of well-structured analyses. */
    examples?: Resolvable<AnalyzeInput, string>;
    systemContext?: Resolvable<AnalyzeInput, string>;
    taskType?: string;
    priority?: LLMPriority;
    /** Default 0.3 — analysis benefits from some perspective variety. */
    temperature?: number;
    maxOutputTokens?: number;
    /**
     * Reasoning effort hint for o-series / gpt-5-nano / Groq gpt-oss-120b.
     * Applies to every call from this analyzer. (alpha.13+)
     */
    reasoningEffort?: "low" | "medium" | "high";
    onBeforeCall?: (input: AnalyzeInput) => void | Promise<void>;
    onResult?: (event: CapabilityEvent<z.infer<TSchema>>) => void | Promise<void>;
    onError?: (error: Error, input: AnalyzeInput) => void | Promise<void>;
}
declare function createAnalyzer<TSchema extends z.ZodTypeAny>(config: CreateAnalyzerConfig<TSchema>): (input: AnalyzeInput) => Promise<z.infer<TSchema>>;

export { type AnalyzeInput, type CapabilityEvent, type ClassifyInput, type CreateAnalyzerConfig, type CreateClassifierConfig, type CreateDrafterConfig, type CreateExtractorConfig, type CreatePlannerConfig, type CreateScorerConfig, type CreateSummarizerConfig, type DraftInput, type ExtractInput, type PlanInput, type Resolvable, type ScoreInput, type SummarizeInput, createAnalyzer, createClassifier, createDrafter, createExtractor, createPlanner, createScorer, createSummarizer };