/**
 * Partition Planner — Logical Work Partitioning for Network-AI
 *
 * Prevents parallel agents from performing redundant research or analysis by
 * running a "meta-step" before DAG execution that generates a Scope Assignment
 * Map (PartitionSchema). Each agent receives a boundary constraint injected
 * into its parameters, declaring what it SHOULD focus on and what it should
 * EXCLUDE.
 *
 * The planner also performs an overlap check — verifying that no two
 * `focus_area` strings overlap semantically (or lexically, when using the
 * built-in heuristic check).
 *
 * Zero external dependencies — the overlap checker and the planner function
 * are pluggable so callers can use any LLM or rule-based strategy.
 *
 * @module PartitionPlanner
 * @version 1.0.0
 */
import type { TeamAgent } from './goal-decomposer';
/**
 * A single entry in the partition schema — the boundary assignment for one
 * agent type.
 */
export interface PartitionEntry {
    /** The agent type / ID this assignment applies to. */
    agent_type: string;
    /** What this agent should focus on. */
    focus_area: string;
    /** Topics this agent must NOT research or analyse to avoid redundancy. */
    excluded_topics: string[];
}
/**
 * The full scope assignment map — one entry per agent.
 */
export type PartitionSchema = PartitionEntry[];
/**
 * A planner function that, given a goal and a list of agents, produces a
 * PartitionSchema via an LLM call (or rule-based logic).
 */
export type PartitionPlannerFunction = (goal: string, agents: TeamAgent[], context?: Record<string, unknown>) => Promise<PartitionSchema>;
/**
 * An overlap-check function that validates no two focus_area strings in a
 * schema overlap. Returns an array of overlap descriptions (empty = no overlaps).
 */
export type OverlapCheckFunction = (schema: PartitionSchema) => Promise<string[]>;
/** Options for {@link PartitionPlanner}. */
export interface PartitionPlannerOptions {
    /**
     * Overlap check implementation.
     * Defaults to the built-in lexical heuristic checker.
     */
    overlapChecker?: OverlapCheckFunction;
    /**
     * When true, throw an error if any semantic overlaps are detected.
     * When false (default), overlaps are reported in `PartitionResult.overlaps`
     * but execution continues.
     */
    strictOverlap?: boolean;
}
/** Result of a partition planning call. */
export interface PartitionResult {
    /** The generated schema (one entry per agent). */
    schema: PartitionSchema;
    /** Any detected focus_area overlaps between agents. */
    overlaps: string[];
    /** True when overlaps were detected (and strictOverlap was false). */
    hasOverlaps: boolean;
    /** When the schema was generated (epoch ms). */
    createdAt: number;
}
/**
 * Lexical overlap checker: considers two focus areas to overlap when they
 * share significant word stems (ignoring common stop words).
 *
 * This is the built-in default. For true semantic overlap detection, inject
 * an LLM-based `OverlapCheckFunction` via `PartitionPlannerOptions.overlapChecker`.
 */
export declare function createLexicalOverlapChecker(): OverlapCheckFunction;
/**
 * Build a partition planner backed by an LLM.
 *
 * The LLM is asked to generate a PartitionSchema JSON array given the goal
 * and the available agents. Use this for rich semantic partitioning.
 *
 * @param executor - Network-AI executor function
 * @param plannerAgentId - Agent ID for the LLM that does partitioning
 */
export declare function createLLMPartitionPlanner(executor: (agentId: string, payload: {
    action: string;
    params: Record<string, unknown>;
}, context: {
    agentId: string;
    taskId: string;
    metadata?: Record<string, unknown>;
}) => Promise<{
    success: boolean;
    data?: unknown;
    error?: {
        message: string;
    };
}>, plannerAgentId: string): PartitionPlannerFunction;
/**
 * Parse a PartitionSchema from an LLM response string.
 * Handles markdown fences and leading/trailing text.
 */
export declare function parsePartitionJSON(text: string): PartitionSchema;
/**
 * PartitionPlanner generates a PartitionSchema (scope assignment map) for a
 * set of agents before the DAG is executed, preventing redundant research.
 *
 * @example
 * ```typescript
 * const planner = new PartitionPlanner(myLLMPartitionPlannerFn);
 * const result = await planner.plan('Analyse Q3 financial results', agents);
 * // result.schema[0] = { agent_type: 'researcher', focus_area: '...', excluded_topics: [...] }
 * // Inject result.schema[i] as boundary constraint into each agent's params
 * ```
 */
export declare class PartitionPlanner {
    private plannerFn;
    private overlapChecker;
    private strictOverlap;
    constructor(plannerFn: PartitionPlannerFunction, options?: PartitionPlannerOptions);
    /**
     * Generate a PartitionSchema for a goal and agent list.
     *
     * Runs the planner then validates for overlaps. If `strictOverlap` is true
     * and overlaps are found, throws an error. Otherwise overlaps are reported
     * in the result.
     *
     * @param goal - Natural language goal
     * @param agents - Available team agents
     * @param context - Optional context to feed to the planner
     */
    plan(goal: string, agents: TeamAgent[], context?: Record<string, unknown>): Promise<PartitionResult>;
    /**
     * Inject partition boundary constraints into agent params.
     *
     * Given a PartitionSchema and an existing params object for an agent,
     * returns a new params object with `_partitionConstraint` added.
     *
     * @param agentId - Agent ID to look up in the schema
     * @param params - Existing task params
     * @param schema - The partition schema
     */
    static injectConstraint(agentId: string, params: Record<string, unknown>, schema: PartitionSchema): Record<string, unknown>;
}
//# sourceMappingURL=partition-planner.d.ts.map