Watch
1
0
Fork
You've already forked arc
0
forked from hesabix/arc
arc/hesabixAPI/app/services/ai/ai_exploration_service.py
2026-07-16 17:36:58 +00:00

537 lines
18 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

"""
Exploration mode — بررسی زنده، جمع‌بندی شواهد و یافته‌های کلیدی.
- ObservationStore: حافظهٔ ساخت‌یافته per-request
- Explored bundle: ادغام چند tool در یک کارت UX
- Thought: یافته‌های مهم (rule-based + اختیاری LLM)
- PII masking برای نمایش کاربر
"""
from __future__ import annotations
import json
import logging
import re
import uuid
from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional, Tuple
from sqlalchemy.orm import Session
from app.services.ai.ai_tool_intent import estimate_query_complexity
from app.services.ai.ai_tool_keys import tool_label_fa
from app.services.ai.ai_trace import summarize_tool_result, extract_result_count
logger = logging.getLogger(__name__)
EXPLORATION_MODE_EXPLORE = "explore"
EXPLORATION_MODE_AUTO = "auto"
EXPLORATION_MODE_OFF = "off"
# کلید تزریق Thought به context مدل (مرحله بعد)
AGENT_THOUGHT_MESSAGE_TAG = "[agent_thought]"
_SENSITIVE_KEYS = frozenset({
"api_key",
"private_key",
"password",
"secret",
"token",
"certificate",
"csr",
"jwt",
})
_ECONOMIC_CODE_RE = re.compile(r"\b\d{10,14}\b")
@dataclass
class ToolObservation:
tool_name: str
arguments: Dict[str, Any]
result: Any
success: bool
elapsed_ms: Optional[int] = None
citations: Optional[List[str]] = None
@dataclass
class ExplorationBundle:
bundle_id: str
iteration: int
title: str
explore_targets: List[str]
observations: List[ToolObservation] = field(default_factory=list)
@property
def tool_count(self) -> int:
return len(self.observations)
@property
def has_errors(self) -> bool:
return any(not o.success for o in self.observations)
@dataclass
class ThoughtRecord:
thought_id: str
bundle_id: str
iteration: int
body_markdown: str
hypothesis: Optional[str] = None
confidence: Optional[str] = None # low | medium | high
open_questions: List[str] = field(default_factory=list)
class ObservationStore:
"""حافظهٔ کاوش در یک پاسخ assistant."""
def __init__(self) -> None:
self.bundles: List[ExplorationBundle] = []
self.thoughts: List[ThoughtRecord] = []
self.open_questions: List[str] = []
def add_bundle(self, bundle: ExplorationBundle) -> None:
self.bundles.append(bundle)
def add_thought(self, thought: ThoughtRecord) -> None:
self.thoughts.append(thought)
self.open_questions.extend(thought.open_questions)
def latest_thought_markdown(self) -> Optional[str]:
if not self.thoughts:
return None
return self.thoughts[-1].body_markdown
def context_for_llm(self) -> Optional[str]:
"""متن فشرده برای تزریق به حلقهٔ agent."""
if not self.thoughts:
return None
parts: List[str] = []
for t in self.thoughts[-3:]:
parts.append(t.body_markdown)
if self.open_questions:
parts.append(
"**سوالات باز:**\n"
+ "\n".join(f"- {q}" for q in self.open_questions[-5:])
)
return f"{AGENT_THOUGHT_MESSAGE_TAG}\n\n" + "\n\n---\n\n".join(parts)
def resolve_exploration_enabled(
exploration_mode: Optional[str],
user_query: Optional[str],
history_messages: Optional[List[dict]] = None,
) -> bool:
mode = (exploration_mode or EXPLORATION_MODE_AUTO).strip().lower()
if mode == EXPLORATION_MODE_OFF:
return False
if mode == EXPLORATION_MODE_EXPLORE:
return True
# auto: علاوه بر پیچیدگی، وقتی سوال قطعاً نیاز به ابزار دارد (Phase 3) هم
# exploration باید فعال باشد — یک سوال ساده اما داده‌محور نباید کاوش را
# از دست بدهد.
complexity = estimate_query_complexity(user_query, history_messages)
if complexity in ("medium", "complex"):
return True
from app.services.ai.ai_tool_intent import query_expects_tool_use
return query_expects_tool_use(user_query, history_messages)
def new_bundle_id(iteration: int) -> str:
return f"bundle_{iteration}_{uuid.uuid4().hex[:8]}"
def explore_target_for_call(function_name: str, arguments: Any) -> str:
"""برچسب کوتاه برای خط Exploring."""
label = tool_label_fa(function_name)
args = arguments if isinstance(arguments, dict) else {}
hints: List[str] = []
for key in ("business_id", "invoice_id", "person_id", "product_id", "id"):
if key in args and args[key] is not None:
hints.append(f"{key}={args[key]}")
if hints:
return f"{label} ({', '.join(hints[:2])})"
q = args.get("query") or args.get("search") or args.get("code")
if isinstance(q, str) and q.strip():
return f"{label}: {q.strip()[:40]}"
return label
def bundle_title_from_calls(function_calls: List[Dict[str, Any]]) -> str:
if len(function_calls) == 1:
return explore_target_for_call(
function_calls[0].get("name", "unknown"),
function_calls[0].get("arguments", {}),
)
labels = [
tool_label_fa(c.get("name", "unknown")) for c in function_calls[:4]
]
if len(function_calls) > 4:
return f"{', '.join(labels)} +{len(function_calls) - 4}"
return " · ".join(labels)
def build_explored_body_markdown(
bundle: ExplorationBundle,
*,
mask_pii: bool = True,
) -> str:
"""جدول/خلاصهٔ Explored برای UI."""
lines: List[str] = []
for obs in bundle.observations:
label = tool_label_fa(obs.tool_name)
status = "✓" if obs.success else "✗"
summary = summarize_tool_result(obs.tool_name, obs.result)
if mask_pii:
summary = mask_sensitive_text(summary)
lines.append(f"#### {status} {label}")
if summary.strip():
lines.append(summary.strip())
if obs.citations:
refs = ", ".join(obs.citations[:5])
if len(obs.citations) > 5:
refs += f" (+{len(obs.citations) - 5})"
lines.append(f"*منابع:* {refs}")
lines.append("")
return "\n".join(lines).strip()
def _extract_claims_from_result(tool_name: str, result: Any) -> List[str]:
"""استخراج claimهای ساخت‌یافته از نتیجه tool."""
claims: List[str] = []
if not isinstance(result, dict):
return claims
if result.get("error"):
msg = result.get("message") or result.get("error")
claims.append(f"خطا در {tool_label_fa(tool_name)}: {msg}")
return claims
for key in ("message", "summary", "description", "status"):
val = result.get(key)
if isinstance(val, str) and val.strip():
claims.append(val.strip()[:400])
break
for key in ("items", "data", "results", "invoices", "products"):
items = result.get(key)
if isinstance(items, list) and items:
total = (
(result.get("pagination") or {}).get("total")
if isinstance(result.get("pagination"), dict)
else len(items)
)
claims.append(f"{tool_label_fa(tool_name)}: **{total}** مورد")
break
# فیلدهای حساس / مالیاتی
for key in (
"tax_memory_id",
"fiscal_id",
"economic_code",
"taxpayer_id",
"sandbox",
"certificate",
"tracking_code",
"error_code",
):
if key in result and result[key] is not None:
val = result[key]
if isinstance(val, str) and len(val) > 80:
val = f"{val[:40]}… ({len(val)} chars)"
claims.append(f"**{key}**: `{val}`")
return claims[:8]
def build_thought_markdown_rule_based(
bundle: ExplorationBundle,
user_query: Optional[str],
*,
language: str = "fa",
) -> Tuple[str, Optional[str], str, List[str]]:
"""
Thought بدون LLM — سریع و پایدار.
Returns: (body_markdown, hypothesis, confidence, open_questions)
"""
findings: List[str] = []
open_questions: List[str] = []
errors = 0
for obs in bundle.observations:
if not obs.success:
errors += 1
findings.extend(_extract_claims_from_result(obs.tool_name, obs.result))
if not findings:
for obs in bundle.observations:
snippet = summarize_tool_result(obs.tool_name, obs.result)
if snippet.strip():
findings.append(
f"**{tool_label_fa(obs.tool_name)}:** {snippet.strip()[:300]}"
)
findings = findings[:7]
findings_header = (
"### یافته‌های مهم" if language == "fa" else "### Important findings"
)
body_lines = [findings_header, ""]
for i, f in enumerate(findings, 1):
body_lines.append(f"{i}. {mask_sensitive_text(f)}")
hypothesis: Optional[str] = None
confidence = "medium"
if errors == len(bundle.observations) and bundle.tool_count > 0:
hypothesis = (
"اجرای ابزارها با خطا مواجه شد؛ داده کافی برای نتیجه‌گیری نیست."
if language == "fa"
else "Tool execution failed; not enough data to conclude."
)
confidence = "low"
open_questions.append(
"آیا پارامترهای جستجو (شناسه کسب‌وکار، فاکتور و …) درست است؟"
if language == "fa"
else "Are search parameters (business id, invoice, etc.) correct?"
)
elif errors > 0:
hypothesis = (
"بخشی از داده‌ها در دسترس نبود؛ پاسخ بر اساس شواهد موجود است."
if language == "fa"
else "Some data was unavailable; answer is based on available evidence."
)
confidence = "medium"
elif len(findings) >= 3:
hypothesis = (
"شواهد کافی جمع شد؛ می‌توان پاسخ نهایی یا کاوش تکمیلی ارائه داد."
if language == "fa"
else "Enough evidence gathered; ready for a final answer or follow-up exploration."
)
confidence = "high"
elif findings:
hypothesis = (
"یافته‌های اولیه ثبت شد؛ در صورت نیاز کاوش تکمیلی پیشنهاد می‌شود."
if language == "fa"
else "Initial findings recorded; follow-up exploration may be needed."
)
confidence = "medium"
else:
hypothesis = (
"نتیجهٔ ابزارها خالی یا غیرقابل تفسیر بود."
if language == "fa"
else "Tool results were empty or not interpretable."
)
confidence = "low"
open_questions.append(
"سوال را دقیق‌تر یا با شناسه مشخص تکرار کنید."
if language == "fa"
else "Please rephrase the question or include a specific identifier."
)
if hypothesis:
hypothesis_label = "**فرضیه:**" if language == "fa" else "**Hypothesis:**"
body_lines.extend(["", f"{hypothesis_label} {hypothesis}"])
body = "\n".join(body_lines)
return body, hypothesis, confidence, open_questions
def observation_store_has_evidence(store: ObservationStore) -> bool:
return bool(store.bundles) or bool(store.thoughts)
def should_continue_exploring(
store: ObservationStore,
iteration: int,
max_iterations: int,
) -> bool:
"""آیا بر اساس evidence هنوز کاوش لازم است؟"""
if iteration >= max_iterations:
return False
if not observation_store_has_evidence(store):
return iteration < max_iterations
if not store.thoughts:
return True
last = store.thoughts[-1]
if last.confidence == "high" and not last.open_questions:
return False
if last.confidence == "low" and iteration < max_iterations:
return True
return bool(last.open_questions) and iteration < max_iterations
def is_tool_result_productive(result: Any) -> bool:
"""آیا خروجی یک ابزار برای ادامهٔ تحلیل مفید است؟"""
if isinstance(result, dict) and result.get("error"):
return False
count = extract_result_count(result) if isinstance(result, dict) else None
return count is None or count > 0
def assess_tool_round_productivity(
function_calls: List[Dict[str, Any]],
function_results: Dict[str, Any],
lookup_result: Any,
) -> bool:
"""آیا حداقل یک ابزار در این نوبت دادهٔ معنادار برگرداند؟"""
for call in function_calls:
result = lookup_result(function_results, call)
if is_tool_result_productive(result):
return True
return False
def should_agent_continue_after_text(
*,
exploration_enabled: bool,
observation_store: Optional[ObservationStore],
iteration: int,
max_iterations: int,
budget: Any = None,
round_text: str = "",
) -> bool:
"""
توقف/ادامهٔ سراسری پس از پاسخ متنی مدل (بدون tool call).
در حالت exploration از Thought استفاده می‌کند؛ در هر حالت سقف budget را رعایت می‌کند.
"""
if budget is not None and budget.remaining_iterations(iteration) <= 0:
return False
if iteration >= max_iterations:
return False
if not exploration_enabled or observation_store is None:
return False
return should_continue_exploring(
observation_store,
iteration,
max_iterations,
)
async def synthesize_thought_with_llm(
provider: Any,
model: str,
max_tokens: int,
temperature: float,
bundle: ExplorationBundle,
user_query: Optional[str],
explored_markdown: str,
db: Optional[Session] = None,
*,
language: str = "fa",
) -> Optional[str]:
"""Thought غنی با LLM (اختیاری، فقط explore صریح)."""
import asyncio
from app.services.ai.prompt_service import get_prompt_by_key
system = get_prompt_by_key(db, "aux.exploration")
if language == "fa":
user_content = (
f"سوال کاربر: {user_query or ''}\n\n"
f"ابزارهای این دسته: {bundle.title}\n\n"
f"نتایج:\n{explored_markdown[:6000]}"
)
else:
user_content = (
f"User question: {user_query or ''}\n\n"
f"Tools in this bundle: {bundle.title}\n\n"
f"Results:\n{explored_markdown[:6000]}"
)
messages = [
{"role": "system", "content": system},
{"role": "user", "content": user_content},
]
def _run() -> Dict[str, Any]:
return provider.chat_completion(
messages=messages,
model=model,
max_tokens=min(900, max_tokens),
temperature=min(0.4, float(temperature)),
tools=None,
)
try:
loop = asyncio.get_event_loop()
resp = await loop.run_in_executor(None, _run)
choices = resp.get("choices") or []
if not choices:
return None
msg = choices[0].get("message") or {}
content = msg.get("content")
if isinstance(content, str) and content.strip():
return content.strip()
except Exception as exc:
logger.warning("LLM thought synthesis failed: %s", exc)
return None
def mask_sensitive_text(text: str, *, admin_view: bool = False) -> str:
"""ماسک PII/رمز برای نمایش کاربر عادی."""
if admin_view or not text:
return text
out = text
for key in _SENSITIVE_KEYS:
pattern = re.compile(
rf"(\*\*{key}\*\*:\s*`)([^`]+)(`)",
re.IGNORECASE,
)
out = pattern.sub(
lambda m: f"{m.group(1)}{_mask_value(m.group(2), key)}{m.group(3)}",
out,
)
# economic codes in plain text
def _mask_code(match: re.Match) -> str:
s = match.group(0)
if len(s) <= 6:
return s
return s[:4] + "…" + s[-2:]
out = _ECONOMIC_CODE_RE.sub(_mask_code, out)
if "plain text" in out.lower() or "plain_text" in out.lower():
out = re.sub(
r"(plain\s*text[^.\n]*)",
"ذخیرهٔ ناامن (جزئیات فقط برای مدیر)",
out,
flags=re.IGNORECASE,
)
return out
def _mask_value(value: str, key: str) -> str:
key_l = key.lower()
if "key" in key_l or "secret" in key_l or "token" in key_l:
if len(value) <= 8:
return "****"
return f"…{value[-4:]} ({len(value)} chars)"
if "certificate" in key_l or "csr" in key_l:
if len(value) == 0 or value in ("0", "None", "null"):
return "خالی"
return f"[{len(value)} chars]"
return value[:6] + "…" if len(value) > 12 else value
def extract_entity_refs_from_calls(
function_calls: List[Dict[str, Any]],
) -> List[Dict[str, Any]]:
"""ارجاع entity برای لینک در UI."""
refs: List[Dict[str, Any]] = []
seen: set = set()
for call in function_calls:
args = call.get("arguments") or {}
if not isinstance(args, dict):
continue
mapping = [
("invoice_id", "invoice"),
("person_id", "person"),
("product_id", "product"),
("business_id", "business"),
("lead_id", "lead"),
("deal_id", "deal"),
]
for field, entity_type in mapping:
val = args.get(field)
if val is not None:
key = f"{entity_type}:{val}"
if key not in seen:
seen.add(key)
refs.append({"type": entity_type, "id": val})
return refs[:8]