@ai.ntellect/core 1.0.0 → 1.1.0

package/agent/entity-resolver/explore-strategy.ts

@@ -0,0 +1,82 @@
+import * as path from "path";
+import * as fs from "fs";
+import { ScoredCandidate, Entity } from "./types";
+import { EntityIndex } from "./entity-index";
+
+export type ExploreAction = {
+  type: "directory_lister";
+  path: string;
+  reason: string;
+};
+
+export class ExploreStrategy {
+  constructor(private index: EntityIndex) {}
+
+  plan(candidates: ScoredCandidate[], cwd: string): ExploreAction[] {
+    const actions: ExploreAction[] = [];
+
+    if (candidates.length === 0) {
+      actions.push({ type: "directory_lister", path: cwd, reason: "no candidates, list cwd" });
+      return actions;
+    }
+
+    const topDir = candidates.find(c => c.entity.category === "dir");
+    const topFile = candidates.find(c => c.entity.category === "file");
+
+    if (topDir && topFile) {
+      if (topDir.breakdown.total > topFile.breakdown.total) {
+        actions.push({
+          type: "directory_lister",
+          path: cwd,
+          reason: `top candidate is dir "${topDir.entity.filename}", list cwd to confirm`,
+        });
+      } else {
+        const dirPath = path.dirname(topFile.entity.path);
+        if (dirPath !== cwd && fs.existsSync(dirPath)) {
+          actions.push({
+            type: "directory_lister",
+            path: dirPath,
+            reason: `top candidate is file "${topFile.entity.filename}", list its parent`,
+          });
+        } else {
+          actions.push({
+            type: "directory_lister",
+            path: cwd,
+            reason: "list cwd to disambiguate",
+          });
+        }
+      }
+      return actions;
+    }
+
+    if (topDir) {
+      actions.push({
+        type: "directory_lister",
+        path: topDir.entity.path,
+        reason: `explore dir candidate "${topDir.entity.filename}"`,
+      });
+      return actions;
+    }
+
+    if (topFile) {
+      const dirPath = path.dirname(topFile.entity.path);
+      if (dirPath !== cwd && fs.existsSync(dirPath)) {
+        actions.push({
+          type: "directory_lister",
+          path: dirPath,
+          reason: `explore parent of file candidate "${topFile.entity.filename}"`,
+        });
+      } else {
+        actions.push({
+          type: "directory_lister",
+          path: cwd,
+          reason: `list cwd for file candidate "${topFile.entity.filename}"`,
+        });
+      }
+      return actions;
+    }
+
+    actions.push({ type: "directory_lister", path: cwd, reason: "fallback: list cwd" });
+    return actions;
+  }
+}

package/agent/entity-resolver/index.ts

@@ -0,0 +1,22 @@
+export { EntityIndex } from "./entity-index";
+export type { TargetResolution, LookupMode } from "./entity-index";
+export { scoreEntities } from "./scorer";
+export { computeConfidence, confidenceImproved } from "./confidence";
+export { EntityResolver, findEntityInInput } from "./resolver";
+export { ExploreStrategy, type ExploreAction } from "./explore-strategy";
+
+export type {
+  Entity,
+  EntityCategory,
+  ScoredCandidate,
+  ScoreBreakdown,
+  Confidence,
+  ConfidenceLevel,
+  EntityReference,
+  EntityResolution,
+  ExplorationBudget,
+  PendingIntent,
+  ConversationState,
+  ResolutionTraceEntry,
+  ResolverContext,
+} from "./types";

package/agent/entity-resolver/resolver.ts

