"""Deterministic evidence contract for broad quality questions. The contract is intentionally about queried business dimensions, not a claim that source defect weights explain the formal composite rate. It never reads unrelated turns or substitutes a different period, release, or filter scope. """ from __future__ import annotations import re from typing import Any from nao_evidence_report import _filters, _same_periods, number, select_comparison_frames from nao_product_defect_pairing import plan_missing_product_defect_stages from nao_period import normalize_period _BROAD = re.compile(r"整体|总体|全面分析|综合分析|公司质量|质量情况|质量怎么样") _SIMPLE_NUMBER = re.compile(r"多少|几(?:%|个百分点|公斤|kg)|数值|是什么") _ANALYSIS = re.compile(r"变化|分析|原因|关注|情况|下降|上升|趋势|怎么|如何") _PRODUCT_PRIORITY = re.compile(r"重点(?:产品|规格)|关注.{0,8}(?:产品|规格)|哪些(?:产品|规格).{0,8}(?:最差|关注|重点)") _FORMAL_FIELDS = {'rate': '合格率', 'scrapRate': '报废率', 'totalWeight': '投入重量', 'scrapWeight': '报废重量'} def _period_equal(left, right): try: normalized_left, normalized_right = normalize_period(left), normalize_period(right) except ValueError: return False return normalized_left is not None and normalized_left == normalized_right def formal_metric_coverage(evidence: list[dict[str, Any]], question: str, context: Any = None) -> dict[str, Any] | None: """Bind a narrow explicit product/two-month request to formal stage fields. Unrecognized language has no authoritative override. This contract never infers a product, year, period, stage, or zero from an absent value. """ from nao_metric_request import metric_request request = metric_request(question, context) if not request: return None product, periods, stages, fields = (request[key] for key in ('product', 'periods', 'stages', 'fields')) contract = {'filters': request['filters'], 'periods': periods, 'stages': stages, 'fields': fields, 'metrics': [], 'missingEvidence': []} requested_context = {**(context if isinstance(context, dict) else {}), 'filters': request['filters'], 'period': periods[0], 'comparisonPeriod': periods[1]} roots, limitations = select_comparison_frames(evidence, requested_context) root = roots[0] if len(roots) == 1 and not limitations else None result = root['result'] if root else {} expected_release = context.get('releaseId') if isinstance(context, dict) else None actual_periods = [(result.get(side) or {}).get('period') for side in ('current', 'comparison')] if (not root or not result.get('releaseId') or expected_release is not None and result.get('releaseId') != expected_release or _filters(result.get('filterBinding')) != contract['filters'] or any(period not in actual_periods for period in periods)): contract['missingEvidence'] = ['缺少与本次明确规格、两期及数据版本一致的正式指标比较。'] return contract from nao_quality_tools import (_valid_composite_rate_reference, _valid_stage_period_coverage, _valid_stage_rate_reference, _valid_stage_scrap_rate_reference) contract.update(evidenceRef=root['evidenceRef'], releaseId=result['releaseId']) for side in ('current', 'comparison'): snapshot = result[side] for stage in stages: metric_snapshot = {**snapshot, 'summary': {stage: snapshot.get(stage)}} try: source_ok, _ = _valid_stage_period_coverage(snapshot, snapshot['period'], stage) rate_ok, _ = _valid_stage_rate_reference(metric_snapshot, snapshot['period'], stage) scrap_rate_ok, _ = _valid_stage_scrap_rate_reference(metric_snapshot, snapshot['period'], stage) except (KeyError, ValueError, TypeError): source_ok = rate_ok = scrap_rate_ok = False values = snapshot.get(stage) if isinstance(snapshot.get(stage), dict) else {} for field in fields: value = values.get(field) numeric = number(value) field_coverage = (rate_ok if field == 'rate' else scrap_rate_ok if field == 'scrapRate' else source_ok) covered = (field_coverage and numeric is not None and not (field in ('scrapRate', 'scrapWeight') and numeric < 0)) contract['metrics'].append({'period': snapshot['period'], 'stage': stage, 'field': field, 'value': value, 'covered': covered, 'sourceCovered': source_ok}) if not covered: period = snapshot['period'] label = '黑片' if stage == 'black' else '亮片' contract['missingEvidence'].append(f'未取得规格{product}在{period["year"]}年{period["month"]}月{label}{_FORMAL_FIELDS[field]}的正式指标或来源覆盖。') return contract def resolve_proven_metric_gaps(contract: dict[str, Any] | None, missing: list[str]) -> tuple[list[str], list[str]]: """Refute only simple, fully understood claims of absent covered metrics. Mixed explanations, row/detail requests, other products/periods, or unknown wording remain missing. A server-wide coverage boolean is never sufficient. """ if not contract or contract['missingEvidence'] or not contract['metrics']: return missing, [] retained, resolved = [], [] product = contract['filters']['product'] for item in missing: text = item.replace(product, '该规格') fields = [field for field, label in _FORMAL_FIELDS.items() if label in text] stages = [stage for stage, label in (('black', '黑片'), ('bright', '亮片')) if label in text] or contract['stages'] # This intentionally small grammar does not interpret free-form model # prose as a machine-readable coverage assertion. simple = re.fullmatch(r'缺少(?:仅针对|针对|该规格|规格|分规格|两期|黑片|亮片|合格率|报废率|投入重量|报废重量|正式数据|数据|的|和|及|、|,|\s|[。;;])+', text) if (simple and fields and set(fields) <= set(contract['fields']) and set(stages) <= set(contract['stages']) and all(row['covered'] for row in contract['metrics'] if row['stage'] in stages and row['field'] in fields)): resolved.append(item) else: retained.append(item) return retained, resolved def _needs_broad_coverage(question: str) -> bool: text = question if isinstance(question, str) else "" return bool(_BROAD.search(text) and (not _SIMPLE_NUMBER.search(text) or _ANALYSIS.search(text))) def is_coverage_question(question: str, context: Any = None) -> bool: from nao_agent_task import task_from_context task = task_from_context(context, question) if task is not None: return bool(task.get('dimensions')) text = question if isinstance(question, str) else '' return _needs_broad_coverage(text) or bool(_PRODUCT_PRIORITY.search(text)) def _same_scope(result: dict[str, Any], root: dict[str, Any]) -> bool: return _filters(result.get('filters')) == _filters(root.get('filterBinding')) def _matching(evidence: list[dict[str, Any]], root: dict[str, Any], kind: str, *, dimension: str, stage: str | None = None) -> list[dict[str, Any]]: return [doc['result'] for doc in evidence if isinstance(doc.get('result'), dict) and doc['result'].get('kind') == kind and doc['result'].get('releaseId') == root.get('releaseId') and doc['result'].get('dimension') == dimension and doc['result'].get('stage') == stage and _same_periods(doc['result'], root) and _same_scope(doc['result'], root)] def _root(evidence: list[dict[str, Any]], context: Any) -> dict[str, Any] | None: roots, limitations = select_comparison_frames(evidence, context) return roots[0]['result'] if len(roots) == 1 and not limitations else None def _requirements(evidence: list[dict[str, Any]], question: str, context: Any) -> list[tuple[str, str, str | None, str]]: from nao_agent_task import task_from_context, dimension_stages task = task_from_context(context, question) if task is not None: dimensions = task.get('dimensions', []) requirements = [] for dimension, label in (('department', '产业部变化'), ('group', '业务分组变化'), ('product', '产品多维重点排序')): if dimension in dimensions: for stage in dimension_stages(task, dimension): prefix = ('黑片' if stage == 'black' else '亮片') if dimension in task.get('dimensionStages', {}) and stage else '' requirements.append(('quality_changes', dimension, stage, prefix + label)) if 'defect' in dimensions and task.get('defectScope', 'scope') in ('scope', 'both'): requirements.extend(('quality_fine_defects', 'defect', selected, ('黑片' if selected == 'black' else '亮片') + '来源具体缺陷') for selected in dimension_stages(task, 'defect')) return requirements stage = context.get('stage') if isinstance(context, dict) else None if stage not in ('black', 'bright'): stage = None if not _needs_broad_coverage(question): return ([('quality_changes', 'product', stage, '产品多维重点排序')] if _PRODUCT_PRIORITY.search(question if isinstance(question, str) else '') else []) stages = (stage,) if stage in ('black', 'bright') else ('black', 'bright') requirements = [ ('quality_changes', 'department', stage, '产业部变化'), ('quality_changes', 'group', stage, '业务分组变化'), ('quality_changes', 'product', stage, '产品多维重点排序'), ] requirements.extend(('quality_fine_defects', 'defect', selected, ('黑片' if selected == 'black' else '亮片') + '来源具体缺陷') for selected in stages) return requirements def _usable(rows: list[dict[str, Any]], kind: str, dimension: str) -> bool: if kind == 'quality_changes': return any(row.get('sort') in ('scrap_delta', 'current_scrap') for row in rows) if dimension == 'product' else bool(rows) return any(row.get('coverage', {}).get('available') is True and row.get('comparisonCoverage', {}).get('available') is True and row.get('category') is None and row.get('defect') is None for row in rows) def coverage_gaps(evidence: list[dict[str, Any]], question: str, context: Any = None) -> list[str]: """Return exact missing query dimensions; an unavailable source is not zero.""" gaps = [] from nao_agent_task import task_from_context task = task_from_context(context, question) if task is not None and task.get('trendRequired'): from nao_agent_report import _build_trend_report try: trend = _build_trend_report(evidence, context, question) if not trend.get('coverageSufficient'): gaps.extend(trend.get('missingEvidence') or ['缺少本轮同期间、同范围的正式月度趋势。']) except (KeyError, ValueError, TypeError): gaps.append('本轮月度趋势依据未通过范围或完整性核验。') if task is not None and task.get('period') and not task.get('comparisonPeriod') and not task.get('comparisonRequired'): return list(dict.fromkeys([*gaps, *semantic_single_period_gaps(evidence, task, context)])) if task is not None and task.get('comparisonRequired'): if _root(evidence, context) is None: gaps.append('尚无与本轮期间、范围一致的正式比较,不能判断变化。') formal = formal_metric_coverage(evidence, question, context) if formal: gaps.extend(formal['missingEvidence']) root = _root(evidence, context) if task is not None and 'defect' in task.get('dimensions', []) and task.get('defectScope') in ('products', 'both'): products = {} if root is not None: parent = _filters(root.get('filterBinding')) from nao_agent_task import dimension_stages stages = dimension_stages(task, 'defect') for document in evidence: result = document.get('result', {}) filters = _filters(result.get('filters')) product = filters.pop('product', None) if (not product or 'product' in parent or filters != parent or result.get('kind') != 'quality_fine_defects' or result.get('dimension') != 'defect' or result.get('releaseId') != root.get('releaseId') or not _same_periods(result, root) or not _usable([result], 'quality_fine_defects', 'defect')): continue products.setdefault(product, set()).add(result.get('stage')) complete = sum(set(stages) <= actual for actual in products.values()) else: complete = 0 required = task.get('defectProductCount', 0) if complete < required: gaps.append(f'重点规格具体缺陷证据尚未覆盖要求的{required}项及对应阶段,当前完成{complete}项。') if _requirements(evidence, question, context): if root is None: gaps.append('缺少同期间、同范围的正式比较,无法完成分析。') else: for kind, dimension, stage, label in _requirements(evidence, question, context): rows = _matching(evidence, root, kind, dimension=dimension, stage=stage) if not _usable(rows, kind, dimension): gaps.append(f'未取得同期间、同范围的{label}证据。') for args in plan_missing_product_defect_stages(evidence, question, context): stage = '黑片' if args['stage'] == 'black' else '亮片' product = args['filters']['product'] gaps.append(f'规格{product}缺少同期间、同范围的{stage}具体缺陷证据。') return list(dict.fromkeys(gaps)) def semantic_single_period_gaps(evidence, task, context): """A single-period question is not forced into a two-period analysis.""" from nao_weight_ranking import ranking_task, ranking_gaps if ranking_task(task): return ranking_gaps(evidence,task,context) matches = [] expected = _filters(task['filters']) for document in evidence: result = document.get('result', {}) if context.get('releaseId') and result.get('releaseId') != context['releaseId']: continue filters = result.get('filterBinding') if result.get('kind') == 'quality_comparison' else result.get('filters') period = (result.get('current') or {}).get('period') if result.get('kind') == 'quality_comparison' else result.get('period') if _filters(filters) != expected or not _period_equal(period, task['period']): continue matches.append(result) gaps = [] if not matches and task.get('freshQuery') and task['kind'] not in ('source_verify', 'details'): gaps.append('未取得本轮指定期间、范围的正式统计。') from nao_agent_task import dimension_stages for dimension in task.get('dimensions', []): for stage in dimension_stages(task, dimension): candidates = [r for r in matches if (r.get('dimension') == dimension or r.get('view') == dimension) and (r.get('stage') == stage if dimension in task.get('dimensionStages', {}) or stage is not None else True)] if dimension == 'defect': from nao_defect_report import matching_single_defects candidates = [doc['result'] for doc in matching_single_defects(evidence, task, context) if doc['result'].get('stage') == stage] if not candidates: gaps.append(f'未取得本轮指定期间、范围的{dimension}统计。') return gaps def semantic_metric_gaps(evidence, question, context): """Verify single/quarter/overall metric requests against formal snapshots.""" from nao_agent_task import task_from_context from nao_evidence_report import _filters, number from nao_quality_tools import (_valid_composite_rate_reference, _valid_stage_period_coverage, _valid_stage_rate_reference, _valid_stage_scrap_rate_reference) task = task_from_context(context, question) if task is None or task['kind'] != 'metrics': return [] snapshots = [] for document in evidence: result = document.get('result', {}) if context.get('releaseId') and result.get('releaseId') != context['releaseId']: continue filters = result.get('filterBinding') if result.get('kind') == 'quality_comparison' else result.get('filters') if _filters(filters) != _filters(task['filters']): continue if result.get('kind') == 'quality_comparison': snapshots.extend(result.get(side, {}) for side in ('current', 'comparison')) elif result.get('kind') == 'quality_metrics' and isinstance(result.get('summary'), dict): snapshots.append({**result['summary'], 'period': result.get('period'), 'coverage': result.get('coverage')}) periods = [task[key] for key in ('period', 'comparisonPeriod') if task.get(key)] if not periods: # The model may resolve an omitted period from the actual data catalog. periods = [s['period'] for s in snapshots if isinstance(s.get('period'), dict)] if len({str(p) for p in periods}) > 1: return ['未明确绑定本轮指标的业务期间。'] periods = periods[:1] if not periods: return ['未取得本轮指标的正式数据。'] gaps = [] for period in periods: found = [s for s in snapshots if _period_equal(s.get('period'), period)] for field in task['fields'] or ['rate']: selected_stages = task['stages'] or (['black', 'bright'] if field == 'scrapRate' else [None]) for stage in selected_stages: def covered(snapshot): if stage is None and field == 'rate': return _valid_composite_rate_reference(snapshot, period)[0] if stage is None: return False # No invented combined black/bright input denominator. if field == 'rate': return _valid_stage_rate_reference(snapshot, period, stage)[0] if field == 'scrapRate': return _valid_stage_scrap_rate_reference(snapshot, period, stage)[0] if not _valid_stage_period_coverage(snapshot, period, stage)[0]: return False value = (snapshot.get(stage) or {}).get(field) numeric = number(value) return numeric is not None and not (field == 'scrapWeight' and numeric < 0) if not any(covered(snapshot) for snapshot in found): stage_label = {'black': '黑片', 'bright': '亮片'}.get( stage, '各阶段' if field == 'scrapRate' else '综合') field_label = _FORMAL_FIELDS.get(field, field) gaps.append(f'未取得指定期间、范围的{stage_label}{field_label}正式指标或来源覆盖。') return gaps def plan_missing_source_queries(evidence: list[dict[str, Any]], task: dict[str, Any], context: Any = None) -> list[dict[str, Any]]: """Complete explicitly requested source checks in the exact parent frame.""" if not task.get('verifySource'): return [] from nao_evidence_finalizer import (_task_read_frame, _task_investigation_matches, _task_side_matches, _source_proof_complete) frame = _task_read_frame(evidence, task, context) if frame is None: return [] stages = task.get('stages') or ['black', 'bright'] if any(stage not in ('black', 'bright') for stage in stages): return [] sides = ('current', 'comparison') if frame['comparisonPeriod'] is not None else ('current',) planned = [] for stage in dict.fromkeys(stages): found = {side:False for side in sides} for document in evidence: if not isinstance(document, dict): continue result = document.get('result') if (document.get('mode') != 'investigate' or not _task_investigation_matches(result, frame, stage) or result.get('action') != 'source'): continue for side in sides: period = frame['currentPeriod'] if side == 'current' else frame['comparisonPeriod'] if _task_side_matches(result.get(side), frame, stage, period) and _source_proof_complete(result.get(side)): found[side] = True if all(found.values()): continue query = {'mode':'investigate','action':'source','releaseId':frame['releaseId'], 'period':frame['currentPeriod'],'filters':frame['filters'], 'stage':stage,'limit':100} if frame['comparisonPeriod'] is not None: query['comparisonPeriod'] = frame['comparisonPeriod'] planned.append(query) return planned def _missing_trend_query(evidence: list[dict[str, Any]], question: str, context: Any = None) -> list[dict[str, Any]]: """Query a missing trend only in the model-resolved, authorized exact frame.""" from nao_agent_task import task_from_context task = task_from_context(context, question) if not task or not task.get('trendRequired') or task.get('needsClarification'): return [] period = task.get('period') release = context.get('releaseId') if isinstance(context, dict) else None filters = task.get('filters') try: period = normalize_period(period) except ValueError: return [] if (period is None or 'month' in period or not isinstance(release, str) or not release.strip() or not isinstance(filters, dict)): return [] allowed = {'department', 'group', 'product', 'projectGroup', 'extraFilters', 'includeUnassigned'} if set(filters) - allowed: return [] # Never silently drop an exclusion or another unsupported selector. for document in evidence: if not isinstance(document, dict) or document.get('mode') != 'query': continue result = document.get('result') if (isinstance(result, dict) and result.get('kind') == 'quality_metrics' and result.get('releaseId') == release and result.get('period') == period and result.get('view') == 'overall' and _filters(result.get('filters')) == _filters(filters)): return [] # Existing unavailable/truncated results are not repaired by guessing or looping. return [{'mode': 'query', 'releaseId': release, 'period': dict(period), 'filters': dict(filters), 'view': 'overall'}] def plan_missing_queries(evidence: list[dict[str, Any]], question: str, context: Any = None) -> list[dict[str, Any]]: """Plan only missing broad-analysis reads. Product-stage pairing has its own guard.""" trend_queries = _missing_trend_query(evidence, question, context) root = _root(evidence, context) if root is None: return trend_queries period = (root.get('current') or {}).get('period') comparison = (root.get('comparison') or {}).get('period') release = root.get('releaseId') if not isinstance(period, dict) or not isinstance(comparison, dict) or not isinstance(release, str): return trend_queries allowed = ('department', 'group', 'product', 'projectGroup', 'extraFilters', 'includeUnassigned') filters = {key: value for key, value in (root.get('filterBinding') or {}).items() if key in allowed} planned = list(trend_queries) for kind, dimension, stage, _ in _requirements(evidence, question, context): rows = _matching(evidence, root, kind, dimension=dimension, stage=stage) if _usable(rows, kind, dimension) or rows and kind == 'quality_fine_defects': continue # A source reported unavailable; requerying cannot invent coverage. common = {'releaseId': release, 'period': period, 'comparisonPeriod': comparison, 'filters': filters} if kind == 'quality_changes': planned.append({'mode': 'changes', **common, 'dimension': dimension, **({'stage': stage} if stage else {}), 'sort': 'scrap_delta', 'limit': 100 if dimension in ('department', 'group') else 20}) else: planned.append({'mode': 'defects', **common, 'dimension': 'defect', 'stage': stage, 'sort': 'current_scrap', 'limit': 20}) return planned