"""Read this turn's bounded, private quality evidence for deterministic charts. This path never sends data to a model or reads original workbooks. In particular it must not use the finalizer's presentation-truncated evidence as a full dataset. """ from __future__ import annotations import json import os import copy from pathlib import Path import re import stat import time FILE_LIMIT = 4 * 1024 * 1024 TOTAL_LIMIT = 16 * 1024 * 1024 DOCUMENT_LIMIT = 100 def load_visual_evidence(directory: Path, release_id: str, *, exclude_files=frozenset(), cancel_event=None, budget_seconds: float = 0.3) -> list[dict]: """Fail closed on bad identity, permissions, excessive size, or a changed file. The caller already owns an isolated actor/session directory. The pre-turn file inventory prevents previous questions from supplying the new answer's charts. Bounds count bytes before parsing any document. """ if directory.is_symlink(): raise ValueError('invalid evidence directory') started = time.monotonic() documents: list[dict] = [] total = 0 for path in sorted(directory.glob('nao-quality-*.json')): if cancel_event is not None and cancel_event.is_set(): return [] if time.monotonic() - started > budget_seconds: raise ValueError('visual evidence deadline') if path.name in exclude_files: continue if not re.fullmatch(r'nao-quality-[a-f0-9]{32}\.json', path.name): continue fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK) with os.fdopen(fd, 'rb') as source: before = os.fstat(source.fileno()) if (not stat.S_ISREG(before.st_mode) or before.st_mode & 0o077 or before.st_uid != os.getuid() or before.st_size > FILE_LIMIT): raise ValueError('invalid evidence file') total += before.st_size if total > TOTAL_LIMIT or len(documents) >= DOCUMENT_LIMIT: raise ValueError('visual evidence limit') raw = source.read(FILE_LIMIT + 1) after = os.fstat(source.fileno()) if (len(raw) > FILE_LIMIT or before.st_size != after.st_size or before.st_mtime_ns != after.st_mtime_ns): raise ValueError('evidence changed while reading') document = json.loads(raw) if not isinstance(document, dict): raise ValueError('invalid evidence document') result = document.get('result') if (document.get('tool') != 'quality_data' or document.get('releaseId') != release_id or not isinstance(result, dict) or result.get('releaseId') != release_id or not re.fullmatch(r'Q[A-F0-9]{8}', str(document.get('evidenceRef', '')))): raise ValueError('evidence binding mismatch') if document.get('mode') in ('query', 'rank', 'compare', 'top', 'changes', 'defects'): documents.append(document) return documents def visual_result(directory: Path, release_id: str, question: str, turn_id: str, *, exclude_files=frozenset(), cancel_event=None, context=None) -> dict: """Build a presentation-only result without changing turn status. The complete server-normalized context, including an exact-question ``_agentTask`` when present, is forwarded to the deterministic builder. This adapter does not reinterpret the task or question. """ if os.environ.get('QUALITY_ANALYSIS_VISUALS_ENABLED', 'true').lower() not in ('true', '1', 'yes'): return {'visualSchemaVersion': 1, 'visualState': 'not_requested', 'visuals': []} if cancel_event is not None and cancel_event.is_set(): return {'visualSchemaVersion': 1, 'visualState': 'unavailable', 'visuals': []} try: from analysis_visuals import build_visuals evidence = load_visual_evidence(directory, release_id, exclude_files=exclude_files, cancel_event=cancel_event) if cancel_event is not None and cancel_event.is_set(): return {'visualSchemaVersion': 1, 'visualState': 'unavailable', 'visuals': []} return build_visuals(evidence, question, turn_id, context=context) except Exception: # Presentation must not turn an otherwise successful business answer into # a failed task, including unexpected adapter bugs. Do not expose paths. return {'visualSchemaVersion': 1, 'visualState': 'failed', 'visuals': []} def protocol_visual_result(evidence, scopes, question, turn_id, *, release_id, base_context=None): """Build charts independently within each server-issued node/scope frame.""" if os.environ.get('QUALITY_ANALYSIS_VISUALS_ENABLED', 'true').lower() not in ('true', '1', 'yes'): return {'visualSchemaVersion': 1, 'visualState': 'not_requested', 'visuals': [], 'missingEvidence': []} if not isinstance(evidence, list) or not isinstance(scopes, list): return {'visualSchemaVersion': 1, 'visualState': 'failed', 'visuals': [], 'missingEvidence': ['queryPlan图表输入范围无效。']} try: from analysis_visuals import build_visuals from nao_query_plan import scope_context, scope_documents from nao_weight_ranking import ranking_task all_visuals, missing, requested_visuals = [], [], False for scope in scopes: if not isinstance(scope, dict) or not isinstance(scope.get('task'), dict): missing.append('服务器签发的图表范围不完整。') continue task = scope['task'] node_id, scope_id = scope.get('nodeId'), scope.get('scopeId') metric_scope = scope.get('purpose') == 'metrics' or task.get('kind') == 'metrics' child_question = task.get('question') if isinstance(task.get('question'), str) else question selected = scope_documents(evidence, scope, release_id=release_id) # A finite ranking operator can serve a confirmed single-object # metrics request. Keep that root intent through visual completion, # using the same exact scope/proof gate as narrative composition. # An explicit chart request still follows the normal chart checks. from nao_weight_ranking import protocol_scalar_metrics_scope root = base_context.get('_agentTask', {}) if isinstance(base_context, dict) else {} scalar_metrics = (len(selected) == 1 and protocol_scalar_metrics_scope( root, base_context, selected[0])) node_requires_chart = any(node.get('visualPreference') == 'required' for node in root.get('queryPlan', []) if isinstance(node, dict)) if (scalar_metrics and task.get('visualPreference', 'auto') != 'required' and root.get('visualPreference') != 'required' and not node_requires_chart): continue context = scope_context(scope, release_id=release_id, question=question) if isinstance(base_context, dict): for key in ('_protocol', '_protocolScopes'): if key in base_context: context[key] = copy.deepcopy(base_context[key]) preference = task.get('visualPreference', 'auto') fields, stages = task.get('fields'), task.get('stages') or [] optional_auto_scalar = (metric_scope and task.get('visualPreference') == 'auto' and task.get('comparisonRequired') is not True and task.get('trendRequired') is not True and isinstance(fields, list) and len(fields) == 1 and isinstance(stages, list) and len(stages) <= 1) metric_chart_required = (preference == 'required' or task.get('comparisonRequired') is True or task.get('visualType') is not None and not optional_auto_scalar) # Batch Top1 results may intentionally omit auto charts. A model's # style hint alone must not mark that omission as unavailable. if scope.get('purpose') == 'changes': requested_visuals |= preference == 'required' elif metric_scope: requested_visuals |= preference != 'none' and ( task.get('trendRequired') is True or metric_chart_required or ranking_task(task)) else: requested_visuals |= preference != 'none' and ( task.get('trendRequired') is True or preference == 'required' or task.get('visualType') is not None or ranking_task(task)) child = build_visuals(selected, child_question, turn_id, context=context) child_visuals = child.get('visuals') if isinstance(child.get('visuals'), list) else [] metric_visual_requirements = [] if metric_scope and metric_chart_required: stages = task.get('stages') or [] for field in task.get('fields', []): if field == 'rate': metric_visual_requirements.extend( [(stage + '_rate', stage) for stage in stages] if stages else [('composite_rate', None)]) elif field == 'scrapRate': metric_visual_requirements.extend( [(stage + '_scrap_rate', stage) for stage in (stages or ['black', 'bright'])]) elif field == 'totalWeight': metric_visual_requirements.extend([(stage + '_total_weight', stage) for stage in stages]) elif field == 'scrapWeight': metric_visual_requirements.extend([(stage + '_scrap_weight', stage) for stage in stages]) expected_pairs = set(metric_visual_requirements) # The visual builder may offer both stage rates for a composite # request. Keep only the exact node fields and stage frame. child_visuals = [chart for chart in child_visuals if (chart.get('metric'), chart.get('stage')) in expected_pairs] if scope.get('purpose') == 'defects' and preference != 'none': query = task.get('defectQuery') if isinstance(task.get('defectQuery'), dict) else {} expected_dimension = query.get('dimension') expected_sort = task.get('sort', 'scrap_delta' if task.get('comparisonRequired') else 'current_scrap') expected_metric = ('source_defect_delta_weight' if task.get('comparisonRequired') and expected_sort == 'scrap_delta' else 'source_defect_weight') chart_types = ({task.get('visualType')} if task.get('visualType') else {'bar', 'column'}) for stage in task.get('stages', []): matched = any( chart.get('metric') == expected_metric and chart.get('stage') == stage and chart.get('dimension') == expected_dimension and chart.get('type') in chart_types and isinstance(chart.get('scope'), dict) and chart['scope'].get('defect') == query.get('defect') and chart['scope'].get('category') == query.get('category') for chart in child_visuals if isinstance(chart, dict)) if not matched: missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id) +'缺少'+str(stage)+'来源具体缺陷重量图,或所选图表类型无法诚实表达该范围。') for visual in child_visuals: if isinstance(visual, dict): # Keep the established chart wire schema. Node/scope # identity is validated from the server-issued tasks and # evidence before building charts; it is not chart data. all_visuals.append(copy.deepcopy(visual)) if child.get('visualState') == 'failed': missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id)+'图表整理失败。') if scope.get('purpose') != 'defects' and ranking_task(task): from nao_weight_ranking import missing_ranking_visuals missing.extend('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id)+':'+gap for gap in missing_ranking_visuals(task, child_visuals, selected)) elif task.get('trendRequired') and preference != 'none': expected = [] stages = task.get('stages') or [] for field in task.get('fields', []): if field == 'rate': expected.extend([('composite_rate', None)] if not stages else [(stage+'_rate', stage) for stage in stages]) elif field == 'scrapRate': expected.extend([(stage+'_scrap_rate', stage) for stage in (stages or ['black', 'bright'])]) elif field == 'totalWeight': expected.extend([(stage+'_total_weight', stage) for stage in (stages or ['black', 'bright'])]) elif field == 'scrapWeight': expected.extend([('current_scrap_weight', stage) for stage in (stages or ['black', 'bright'])]) for metric, stage in expected: chart_types = ({task.get('visualType')} if task.get('visualType') else {'line', 'area', 'heatmap'}) if not any(chart.get('metric') == metric and chart.get('stage') == stage and chart.get('type') in chart_types for chart in child_visuals): missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id) +'缺少'+str(stage or '综合')+' '+metric+'趋势图。') elif metric_scope and preference != 'none' and metric_chart_required: required = metric_visual_requirements chart_types = ({task.get('visualType')} if task.get('visualType') else {'bar', 'column'}) if not required: missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id) +'缺少当前指标范围可表达的图表。') else: for metric, stage in required: if not any(chart.get('metric') == metric and chart.get('stage') == stage and chart.get('type') in chart_types for chart in child_visuals): missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id) +'缺少'+str(stage or '综合')+' '+metric+'比较图。') elif preference == 'required' and not child_visuals: missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id)+'缺少所需图表。') if len(all_visuals) > 12: missing.append(f'queryPlan共有{len(all_visuals)}张图表,超过12张呈现上限,已截取前12张;结果为部分完成。') all_visuals = all_visuals[:12] state = 'ready' if all_visuals else ('unavailable' if requested_visuals else 'not_requested') return {'visualSchemaVersion': 1, 'visualState': state, 'visuals': all_visuals, 'missingEvidence': list(dict.fromkeys(missing))} except Exception: return {'visualSchemaVersion': 1, 'visualState': 'failed', 'visuals': [], 'missingEvidence': ['queryPlan图表整理失败;已保留文字证据。']}