Download platform/core/amazon_project_results.py from fsanyoto/loopable: direct link, hf CLI and curl.
- Browser
- Download file 12.7 kB
-
https://huggingface.co/spaces/fsanyoto/loopable/resolve/main/platform/core/amazon_project_results.py
- Command line
-
hf download hf://spaces/fsanyoto/loopable/platform/core/amazon_project_results.py
-
curl -L -o amazon_project_results.py https://huggingface.co/spaces/fsanyoto/loopable/resolve/main/platform/core/amazon_project_results.py
12.7 kB
| """Typed project results and daily series with independent source reconciliation.""" | |
| from datetime import date, timedelta | |
| import hashlib | |
| import json | |
| import math | |
| import re | |
| import uuid | |
| from core import periods | |
| METRICS = ('sales', 'units', 'returns', 'return_rate', 'refund_rate', 'roas') | |
| GRAINS = ('sku', 'asin', 'parent_asin') | |
| MAX_CONFIGS = 20 | |
| BOUNDARY = '[completedOn, endExclusive) in the tenant timezone. Today is excluded.' | |
| SERIES_METRICS = ( | |
| ('sales', 'Sales', 'currency'), ('units', 'Units', 'units'), | |
| ('margin', 'Margin', 'percent'), ('returns', 'Returns', 'units'), | |
| ('returns_pct', 'Returns %', 'percent'), ('refunds_pct', 'Refunds %', 'percent'), | |
| ('roas', 'ROAS', 'ratio'), ('sales_yoy', 'Sales YoY', 'percent'), | |
| ) | |
| SERIES_BOUNDARY = 'Inclusive requested dates in the tenant timezone. Today is incomplete and excluded from totals.' | |
| class ValidationFailed(RuntimeError): | |
| """A daily project series does not reconcile to its independent source aggregate.""" | |
| def series_scope(value='all'): | |
| """Parse the modal filter without allowing it to widen project membership.""" | |
| if value == 'all': | |
| return None | |
| if not isinstance(value, str) or ':' not in value: | |
| raise ValueError('scope must be all, sku:<keys>, asin:<key> or parent:<key>.') | |
| grain, text = value.split(':', 1) | |
| keys = [key.strip() for key in text.split(',')] | |
| if (grain not in ('sku', 'asin', 'parent') or not all(keys) | |
| or (grain != 'sku' and len(keys) != 1)): | |
| raise ValueError('scope must be all, sku:<keys>, asin:<key> or parent:<key>.') | |
| return {'grain': grain, 'keys': list(dict.fromkeys(keys))} | |
| def series_window(project, start=None, end=None, *, today=None): | |
| """Default to thirty days before start through today and aggregate only completed tenant days.""" | |
| today = today or periods.today() | |
| def parsed(value): | |
| if not isinstance(value, str) or not re.fullmatch(r'\d{4}-\d{2}-\d{2}', value): | |
| raise ValueError('Series dates must use YYYY-MM-DD.') | |
| return date.fromisoformat(value) | |
| first = (parsed(start) if start is not None else | |
| parsed(project.get('start_on') or today.isoformat()) - timedelta(days=30)) | |
| last = parsed(end) if end is not None else today | |
| if first > last or last > today: | |
| raise ValueError('Series dates must be ordered and cannot end after today.') | |
| stop = min(last + timedelta(days=1), today) | |
| lo, hi, rule = periods.yoy_window(first.isoformat(), stop.isoformat(), 'day') | |
| return {'from': first.isoformat(), 'to': last.isoformat(), 'days': (stop - first).days, | |
| 'current': (first, stop), 'comparison': (date.fromisoformat(lo), date.fromisoformat(hi)), | |
| 'compare_rule': rule} | |
| def _finite(value): | |
| return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) | |
| def validate(answer, *, independent): | |
| """Requery independent totals and return failing checks for any changed or unproved series.""" | |
| checks = [] | |
| first, last = date.fromisoformat(answer['from']), date.fromisoformat(answer['to']) | |
| dates = [(first + timedelta(days=i)).isoformat() for i in range((last - first).days + 1)] | |
| expected_keys = [key for key, _label, _unit in SERIES_METRICS] | |
| metrics = answer['metrics'] | |
| if [metric['key'] for metric in metrics] != expected_keys: | |
| return [{'check': 'series total ties to economics', 'ok': False, | |
| 'reason': 'Series metrics do not follow the project result contract.'}] | |
| for metric in metrics: | |
| ours = metric.get('total') | |
| source = independent(metric['key']) | |
| expected, source_reason = source['value'], source.get('reason') | |
| points = metric.get('points', []) | |
| ok = [point.get('date') for point in points] == dates | |
| if ours is None: | |
| ok = ok and bool(metric.get('reason')) and all(point.get('value') is None for point in points) | |
| else: | |
| ok = (ok and _finite(ours) and _finite(expected) | |
| and math.isclose(ours, expected, rel_tol=1e-9, abs_tol=1e-6) | |
| and all(point.get('value') is None or _finite(point['value']) for point in points)) | |
| if metric['key'] in ('sales', 'units', 'returns'): | |
| values = [point['value'] for point in points if point.get('value') is not None] | |
| ok = ok and bool(values) and math.isclose(math.fsum(values), ours, rel_tol=1e-9, abs_tol=1e-6) | |
| tie = metric.get('tie', {}) | |
| if tie.get('ok') or tie.get('ours') is not None or tie.get('independent') is not None: | |
| ok = (ok and ours is not None and tie.get('ok') is True | |
| and _finite(tie.get('ours')) and _finite(tie.get('independent')) | |
| and math.isclose(tie['ours'], ours, rel_tol=1e-9, abs_tol=1e-6) | |
| and _finite(expected) | |
| and math.isclose(tie['independent'], expected, rel_tol=1e-9, abs_tol=1e-6)) | |
| checks.append({'check': 'series total ties to economics', 'metric': metric['key'], 'ok': bool(ok), | |
| 'ours': ours, 'independent': expected, | |
| 'reason': metric.get('reason') or source_reason}) | |
| return checks | |
| def series(project, *, bounds, read, independent): | |
| """Publish the fixed chart order and project markers after independent economics reconciliation.""" | |
| first, last = date.fromisoformat(bounds['from']), date.fromisoformat(bounds['to']) | |
| dates = [(first + timedelta(days=i)).isoformat() for i in range((last - first).days + 1)] | |
| answer = {'projectId': project['id'], 'from': bounds['from'], 'to': bounds['to'], | |
| 'timezone': timezone_name(), 'boundary': SERIES_BOUNDARY, | |
| 'markers': {'start': project.get('start_on'), 'target': project.get('target_on'), | |
| 'completed': project.get('completed_on')}, 'metrics': []} | |
| for key, label, unit in SERIES_METRICS: | |
| measured = read(key) | |
| total, reason = measured.get('total'), measured.get('reason') | |
| if total is None and not reason: | |
| reason = 'An independent daily source for this metric is unavailable.' | |
| values = {point['date']: point['value'] for point in measured.get('points', [])} if total is not None else {} | |
| answer['metrics'].append({'key': key, 'label': label, 'unit': measured.get('unit', unit), | |
| 'points': [{'date': day, 'value': values.get(day)} for day in dates], | |
| 'total': total, 'reason': reason, | |
| 'tie': {'ok': False, 'ours': None, 'independent': None}}) | |
| checks = validate(answer, independent=independent) | |
| if any(not check['ok'] for check in checks): | |
| raise ValidationFailed('A series total does not tie to its independent Amazon economics aggregate.') | |
| for metric, check in zip(answer['metrics'], checks): | |
| if metric['total'] is not None: | |
| metric['tie'] = {'ok': True, 'ours': check['ours'], 'independent': check['independent']} | |
| return answer | |
| def configurations(values): | |
| """Normalize an ordered list of supported metrics without accepting executable expressions.""" | |
| if not isinstance(values, (list, tuple)) or len(values) > MAX_CONFIGS: | |
| raise ValueError(f'resultConfigs must be a list of at most {MAX_CONFIGS} configurations.') | |
| out, seen = [], set() | |
| for item in values: | |
| if not isinstance(item, dict) or set(item) - {'id', 'metric', 'grain', 'window', 'days', 'compare'}: | |
| raise ValueError('Each result configuration must contain only typed result fields.') | |
| identity = item.get('id', uuid.uuid4().hex) | |
| if (not isinstance(identity, str) or not re.fullmatch(r'[A-Za-z0-9_-]{1,64}', identity) | |
| or identity in seen): | |
| raise ValueError('Result configuration ids must be unique text identifiers.') | |
| metric, grain = item.get('metric'), item.get('grain', 'sku') | |
| window, compare = item.get('window', 'fixed'), item.get('compare', 'prior') | |
| days = item.get('days', 7) | |
| if metric not in METRICS or grain not in GRAINS: | |
| raise ValueError('Select a supported Amazon metric and target grain.') | |
| if window not in ('fixed', 'completion_to_now') or compare not in ('prior', 'yoy'): | |
| raise ValueError('Select a supported result window and comparison.') | |
| if type(days) is not int or not 1 <= days <= 366: | |
| raise ValueError('Result days must be a whole number from 1 to 366.') | |
| out.append(dict(id=identity, metric=metric, grain=grain, window=window, days=days, compare=compare)) | |
| seen.add(identity) | |
| return out | |
| def timezone_name(): | |
| """Return the effective tenant business timezone, including the shared UTC fallback.""" | |
| return getattr(periods._business_zone(), 'key', 'UTC') | |
| def windows(project, config, today=None): | |
| """Anchor equal comparison windows to completion and exclude the tenant's incomplete day.""" | |
| today = today or periods.today() | |
| base = {'state': 'waiting_for_completion', 'days': 0, 'boundary': BOUNDARY} | |
| if project.get('status') != 'Completed' or not project.get('completed_on'): | |
| return base | |
| start = date.fromisoformat(project['completed_on']) | |
| if start > today: | |
| raise ValueError('completedOn cannot be in the future.') | |
| if start == today: | |
| return {**base, 'state': 'waiting_for_completed_day'} | |
| end = today if config['window'] == 'completion_to_now' else start + timedelta(days=config['days']) | |
| if end > today: | |
| return {**base, 'state': 'waiting_for_window', 'availableDays': (today - start).days, | |
| 'requestedDays': config['days']} | |
| days = (end - start).days | |
| if config['compare'] == 'yoy': | |
| lo, hi, rule = periods.yoy_window(start.isoformat(), end.isoformat(), 'day') | |
| prior = (date.fromisoformat(lo), date.fromisoformat(hi)) | |
| else: | |
| prior, rule = (start - timedelta(days=days), start), None | |
| return {**base, 'state': 'ready', 'days': days, 'current': (start, end), 'comparison': prior, | |
| 'compare_rule': rule} | |
| def anchor(project, targets, today, zone): | |
| """Identify the complete completion, configuration, target and tenant-day input set.""" | |
| values = {'status': project['status'], 'completedOn': project.get('completed_on'), | |
| 'configs': project.get('result_configs', []), | |
| 'targets': sorted({(t['grain'], t['key']) for t in targets}), | |
| 'today': today.isoformat(), 'timezone': zone} | |
| return hashlib.sha256(json.dumps(values, sort_keys=True, separators=(',', ':')).encode()).hexdigest() | |
| def results(project, targets, *, read, metadata, today=None): | |
| """Publish reconciled figures only after deriving their current completion and target anchor.""" | |
| today, zone = today or periods.today(), timezone_name() | |
| out = {'projectId': project['id'], 'timezone': zone, 'boundary': BOUNDARY, | |
| 'anchor': anchor(project, targets, today, zone), 'results': []} | |
| for config in configurations(project.get('result_configs', [])): | |
| bounds = windows(project, config, today) | |
| entry = {'config': config, **metadata(config['metric']), 'state': bounds['state'], | |
| 'current': None, 'comparison': None, 'series': [], 'scope': None, | |
| 'delta': None, 'deltaPercent': None, 'reason': None, | |
| 'compare_rule': bounds.get('compare_rule')} | |
| if bounds['state'] == 'ready': | |
| figure = read(config, bounds) | |
| entry.update(figure) | |
| current, prior = figure.get('current'), figure.get('comparison') | |
| if current is not None and prior is not None: | |
| entry['series'] = current.get('series', []) | |
| states = [current['status'], prior['status']] | |
| entry['state'] = next((state for state in ('unavailable', 'no_prior_data', 'partial_data') | |
| if state in states), 'ready') | |
| entry['reason'] = current.get('reason') or prior.get('reason') | |
| if all(w.get('validated') and w.get('status') == 'available' for w in (current, prior)): | |
| a, b = current['value'], prior['value'] | |
| if a is not None and b is not None and all(math.isfinite(v) for v in (a, b)): | |
| change = a - b | |
| entry['delta'] = change if math.isfinite(change) else None | |
| percent = 100 * change / b if b > 0 else None | |
| entry['deltaPercent'] = percent if percent is not None and math.isfinite(percent) else None | |
| out['results'].append(entry) | |
| return out | |