agent-memory-engine 0.1.0__py3-none-any.whl

agent_memory/__init__.py

@@ -0,0 +1,33 @@
+from agent_memory.client import MemoryClient
+from agent_memory.models import (
+    ConflictRecord,
+    ConflictResolution,
+    ConversationTurn,
+    HealthReport,
+    MaintenanceReport,
+    MemoryDraft,
+    MemoryItem,
+    MemoryLayer,
+    MemoryType,
+    QueryIntent,
+    RelationEdge,
+    SearchResult,
+    TraceReport,
+)
+
+__all__ = [
+    "ConflictRecord",
+    "ConflictResolution",
+    "ConversationTurn",
+    "HealthReport",
+    "MaintenanceReport",
+    "MemoryClient",
+    "MemoryDraft",
+    "MemoryItem",
+    "MemoryLayer",
+    "MemoryType",
+    "QueryIntent",
+    "RelationEdge",
+    "SearchResult",
+    "TraceReport",
+]

agent_memory/cli.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import asdict, is_dataclass, replace
+from enum import Enum
+import json
+from pathlib import Path
+from typing import Any
+
+from agent_memory.client import MemoryClient
+from agent_memory.config import AgentMemoryConfig
+
+
+def _json_default(value: Any) -> Any:
+    if isinstance(value, Enum):
+        return value.value
+    if hasattr(value, "isoformat"):
+        return value.isoformat()
+    if is_dataclass(value):
+        return asdict(value)
+    raise TypeError(f"Object of type {type(value)!r} is not JSON serializable")
+
+
+def _print_json(payload: Any) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2, default=_json_default))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="agent-memory", description="Zero-config local memory engine for agents.")
+    parser.add_argument("--db", dest="database_path", help="Path to the SQLite database file.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    store = subparsers.add_parser("store", help="Store a memory.")
+    store.add_argument("content")
+    store.add_argument("--source-id", default="cli")
+    store.add_argument("--memory-type", default="semantic")
+    store.add_argument("--causal-parent-id")
+    store.add_argument("--tag", action="append", default=[])
+
+    search = subparsers.add_parser("search", help="Search memories.")
+    search.add_argument("query")
+    search.add_argument("--limit", type=int, default=5)
+
+    trace = subparsers.add_parser("trace", help="Trace a memory graph.")
+    trace.add_argument("memory_id")
+    trace.add_argument("--max-depth", type=int, default=10)
+
+    evolution = subparsers.add_parser("evolution", help="Show memory evolution history.")
+    evolution.add_argument("memory_id")
+    evolution.add_argument("--limit", type=int, default=20)
+
+    audit = subparsers.add_parser("audit", help="Show recent audit events.")
+    audit.add_argument("--limit", type=int, default=20)
+
+    health = subparsers.add_parser("health", help="Show memory health report.")
+
+    maintain = subparsers.add_parser("maintain", help="Run maintenance cycle.")
+
+    export_cmd = subparsers.add_parser("export", help="Export to JSONL.")
+    export_cmd.add_argument("path")
+
+    import_cmd = subparsers.add_parser("import", help="Import from JSONL.")
+    import_cmd.add_argument("path")
+
+    return parser
+
+
+def _build_client(database_path: str | None) -> MemoryClient:
+    config = AgentMemoryConfig.from_env()
+    if database_path:
+        config = replace(config, database_path=database_path)
+    return MemoryClient(config=config)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    client = _build_client(args.database_path)
+    try:
+        if args.command == "store":
+            item = client.add(
+                args.content,
+                source_id=args.source_id,
+                memory_type=args.memory_type,
+                causal_parent_id=args.causal_parent_id,
+                tags=list(args.tag),
+            )
+            _print_json({"id": item.id, "content": item.content, "trust_score": item.trust_score})
+            return 0
+
+        if args.command == "search":
+            _print_json(
+                [
+                    {
+                        "id": result.item.id,
+                        "content": result.item.content,
+                        "score": result.score,
+                        "matched_by": result.matched_by,
+                    }
+                    for result in client.search(args.query, limit=args.limit)
+                ]
+            )
+            return 0
+
+        if args.command == "trace":
+            _print_json(asdict(client.trace_graph(args.memory_id, max_depth=args.max_depth)))
+            return 0
+
+        if args.command == "evolution":
+            _print_json(client.evolution_events(memory_id=args.memory_id, limit=args.limit))
+            return 0
+
+        if args.command == "audit":
+            _print_json(client.audit_events(limit=args.limit))
+            return 0
+
+        if args.command == "health":
+            _print_json(asdict(client.health()))
+            return 0
+
+        if args.command == "maintain":
+            _print_json(asdict(client.maintain()))
+            return 0
+
+        if args.command == "export":
+            path = str(Path(args.path))
+            _print_json({"path": path, "exported": client.export_jsonl(path)})
+            return 0
+
+        if args.command == "import":
+            path = str(Path(args.path))
+            _print_json({"path": path, "imported": client.import_jsonl(path)})
+            return 0
+
+        parser.error(f"Unsupported command: {args.command}")
+        return 2
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_memory/client.py

@@ -0,0 +1,355 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import replace
+from datetime import datetime, timezone
+import uuid
+
+from agent_memory.controller.conflict import ConflictDetector
+from agent_memory.controller.consolidation import ConsolidationPlanner
+from agent_memory.controller.forgetting import ForgettingPolicy
+from agent_memory.config import AgentMemoryConfig
+from agent_memory.controller.router import IntentRouter, reciprocal_rank_fusion, strip_intent_markers
+from agent_memory.controller.trust import TrustScorer
+from agent_memory.embedding.local_provider import LocalEmbeddingProvider
+from agent_memory.governance.audit import AuditLogReader
+from agent_memory.governance.export import MemoryExporter, MemoryImporter
+from agent_memory.governance.health import MemoryHealthMonitor
+from agent_memory.extraction.entity_extractor import EntityExtractor
+from agent_memory.extraction.pipeline import ConversationMemoryPipeline
+from agent_memory.llm.base import LLMClient
+from agent_memory.models import (
+    ConflictRecord,
+    ConversationTurn,
+    MaintenanceReport,
+    MemoryDraft,
+    MemoryItem,
+    MemoryLayer,
+    MemoryType,
+    RelationEdge,
+    RelationType,
+    SearchResult,
+    TraceReport,
+)
+from agent_memory.storage.sqlite_backend import SQLiteBackend
+
+
+class MemoryClient:
+    def __init__(
+        self,
+        config: AgentMemoryConfig | None = None,
+        backend: SQLiteBackend | None = None,
+        embedding_provider: LocalEmbeddingProvider | None = None,
+        entity_extractor: EntityExtractor | None = None,
+        llm_client: LLMClient | None = None,
+    ) -> None:
+        self.config = config or AgentMemoryConfig.from_env()
+        self.backend = backend or SQLiteBackend(
+            self.config.database_path,
+            prefer_sqlite_vec=self.config.enable_sqlite_vec,
+        )
+        self.embedding_provider = embedding_provider or LocalEmbeddingProvider()
+        self.entity_extractor = entity_extractor or EntityExtractor()
+        self.router = IntentRouter()
+        self.llm_client = llm_client
+        self.pipeline = ConversationMemoryPipeline(entity_extractor=self.entity_extractor, llm_client=self.llm_client)
+        self.turn_model = ConversationTurn
+        self.forgetting_policy = ForgettingPolicy()
+        self.trust_scorer = TrustScorer()
+        self.conflict_detector = ConflictDetector(self.backend, llm_client=self.llm_client)
+        self.consolidation_planner = ConsolidationPlanner()
+        self.health_monitor = MemoryHealthMonitor(self.backend)
+        self.audit_reader = AuditLogReader(self.backend)
+        self.exporter = MemoryExporter(self.backend)
+        self.importer = MemoryImporter(self.backend)
+
+    def close(self) -> None:
+        self.backend.close()
+
+    def add(
+        self,
+        content: str,
+        *,
+        source_id: str,
+        memory_type: MemoryType | str = MemoryType.SEMANTIC,
+        importance: float = 0.5,
+        trust_score: float = 0.75,
+        tags: list[str] | None = None,
+        entity_refs: list[str] | None = None,
+        causal_parent_id: str | None = None,
+        supersedes_id: str | None = None,
+    ) -> MemoryItem:
+        memory_type = MemoryType(memory_type)
+        embedding = self.embedding_provider.embed([content])[0]
+        now = datetime.now(timezone.utc)
+        base_trust = self.trust_scorer.score(source_reliability=trust_score)
+        item = MemoryItem(
+            id=str(uuid.uuid4()),
+            content=content,
+            memory_type=memory_type,
+            embedding=embedding,
+            created_at=now,
+            last_accessed=now,
+            importance=importance,
+            trust_score=base_trust,
+            source_id=source_id,
+            entity_refs=entity_refs or self.entity_extractor.extract(content),
+            tags=tags or [],
+            causal_parent_id=causal_parent_id,
+            supersedes_id=supersedes_id,
+        )
+        item = self.backend.add_memory(item)
+        self._attach_structural_relations(item)
+        conflicts = self.detect_conflicts(item)
+        if conflicts:
+            item, _ = self._apply_conflicts(item, conflicts)
+        return item
+
+    def get(self, memory_id: str) -> MemoryItem | None:
+        return self.backend.get_memory(memory_id)
+
+    def delete(self, memory_id: str) -> bool:
+        return self.backend.soft_delete_memory(memory_id)
+
+    def search(self, query: str, limit: int | None = None) -> list[SearchResult]:
+        search_limit = limit or self.config.default_search_limit
+        plan = self.router.plan(query)
+        rankings: dict[str, list[str]] = {}
+        results_by_id: dict[str, MemoryItem] = {}
+        matched_by: dict[str, set[str]] = defaultdict(set)
+        memory_type = plan.filters.get("memory_type")
+        normalized_query = strip_intent_markers(query) or query
+
+        if "semantic" in plan.strategies:
+            embedding = self.embedding_provider.embed([normalized_query])[0]
+            semantic_results = self.backend.search_by_vector(embedding, limit=self.config.semantic_limit, memory_type=memory_type)
+            rankings["semantic"] = [item.id for item, _ in semantic_results]
+            for item, _ in semantic_results:
+                results_by_id[item.id] = item
+                matched_by[item.id].add("semantic")
+
+        if "full_text" in plan.strategies:
+            lexical_results = self.backend.search_full_text(normalized_query, limit=self.config.lexical_limit, memory_type=memory_type)
+            rankings["full_text"] = [item.id for item, _ in lexical_results]
+            for item, _ in lexical_results:
+                results_by_id[item.id] = item
+                matched_by[item.id].add("full_text")
+
+        if "entity" in plan.strategies:
+            entities = self.entity_extractor.extract(normalized_query)
+            entity_results = self.backend.search_by_entities(entities, limit=self.config.entity_limit, memory_type=memory_type)
+            rankings["entity"] = [item.id for item, _ in entity_results]
+            for item, _ in entity_results:
+                results_by_id[item.id] = item
+                matched_by[item.id].add("entity")
+
+        if "causal_trace" in plan.strategies:
+            seed_ids = rankings.get("semantic", [])[:2] or rankings.get("full_text", [])[:2]
+            trace_ids: list[str] = []
+            for seed_id in seed_ids:
+                for ancestor in self.backend.trace_ancestors(seed_id, max_depth=5):
+                    results_by_id[ancestor.id] = ancestor
+                    matched_by[ancestor.id].add("causal_trace")
+                    trace_ids.append(ancestor.id)
+            if trace_ids:
+                rankings["causal_trace"] = trace_ids
+
+        fused = reciprocal_rank_fusion(rankings, k=self.config.rrf_k)
+        final_ids = list(fused.keys())
+        if plan.filters.get("sort") == "recency":
+            final_ids.sort(
+                key=lambda item_id: (
+                    fused.get(item_id, 0.0),
+                    results_by_id[item_id].created_at,
+                ),
+                reverse=True,
+            )
+
+        output: list[SearchResult] = []
+        for memory_id in final_ids[:search_limit]:
+            self.backend.touch_memory(memory_id)
+            refreshed = self.backend.get_memory(memory_id)
+            if refreshed is None:
+                continue
+            output.append(
+                SearchResult(
+                    item=refreshed,
+                    score=fused.get(memory_id, 0.0),
+                    matched_by=sorted(matched_by[memory_id]),
+                )
+            )
+        return output
+
+    def ingest_conversation(self, turns: list[ConversationTurn], source_id: str) -> list[MemoryItem]:
+        drafts = self.pipeline.extract(turns, source_id=source_id)
+        created: list[MemoryItem] = []
+        for draft in drafts:
+            created.append(self.add_from_draft(draft))
+        return created
+
+    def add_from_draft(self, draft: MemoryDraft) -> MemoryItem:
+        return self.add(
+            draft.content,
+            source_id=draft.source_id,
+            memory_type=draft.memory_type,
+            importance=draft.importance,
+            trust_score=draft.trust_score,
+            tags=list(draft.tags),
+            entity_refs=list(draft.entity_refs),
+            causal_parent_id=draft.causal_parent_id,
+            supersedes_id=draft.supersedes_id,
+        )
+
+    def update(self, item: MemoryItem, **changes: object) -> MemoryItem:
+        if "memory_type" in changes and isinstance(changes["memory_type"], str):
+            changes["memory_type"] = MemoryType(changes["memory_type"])
+        updated = replace(item, **changes)
+        updated = self.backend.update_memory(updated)
+        self._attach_structural_relations(updated)
+        if "content" in changes or "entity_refs" in changes:
+            conflicts = self.detect_conflicts(updated)
+            if conflicts:
+                updated, _ = self._apply_conflicts(updated, conflicts)
+        return updated
+
+    def trace(self, memory_id: str, max_depth: int = 10) -> list[MemoryItem]:
+        return self.backend.trace_ancestors(memory_id, max_depth=max_depth)
+
+    def trace_graph(self, memory_id: str, max_depth: int = 10) -> TraceReport:
+        focus = self.get(memory_id)
+        if focus is None:
+            raise ValueError(f"Memory {memory_id} not found")
+        return TraceReport(
+            focus=focus,
+            ancestors=self.backend.trace_ancestors(memory_id, max_depth=max_depth),
+            descendants=self.backend.trace_descendants(memory_id, max_depth=max_depth),
+            relations=self.backend.list_relations(memory_id),
+            evolution_events=self.backend.get_evolution_events(memory_id=memory_id, limit=100),
+        )
+
+    def detect_conflicts(self, item: MemoryItem) -> list[ConflictRecord]:
+        return self.conflict_detector.detect(item)
+
+    def health(self):
+        return self.health_monitor.generate()
+
+    def audit_events(self, limit: int = 50) -> list[dict[str, object]]:
+        return self.audit_reader.recent(limit=limit)
+
+    def evolution_events(self, memory_id: str | None = None, limit: int = 50) -> list[dict[str, object]]:
+        return self.backend.get_evolution_events(memory_id=memory_id, limit=limit)
+
+    def export_jsonl(self, path: str) -> int:
+        return self.exporter.export_jsonl(path)
+
+    def import_jsonl(self, path: str) -> int:
+        return self.importer.import_jsonl(path)
+
+    def maintain(self) -> MaintenanceReport:
+        report = MaintenanceReport()
+        now = datetime.now(timezone.utc)
+        for memory in self.backend.list_memories():
+            age_days = max((now - memory.last_accessed).total_seconds() / 86400.0, 0.0)
+            strength = self.forgetting_policy.effective_strength(memory, age_days=age_days)
+            next_layer = self.forgetting_policy.next_layer(memory, age_days=age_days)
+            updated = memory
+            if next_layer is not memory.layer:
+                updated = replace(updated, layer=next_layer)
+                if next_layer is MemoryLayer.LONG_TERM:
+                    report.promoted += 1
+                else:
+                    report.demoted += 1
+            if strength < 0.1 and age_days > 60:
+                if self.backend.soft_delete_memory(memory.id):
+                    report.decayed += 1
+                continue
+            if updated is not memory:
+                self.backend.update_memory(updated)
+        for memory in self.backend.list_memories():
+            conflicts = self.detect_conflicts(memory)
+            report.conflicts_found += len(conflicts)
+            if conflicts:
+                report.conflicts_resolved += self._apply_conflicts(memory, conflicts)[1]
+        report.consolidated = self.consolidate()
+        return report
+
+    def consolidate(self) -> int:
+        memories = self.backend.list_memories()
+        groups = self.consolidation_planner.find_merge_groups(memories)
+        consolidated = 0
+        for index, group in enumerate(groups, start=1):
+            primary = max(group, key=lambda item: (item.importance, item.trust_score, item.created_at))
+            if any(
+                memory.supersedes_id == primary.id and "consolidated" in memory.tags
+                for memory in memories
+            ):
+                continue
+            draft = self.consolidation_planner.create_merged_draft(
+                group,
+                source_id=f"consolidation:{index}",
+                llm_client=self.llm_client,
+            )
+            merged = self.add_from_draft(
+                replace(
+                    draft,
+                    supersedes_id=primary.id,
+                    causal_parent_id=primary.causal_parent_id,
+                )
+            )
+            for memory in group:
+                if memory.id == primary.id:
+                    continue
+                self.backend.add_relation(
+                    RelationEdge(
+                        source_id=merged.id,
+                        target_id=memory.id,
+                        relation_type=RelationType.SUPERSEDES,
+                    )
+                )
+            consolidated += 1
+        return consolidated
+
+    def _attach_structural_relations(self, item: MemoryItem) -> None:
+        if item.causal_parent_id:
+            self.backend.add_relation(
+                RelationEdge(
+                    source_id=item.id,
+                    target_id=item.causal_parent_id,
+                    relation_type=RelationType.DERIVED_FROM,
+                )
+            )
+        if item.supersedes_id:
+            self.backend.add_relation(
+                RelationEdge(
+                    source_id=item.id,
+                    target_id=item.supersedes_id,
+                    relation_type=RelationType.SUPERSEDES,
+                )
+            )
+
+    def _apply_conflicts(self, item: MemoryItem, conflicts: list[ConflictRecord]) -> tuple[MemoryItem, int]:
+        contradiction_count = 0
+        inserted_relations = 0
+        for conflict in conflicts:
+            contradiction_count += 1
+            inserted_relations += int(
+                self.backend.add_relation(
+                RelationEdge(
+                    source_id=item.id,
+                    target_id=conflict.existing_id,
+                    relation_type=(
+                        RelationType.SUPERSEDES
+                        if conflict.resolution.value == "supersede"
+                        else RelationType.CONTRADICTS
+                    ),
+                )
+            )
+            )
+        age_days = max((datetime.now(timezone.utc) - item.created_at).total_seconds() / 86400.0, 0.0)
+        adjusted_trust = self.trust_scorer.score(
+            source_reliability=item.trust_score,
+            contradiction_count=contradiction_count,
+            age_days=age_days,
+        )
+        updated = replace(item, trust_score=adjusted_trust)
+        return self.backend.update_memory(updated), inserted_relations

agent_memory/config.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class AgentMemoryConfig:
+    database_path: str = str(Path.cwd() / "agent-memory.db")
+    semantic_limit: int = 10
+    lexical_limit: int = 10
+    entity_limit: int = 10
+    default_search_limit: int = 5
+    rrf_k: int = 60
+    enable_sqlite_vec: bool = True
+
+    @classmethod
+    def from_env(cls) -> "AgentMemoryConfig":
+        return cls(
+            database_path=os.getenv("AGENT_MEMORY_DB_PATH", str(Path.cwd() / "agent-memory.db")),
+            semantic_limit=int(os.getenv("AGENT_MEMORY_SEMANTIC_LIMIT", "10")),
+            lexical_limit=int(os.getenv("AGENT_MEMORY_LEXICAL_LIMIT", "10")),
+            entity_limit=int(os.getenv("AGENT_MEMORY_ENTITY_LIMIT", "10")),
+            default_search_limit=int(os.getenv("AGENT_MEMORY_DEFAULT_SEARCH_LIMIT", "5")),
+            rrf_k=int(os.getenv("AGENT_MEMORY_RRF_K", "60")),
+            enable_sqlite_vec=os.getenv("AGENT_MEMORY_ENABLE_SQLITE_VEC", "true").lower() not in {"0", "false", "no"},
+        )

agent_memory/controller/__init__.py

@@ -0,0 +1,15 @@
+from agent_memory.controller.conflict import ConflictDetector
+from agent_memory.controller.consolidation import ConsolidationPlanner
+from agent_memory.controller.forgetting import ForgettingPolicy
+from agent_memory.controller.router import IntentRouter, reciprocal_rank_fusion
+from agent_memory.controller.trust import TrustScorer
+
+__all__ = [
+    "ConflictDetector",
+    "ConsolidationPlanner",
+    "ForgettingPolicy",
+    "IntentRouter",
+    "TrustScorer",
+    "reciprocal_rank_fusion",
+]
+

agent_memory/controller/conflict.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+import re
+from typing import Any
+
+from agent_memory.extraction.prompts import CONFLICT_JUDGE_PROMPT
+from agent_memory.llm.base import LLMClient
+from agent_memory.models import ConflictRecord, ConflictResolution, MemoryItem
+from agent_memory.storage.sqlite_backend import SQLiteBackend
+
+
+NEGATION_MARKERS = ("不", "没", "不是", "不会", "never", "not", "no ")
+PREFERENCE_MARKERS = ("喜欢", "偏好", "prefer", "prefers", "using", "uses", "选择", "selected")
+CONFLICT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "label": {"type": "string", "enum": ["contradicts", "supersedes", "supports", "related", "none"]},
+        "confidence": {"type": "number"},
+        "reason": {"type": "string"},
+    },
+    "required": ["label", "confidence", "reason"],
+    "additionalProperties": False,
+}
+
+
+@dataclass(slots=True)
+class ConflictDetector:
+    backend: SQLiteBackend
+    llm_client: LLMClient | None = None
+
+    def detect(self, candidate: MemoryItem, limit: int = 10) -> list[ConflictRecord]:
+        vector_hits = self.backend.search_by_vector(candidate.embedding, limit=limit)
+        conflicts: list[ConflictRecord] = []
+        for existing, similarity in vector_hits:
+            if existing.id == candidate.id:
+                continue
+            if self.backend.relation_exists_between(
+                candidate.id,
+                existing.id,
+                relation_types=["contradicts", "supersedes"],
+            ):
+                continue
+            label, confidence, reason = self._judge_relationship(candidate, existing, similarity)
+            if label not in {"contradicts", "supersedes"} or confidence < 0.55:
+                continue
+            conflicts.append(
+                ConflictRecord(
+                    existing_id=existing.id,
+                    candidate_id=candidate.id,
+                    confidence=confidence,
+                    resolution=ConflictResolution.SUPERSEDE if label == "supersedes" else ConflictResolution.KEEP_BOTH,
+                    reason=reason,
+                )
+            )
+        conflicts.sort(key=lambda item: item.confidence, reverse=True)
+        return conflicts
+
+    def _judge_relationship(self, candidate: MemoryItem, existing: MemoryItem, similarity: float) -> tuple[str, float, str]:
+        heuristic_confidence = self._contradiction_confidence(candidate.content, existing.content, similarity)
+        heuristic_label = "contradicts" if heuristic_confidence >= 0.55 else "none"
+        heuristic_reason = "Heuristic semantic overlap and polarity mismatch."
+        if self.llm_client is None or similarity < 0.4:
+            return heuristic_label, heuristic_confidence, heuristic_reason
+        try:
+            response = self.llm_client.generate_json(
+                prompt=(
+                    f"Memory A: {existing.content}\n"
+                    f"Memory B: {candidate.content}\n"
+                    "Decide the relationship."
+                ),
+                schema=CONFLICT_SCHEMA,
+                schema_name="memory_conflict_judgement",
+                system_prompt=CONFLICT_JUDGE_PROMPT,
+            )
+        except Exception:
+            return heuristic_label, heuristic_confidence, heuristic_reason
+        label = str(response.get("label", heuristic_label))
+        confidence = float(response.get("confidence", heuristic_confidence))
+        reason = str(response.get("reason", heuristic_reason))
+        return label, confidence, reason
+
+    def _contradiction_confidence(self, left: str, right: str, similarity: float) -> float:
+        left_norm = self._normalize(left)
+        right_norm = self._normalize(right)
+        ratio = SequenceMatcher(None, left_norm, right_norm).ratio()
+        left_negative = any(marker in left_norm for marker in NEGATION_MARKERS)
+        right_negative = any(marker in right_norm for marker in NEGATION_MARKERS)
+        polarity_bonus = 0.25 if left_negative != right_negative else 0.0
+        preference_bonus = 0.15 if any(marker in left_norm or marker in right_norm for marker in PREFERENCE_MARKERS) else 0.0
+        return min(1.0, similarity * 0.45 + ratio * 0.25 + polarity_bonus + preference_bonus)
+
+    def _normalize(self, text: str) -> str:
+        return " ".join(re.findall(r"[\w\u4e00-\u9fff]+", text.lower()))