@@ -0,0 +1,193 @@
+import {
+  EntityReference,
+  EntityResolution,
+  ResolverContext,
+  Entity,
+  ScoredCandidate,
+  Confidence,
+  ResolutionTraceEntry,
+  EntityHandle,
+} from "./types";
+import { EntityIndex } from "./entity-index";
+import { scoreEntities } from "./scorer";
+import { computeConfidence } from "./confidence";
+
+const TYPE_HINT_WORDS: Record<string, string[]> = {
+  file: ["fichier", "file", "read", "lis", "lecture", "ouvre", "contenu", "md", "markdown"],
+  dir: ["dossier", "dir", "folder", "list", "lister", "répertoire", "repertoire"],
+  command: ["commande", "run", "execute", "exec", "lance"],
+  test: ["test", "spec", "tests"],
+  workflow: ["workflow", "pipeline"],
+  service: ["service", "daemon", "api"],
+};
+
+function extractCategoryHint(message: string): string | null {
+  const lower = message.toLowerCase();
+  for (const [cat, words] of Object.entries(TYPE_HINT_WORDS)) {
+    if (words.some(w => lower.includes(w))) return cat;
+  }
+  return null;
+}
+
+function extractReferences(message: string): string[] {
+  const normalized = message
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "");
+
+  const candidates = new Set<string>();
+
+  const clean = normalized.replace(/[?.,!;:()"']/g, " ");
+
+  const tokens = clean.split(/\s+/).filter(t => t.length > 0);
+
+  for (const token of tokens) {
+    const lower = token.toLowerCase();
+    if (["le", "la", "les", "un", "une", "des", "du", "de", "et", "ou",
+         "est", "sont", "dans", "pour", "sur", "avec", "sans", "pas",
+         "tu", "je", "il", "elle", "on", "nous", "vous", "ils", "elles",
+         "me", "te", "se", "lui", "leur", "moi", "toi", "qui", "que",
+         "quoi", "dont", "ou", "ce", "cet", "cette", "ces", "mon", "ton",
+         "son", "ma", "ta", "sa", "mes", "tes", "ses", "nos", "vos",
+         "leurs", "lui", "leur", "eux", "ca", "ça", "cela", "ceci",
+         "elle", "lui", "moi", "nous", "vous", "eux", "elles",
+         "fichier", "dossier", "contenu", "lister", "repertoire",
+         "stp", "svp", "merci", "bonjour", "salut", "bonsoir",
+         "peux", "peut", "veux", "veut", "vas", "va", "vais",
+         "faire", "fais", "fait", "donne", "donner",
+         "vois", "voir", "regarde", "regarder",
+         "dis", "dire", "dites", "lis", "lit", "lire",
+         "ouvre", "ouvrir", "ouvres",
+         "montre", "montrer", "trouve", "trouver",
+         "cherche", "chercher", "affiche", "afficher",
+         "ajoute", "ajouter", "modifie", "modifier",
+         "supprime", "supprimer", "efface", "effacer",
+    ].includes(lower)) continue;
+
+    if (/[\d]{4,}/.test(token)) continue;
+
+    const parts = token.split(/[-._]/).filter(p => p.length > 0 && p.length < 40);
+    for (const part of parts) {
+      if (part.length >= 2 && !/^\d+$/.test(part)) {
+        candidates.add(part);
+      }
+    }
+  }
+
+  return Array.from(candidates);
+}
+
+export type ResolveResult = {
+  resolution: EntityResolution;
+  trace: ResolutionTraceEntry[];
+  confidence: Confidence;
+  shouldExplore: boolean;
+  handles: Record<string, EntityHandle>;
+};
+
+export class EntityResolver {
+  constructor(
+    private index: EntityIndex,
+    private threshold: number = 0.25
+  ) {}
+
+  resolve(ctx: ResolverContext): ResolveResult {
+    const trace: ResolutionTraceEntry[] = [];
+    const refs = extractReferences(ctx.userMessage);
+    const references: EntityReference[] = [];
+
+    for (const ref of refs) {
+      const entities = this.index.lookup(ref);
+      const candidates = scoreEntities(ref, entities, ctx);
+      const confidence = computeConfidence(candidates);
+
+      let resolved: Entity | null = null;
+      if (confidence.level === "high") {
+        resolved = candidates[0]?.entity || null;
+      }
+
+      const refEntry: EntityReference = {
+        raw: ref,
+        resolved,
+        candidates,
+        confidence,
+      };
+      references.push(refEntry);
+
+      trace.push({
+        query: ref,
+        candidates,
+        confidence: confidence.score,
+        action: resolved ? "auto_resolved" : candidates.length > 0 ? "injected" : "failed",
+      });
+    }
+
+    const resolved = references.filter(r => r.resolved !== null);
+    const ambiguous = references.filter(r => r.resolved === null && r.candidates.length > 0);
+
+    const resolution: EntityResolution = {
+      references,
+      resolved,
+      ambiguous,
+      modifiedInput: ctx.userMessage,
+    };
+
+    const handles: Record<string, EntityHandle> = {};
+    let handleIdx = 0;
+    for (const ref of references) {
+      for (const c of ref.candidates) {
+        const eid = `ent_${handleIdx++}`;
+        handles[eid] = {
+          id: eid,
+          label: c.entity.filename,
+          path: c.entity.path,
+          category: c.entity.category,
+        };
+      }
+    }
+
+    const overallConfidence = this.overallConfidence(references);
+
+    return {
+      resolution,
+      trace,
+      confidence: overallConfidence,
+      shouldExplore: overallConfidence.level === "low" && ambiguous.length > 0,
+      handles,
+    };
+  }
+
+  private overallConfidence(references: EntityReference[]): Confidence {
+    const withCandidates = references.filter(r => r.candidates.length > 0);
+
+    if (withCandidates.length === 0) {
+      return { level: "high", score: 1, gap: 1, reason: "no entity references found" };
+    }
+
+    let totalScore = 0;
+    let minGap = 1;
+    let allHigh = true;
+    let anyLow = false;
+
+    for (const ref of withCandidates) {
+      totalScore += ref.confidence.score;
+      minGap = Math.min(minGap, ref.confidence.gap);
+      if (ref.confidence.level !== "high") allHigh = false;
+      if (ref.confidence.level === "low") anyLow = true;
+    }
+
+    const avgScore = totalScore / withCandidates.length;
+
+    if (allHigh) {
+      return { level: "high", score: avgScore, gap: minGap, reason: "all references resolved with high confidence" };
+    }
+    if (anyLow) {
+      return { level: "low", score: avgScore, gap: minGap, reason: "some references have low confidence" };
+    }
+    return { level: "medium", score: avgScore, gap: minGap, reason: "mixed confidence across references" };
+  }
+}
+
+export function findEntityInInput(message: string): string | null {
+  const refs = extractReferences(message);
+  return refs.length > 0 ? refs[0] : null;
+}

package/agent/entity-resolver/scorer.ts

@@ -0,0 +1,211 @@
+import { Entity, ScoreBreakdown, ScoredCandidate, ResolverContext } from "./types";
+
+const WEIGHTS = {
+  lexical: 0.25,
+  exact: 0.20,
+  stem: 0.15,
+  typeHint: 0.15,
+  context: 0.15,
+  recency: 0.10,
+};
+
+function scoreLexical(query: string, entity: Entity): { score: number; reasons: string[] } {
+  const reasons: string[] = [];
+  const qLower = query.toLowerCase();
+  const tokens = qLower.split(/[-._\s]+/).filter(Boolean);
+  const entityTokens = entity.tokens;
+
+  if (tokens.length === 0) return { score: 0, reasons: [] };
+
+  let matchCount = 0;
+  for (const qt of tokens) {
+    if (entityTokens.some(et => et === qt || et.startsWith(qt) || qt.startsWith(et))) {
+      matchCount++;
+    }
+  }
+
+  let overlap = matchCount / Math.max(tokens.length, entityTokens.length);
+  overlap = Math.min(1, overlap);
+
+  if (overlap > 0) reasons.push(`token overlap ${(overlap * 100).toFixed(0)}%`);
+  return { score: overlap, reasons };
+}
+
+function scoreExact(query: string, entity: Entity): { score: number; reasons: string[] } {
+  const qLower = query.toLowerCase();
+  const reasons: string[] = [];
+
+  if (entity.filename.toLowerCase() === qLower) {
+    reasons.push(`filename exact match: ${entity.filename}`);
+    return { score: 1, reasons };
+  }
+  if (entity.stem.toLowerCase() === qLower) {
+    reasons.push(`stem exact match: ${entity.stem}`);
+    return { score: 0.9, reasons };
+  }
+  if (entity.filename.toLowerCase().includes(qLower)) {
+    reasons.push(`filename contains query`);
+    return { score: 0.6, reasons };
+  }
+  return { score: 0, reasons };
+}
+
+function scoreStem(query: string, entity: Entity): { score: number; reasons: string[] } {
+  const qLower = query.toLowerCase();
+  const reasons: string[] = [];
+
+  if (entity.stem.toLowerCase() === qLower) {
+    reasons.push(`stem match: ${entity.stem}`);
+    return { score: 1, reasons };
+  }
+  if (entity.stem.toLowerCase().includes(qLower) || qLower.includes(entity.stem.toLowerCase())) {
+    reasons.push(`stem partial match`);
+    return { score: 0.7, reasons };
+  }
+  return { score: 0, reasons };
+}
+
+function scoreTypeHint(query: string, entity: Entity): { score: number; reasons: string[] } {
+  const reasons: string[] = [];
+  const qLower = query.toLowerCase();
+  let score = 0;
+
+  const fileHints = /\b(fichier|file|read|lis|lecture|ouvre|contenu)\b/i;
+  const dirHints = /\b(dossier|dir|folder|list|lister|répertoire)\b/i;
+
+  const isFileHint = fileHints.test(qLower);
+  const isDirHint = dirHints.test(qLower);
+
+  if (isFileHint && entity.category === "file") {
+    score = 1;
+    reasons.push("user said 'fichier'/'file' → entity is file");
+  } else if (isDirHint && entity.category === "dir") {
+    score = 1;
+    reasons.push("user said 'dossier'/'dir' → entity is dir");
+  } else if (isFileHint && entity.category !== "file") {
+    score = 0.1;
+  } else if (isDirHint && entity.category !== "dir") {
+    score = 0.1;
+  } else {
+    score = 0.5;
+  }
+
+  return { score, reasons };
+}
+
+function scoreContext(query: string, entity: Entity, ctx: ResolverContext): { score: number; reasons: string[] } {
+  const reasons: string[] = [];
+  const qLower = query.toLowerCase();
+  const lastTarget = ctx.conversationState.lastResolvedEntity;
+  const lastType = ctx.conversationState.lastResolvedType;
+  const pending = ctx.conversationState.pendingIntent;
+
+  let score = 0;
+
+  if (lastTarget) {
+    const lastFile = lastTarget.split("/").pop() || "";
+    const lastStem = lastFile.includes(".") ? lastFile.slice(0, lastFile.lastIndexOf(".")) : lastFile;
+
+    if (lastStem.toLowerCase() === qLower) {
+      score = 1;
+      reasons.push(`continues from last entity: ${lastTarget}`);
+      return { score, reasons };
+    }
+
+    const lastTokens = lastStem.split(/[-._\s]+/).filter(Boolean).map(t => t.toLowerCase());
+    const queryTokens = qLower.split(/[-._\s]+/).filter(Boolean);
+
+    if (lastTokens.some(lt => queryTokens.includes(lt)) || queryTokens.some(qt => lastTokens.includes(qt))) {
+      score = 0.6;
+      reasons.push(`token overlap with last entity: ${lastTarget}`);
+    }
+
+    if (lastType && entity.category === lastType) {
+      score = Math.max(score, 0.4);
+      reasons.push(`same type as last entity: ${lastType}`);
+    }
+
+    const lastDir = lastTarget.includes("/") ? lastTarget.split("/").slice(0, -1).join("/") : "";
+    if (lastDir && entity.id.startsWith(lastDir + "/")) {
+      score = Math.max(score, 0.5);
+      reasons.push(`same directory as last entity`);
+    }
+  }
+
+  if (pending && pending.unresolvedEntity) {
+    const pendingLower = pending.unresolvedEntity.toLowerCase();
+    if (entity.stem.toLowerCase() === pendingLower || entity.filename.toLowerCase().includes(pendingLower)) {
+      score = Math.max(score, 0.7);
+      reasons.push(`matches pending unresolved entity: ${pending.unresolvedEntity}`);
+    }
+  }
+
+  if (score === 0) {
+    reasons.push("no contextual match");
+  }
+
+  return { score: Math.min(1, score), reasons };
+}
+
+function scoreRecency(query: string, entity: Entity, ctx: ResolverContext): { score: number; reasons: string[] } {
+  const reasons: string[] = [];
+  const msgs = ctx.conversationHistory.slice(-6);
+
+  for (const msg of msgs) {
+    const content = msg.content.toLowerCase();
+    if (content.includes(entity.filename.toLowerCase()) || content.includes(entity.stem.toLowerCase())) {
+      reasons.push(`mentioned in recent conversation: ${entity.filename}`);
+      return { score: 1, reasons };
+    }
+    for (const token of entity.tokens) {
+      if (content.includes(token)) {
+        reasons.push(`token "${token}" in recent conversation`);
+        return { score: 0.8, reasons };
+      }
+    }
+  }
+
+  return { score: 0, reasons: ["not recently mentioned"] };
+}
+
+export function scoreEntities(
+  query: string,
+  entities: Entity[],
+  ctx: ResolverContext
+): ScoredCandidate[] {
+  return entities.map(entity => {
+    const lex = scoreLexical(query, entity);
+    const exact = scoreExact(query, entity);
+    const stem = scoreStem(query, entity);
+    const type = scoreTypeHint(query, entity);
+    const context = scoreContext(query, entity, ctx);
+    const recency = scoreRecency(query, entity, ctx);
+
+    const breakdown: ScoreBreakdown = {
+      lexical: lex.score,
+      typeHint: type.score,
+      context: context.score,
+      recency: recency.score,
+      total: 0,
+    };
+
+    breakdown.total =
+      WEIGHTS.lexical * lex.score +
+      WEIGHTS.exact * exact.score +
+      WEIGHTS.stem * stem.score +
+      WEIGHTS.typeHint * type.score +
+      WEIGHTS.context * context.score +
+      WEIGHTS.recency * recency.score;
+
+    const reasons = [
+      ...lex.reasons,
+      ...exact.reasons,
+      ...stem.reasons,
+      ...type.reasons,
+      ...context.reasons,
+      ...recency.reasons,
+    ];
+
+    return { entity, breakdown, reasons };
+  }).sort((a, b) => b.breakdown.total - a.breakdown.total);
+}

package/agent/entity-resolver/types.ts

@@ -0,0 +1,98 @@
+export type EntityCategory = "file" | "dir" | "command" | "workflow" | "test" | "service";
+
+export type Entity = {
+  id: string;
+  category: EntityCategory;
+  filename: string;
+  stem: string;
+  extension: string | null;
+  tokens: string[];
+  path: string;
+};
+
+export type ScoredCandidate = {
+  entity: Entity;
+  breakdown: ScoreBreakdown;
+  reasons: string[];
+};
+
+export type ScoreBreakdown = {
+  lexical: number;
+  typeHint: number;
+  context: number;
+  recency: number;
+  total: number;
+};
+
+export type ConfidenceLevel = "high" | "medium" | "low";
+
+export type Confidence = {
+  level: ConfidenceLevel;
+  score: number;
+  gap: number;
+  reason: string;
+};
+
+export type EntityReference = {
+  raw: string;
+  resolved: Entity | null;
+  candidates: ScoredCandidate[];
+  confidence: Confidence;
+};
+
+export type EntityResolution = {
+  references: EntityReference[];
+  resolved: EntityReference[];
+  ambiguous: EntityReference[];
+  modifiedInput: string;
+};
+
+export type ExplorationBudget = {
+  maxSteps: number;
+  maxExplorations: number;
+  maxToolCalls: number;
+  stepsUsed: number;
+  explorationsUsed: number;
+  toolCallsUsed: number;
+};
+
+export type PendingIntent = {
+  action: string | null;
+  unresolvedEntity: string | null;
+  originalInput: string;
+  turn: number;
+  failed: boolean;
+};
+
+export type ConversationState = {
+  currentGoal: string;
+  currentTarget: string | null;
+  lastResolvedEntity: string | null;
+  lastResolvedType: EntityCategory | null;
+  pendingTask: string | null;
+  turnCount: number;
+  pendingIntent: PendingIntent | null;
+};
+
+export type EntityHandle = {
+  id: string;
+  label: string;
+  path: string;
+  category: EntityCategory;
+};
+
+export type ResolutionTraceEntry = {
+  query: string;
+  candidates: ScoredCandidate[];
+  confidence: number;
+  action: "auto_resolved" | "injected" | "explored" | "failed";
+  exploration?: string;
+};
+
+export type ResolverContext = {
+  userMessage: string;
+  conversationHistory: { role: string; content: string }[];
+  conversationState: ConversationState;
+  cwd: string;
+  entityIndex: any;
+};