experiment-core 0.1.0__py3-none-any.whl

experiment_core/__init__.py

@@ -0,0 +1,8 @@
+"""Domain-neutral contracts and an explicit local reference runtime.
+
+Runtime components are imported from their documented modules. Importing this
+package does not create stores, register applications or contact any service.
+"""
+from experiment_core.validation import ContractError, schema, validate_message
+
+__all__ = ["ContractError", "schema", "validate_message"]

experiment_core/adjustment_guidance.py

@@ -0,0 +1,49 @@
+"""Advisory proposal sizes; never physical limits or execution authority."""
+from copy import deepcopy
+import math
+
+from experiment_core.records import digest, safe_id
+
+
+def validate(value):
+    if (not isinstance(value, dict) or set(value) != {'schema_version', 'knobs'}
+            or type(value['schema_version']) is not int or value['schema_version'] != 1
+            or not isinstance(value['knobs'], dict) or len(value['knobs']) > 128):
+        raise ValueError('Expected versioned per-knob adjustment guidance')
+    for name, item in value['knobs'].items():
+        safe_id(name)
+        if not isinstance(item, dict) or set(item) != {'kind', 'step', 'unit', 'reason'}:
+            raise ValueError('Guidance requires kind, step, unit and reason')
+        if item['kind'] not in ('absolute', 'relative'):
+            raise ValueError('Guidance kind must be absolute or relative')
+        if type(item['step']) not in (int, float) or not math.isfinite(item['step']) or item['step'] <= 0:
+            raise ValueError('Suggested step must be positive and finite')
+        for key, maximum in (('unit', 64), ('reason', 1024)):
+            text = item[key]
+            if (not isinstance(text, str) or not text.strip() or len(text.encode()) > maximum
+                    or any(ord(c) < 32 or ord(c) == 127 for c in text)):
+                raise ValueError('Invalid guidance '+key)
+        if item['kind'] == 'relative' and item['unit'] != 'fraction':
+            raise ValueError('Relative advice uses a dimensionless fraction of the current magnitude')
+    return deepcopy(value)
+
+
+def snapshot(value):
+    value = validate(value)
+    return dict(document=value, revision=digest(value), advisory_only=True,
+                interpretation='An initial proposal size, not a minimum, maximum, safety limit or permission')
+
+
+def instructions():
+    return ('Per-knob adjustment_guidance is advisory, not an execution bound. Start a local comparison '
+            'near the suggested initial step when it is appropriate to the current evidence. An absolute '
+            'step uses the stated physical unit; a relative step is a fraction of the magnitude of the '
+            'current parameter, not of its allowed range. Relative advice at zero does not define a step. '
+            'Use previous comparable responses, sensitivity, resolution, drift and recovery cost to choose '
+            'a smaller or larger step, and explain deviations in the decision reason. A permitted excursion '
+            'is not a recommended trial step: never select half the allowed span merely because it is allowed. '
+            'Characterization mode does not remove this distinction. Enlarge only when observations support '
+            'it; reduce after a large response or loss of the branch. Missing guidance means unknown, not '
+            'permission to use the range endpoint. Read current adjustment guidance before planning a new knob '
+            'trial if no current guidance snapshot was supplied. Advice alone never changes output, supported '
+            'capabilities, approved envelopes, physical limits, freshness requirements or foreground priority.')

experiment_core/agent_contracts.py

@@ -0,0 +1,200 @@
+"""Provider-neutral, versioned agent execution and evidence contracts.
+
+Profiles select computation, never physical authority. Bundles retain provenance
+without copying an entire conversation or silently truncating required evidence.
+"""
+import copy
+import hashlib
+import math
+
+from experiment_core.records import canonical_json, digest, safe_id
+
+
+def text(value, name, limit=512, *, empty=False):
+    if (not isinstance(value, str) or (not value and not empty)
+            or len(value.encode()) > limit or any(ord(c) < 32 or ord(c)==127 for c in value)):
+        raise ValueError('Invalid ' + name)
+    return value
+
+
+def positive(value, name, maximum):
+    if type(value) not in (float, int) or not math.isfinite(value) or not 0 < value <= maximum:
+        raise ValueError('Invalid ' + name)
+    return value
+
+
+def execution_profile(value):
+    if not isinstance(value, dict):
+        raise ValueError('Execution profile must be a mapping')
+    defaults = dict(effort='', required_tools=[], required_modalities=['text'],
+                    timeout_s=600., max_turns=8, max_input_bytes=32000)
+    if set(value) - {'provider', 'model', *defaults} or not {'provider', 'model'} <= value.keys():
+        raise ValueError('Profile requires provider/model and supported execution fields')
+    p = {**defaults, **copy.deepcopy(value)}
+    safe_id(p['provider'])
+    text(p['model'], 'exact model identifier')
+    text(p['effort'], 'effort', 80, empty=True)
+    positive(p['timeout_s'], 'task timeout', 86400)
+    for key, maximum in (('max_turns', 100), ('max_input_bytes', 262144)):
+        if type(p[key]) is not int or not 1 <= p[key] <= maximum:
+            raise ValueError('Invalid ' + key)
+    for key in ('required_tools', 'required_modalities'):
+        if (not isinstance(p[key], list) or len(p[key]) > 128 or any(not isinstance(v,str) for v in p[key])
+                or len(set(p[key])) != len(p[key])):
+            raise ValueError('Invalid ' + key)
+        for item in p[key]:
+            safe_id(item)
+    if set(p['required_modalities']) - {'text', 'image'}:
+        raise ValueError('Unsupported required modality')
+    return p
+
+
+DIFFICULTIES = ('basic', 'standard', 'deep')
+
+
+def difficulty_profile(matrix, provider, difficulty):
+    """Resolve an explicit routing table. Profile names carry no semantics."""
+    if difficulty not in DIFFICULTIES:
+        raise ValueError('Unknown task difficulty')
+    name = matrix.get(provider, {}).get(difficulty)
+    if not name:
+        raise ValueError('No profile for provider/difficulty: ' + provider + '/' + difficulty)
+    safe_id(name)
+    return name
+
+
+def execution_policy(value=None):
+    defaults = dict(mode='resident', task_profile='', escalation_profiles=[], provider_profiles={}, difficulty='')
+    if value is None:
+        return defaults
+    if not isinstance(value, dict) or set(value) - set(defaults):
+        raise ValueError('Invalid agent execution policy')
+    p = {**defaults, **copy.deepcopy(value)}
+    if p['mode'] not in ('resident', 'on_request', 'required'):
+        raise ValueError('Invalid agent execution mode')
+    if p['task_profile']:
+        safe_id(p['task_profile'])
+    if not isinstance(p['provider_profiles'], dict) or len(p['provider_profiles']) > 16:
+        raise ValueError('Invalid provider profiles')
+    for provider, profile in p['provider_profiles'].items():
+        safe_id(provider); safe_id(profile)
+    if p['difficulty'] not in ('', 'default', *DIFFICULTIES):
+        raise ValueError('Invalid card difficulty')
+    if sum(bool(p[k]) for k in ('provider_profiles', 'task_profile', 'difficulty')) > 1:
+        raise ValueError('Choose difficulty routing, inherited provider profiles or a fixed task profile')
+    if p['mode'] == 'required' and not (p['task_profile'] or p['provider_profiles'] or p['difficulty']):
+        raise ValueError('Required delegation needs a task profile')
+    if not isinstance(p['escalation_profiles'], list) or len(p['escalation_profiles']) > 32:
+        raise ValueError('Invalid escalation profiles')
+    for item in p['escalation_profiles']:
+        safe_id(item)
+    return p
+
+
+def choose_profile(policy, *, requested=False, override='', provider='', matrix=None, default_difficulty='standard'):
+    p = execution_policy(policy)
+    if p['mode'] == 'resident':
+        if override:
+            raise ValueError('This card does not allow delegation')
+        return None
+    if p['mode'] == 'on_request' and not requested:
+        return None
+    if p['difficulty']:
+        matrix = matrix or {}
+        if override:
+            allowed = {name for levels in matrix.values() for name in levels.values()} | set(p['escalation_profiles'])
+            if override not in allowed:
+                raise ValueError('Requested profile is not allowed by this card routing table')
+            return override
+        return difficulty_profile(matrix, provider, default_difficulty if p['difficulty']=='default' else p['difficulty'])
+    if not override and p['provider_profiles'] and provider not in p['provider_profiles']:
+        raise ValueError('No card task profile for the selected gateway provider: ' + (provider or 'unresolved'))
+    chosen = override or p['provider_profiles'].get(provider) or p['task_profile']
+    if not chosen or chosen not in [p['task_profile'], *p['provider_profiles'].values(), *p['escalation_profiles']]:
+        raise ValueError('Requested profile is not allowed by this card')
+    return chosen
+
+
+def instruction_bundle(common, task, *, revision, context, evidence, max_input_bytes=32000):
+    """Fixed UTF-8 policy bytes plus bounded, separately hashed run evidence."""
+    instructions = common + b'\n\n' + task
+    instructions.decode('utf-8')
+    data = dict(context=copy.deepcopy(context), evidence=copy.deepcopy(evidence))
+    encoded = canonical_json(data).encode()
+    if len(encoded) > max_input_bytes:
+        raise ValueError('Task context exceeds its budget; select evidence or use artifact references')
+    return dict(schema_version=1, instruction_revision=revision,
+                instructions=instructions.decode(), instructions_sha256=hashlib.sha256(instructions).hexdigest(),
+                instructions_bytes=len(instructions), input=data, input_sha256=digest(data),
+                input_bytes=len(encoded), full_history_included=False)
+
+
+class Conditions:
+    """Persistable change detector: distinct fresh acquisitions, hysteresis and cooldown.
+
+    Missing/invalid data never clears an unresolved degradation or counts as a
+    new observation. The caller persists returned state, not a model conversation.
+    """
+    def __init__(self, rules, state=None):
+        self.rules = self.validate(rules)
+        self.state = copy.deepcopy(state or {})
+
+    @staticmethod
+    def validate(rules):
+        if not isinstance(rules, list) or len(rules) > 32:
+            raise ValueError('Expected at most 32 monitor conditions')
+        ids = set()
+        for rule in rules:
+            required = {'id', 'metric', 'above', 'clear_below', 'persistence_s', 'cooldown_s', 'max_age_s'}
+            if not isinstance(rule, dict) or not required <= set(rule) <= required | {'baseline','repeat_s'}:
+                raise ValueError('Invalid monitor condition fields')
+            safe_id(rule['id']); text(rule['metric'], 'metric', 160)
+            if rule['id'] in ids:
+                raise ValueError('Duplicate monitor condition')
+            ids.add(rule['id'])
+            for name in ('above', 'clear_below', 'persistence_s', 'cooldown_s', 'max_age_s'):
+                v = rule[name]
+                if type(v) not in (int, float) or not math.isfinite(v):
+                    raise ValueError('Monitor thresholds must be finite')
+            if (rule['clear_below'] > rule['above'] or rule['persistence_s'] < 0
+                    or rule['cooldown_s'] < 0 or rule['max_age_s'] <= 0):
+                raise ValueError('Invalid monitor hysteresis/timing')
+            if 'repeat_s' in rule and (type(rule['repeat_s']) not in (int,float) or not math.isfinite(rule['repeat_s']) or rule['repeat_s']<=0):
+                raise ValueError('Monitor repeat interval must be finite and positive')
+            if 'baseline' in rule and (type(rule['baseline']) not in (int, float)
+                    or not math.isfinite(rule['baseline']) or rule['baseline'] == 0):
+                raise ValueError('Relative-change baseline must be finite and nonzero')
+        return copy.deepcopy(rules)
+
+    def observe(self, metrics, now):
+        events = []
+        for rule in self.rules:
+            old = self.state.setdefault(rule['id'], {})
+            if old.get('rule') != digest(rule):
+                old.clear(); old['rule'] = digest(rule)
+            sample = metrics.get(rule['metric'], {})
+            value, timestamp = sample.get('value'), sample.get('acquired_unix_s')
+            if (sample.get('valid') is not True or type(value) not in (int, float)
+                    or type(timestamp) not in (int, float) or not math.isfinite(value)
+                    or not math.isfinite(timestamp) or not 0 <= now - timestamp <= rule['max_age_s']):
+                old.pop('since', None)
+                continue
+            if timestamp <= old.get('last_sample', -math.inf):
+                continue
+            if 'baseline' in rule:
+                value = abs(value-rule['baseline'])/abs(rule['baseline'])
+            if timestamp - old.get('last_sample', timestamp) > rule['max_age_s']:
+                old.pop('since', None)
+            old['last_sample'] = timestamp
+            if value <= rule['clear_below']:
+                old.pop('since', None); old['active'] = False
+            elif value > rule['above']:
+                old.setdefault('since', timestamp)
+                repeated=bool(old.get('active'))
+                due=not repeated or ('repeat_s' in rule and now-old.get('last_event',-math.inf)>=rule['repeat_s'])
+                if (due and timestamp - old['since'] >= rule['persistence_s']
+                        and now - old.get('last_event', -math.inf) >= rule['cooldown_s']):
+                    old.update(active=True, last_event=now)
+                    events.append(dict(condition=rule['id'], metric=rule['metric'], value=value,
+                                       acquired_unix_s=timestamp, rule_revision=digest(rule), repeated=repeated))
+        return events

experiment_core/agent_roles.py

@@ -0,0 +1,135 @@
+"""Domain-neutral gateway/task relationships and result authorship.
+
+Roles select responsibilities, not model price, provider, intelligence or physical
+authority. A gateway is a communication parent; its liveness is not a task lease.
+Domain hosts own permissions, evidence evaluation and effectful adoption.
+"""
+import copy
+import math
+
+from experiment_core.agent_contracts import execution_profile, text
+from experiment_core.records import safe_id
+
+VERSION = 'experiment.agent-roles/1'
+ROLES = frozenset(('gateway', 'task'))
+ADOPTION_MODES = frozenset(('report_only', 'human_confirmation', 'auto_within_approved'))
+RESPONSIBILITIES = {
+    'gateway': ('receive_requests', 'dispatch_cards', 'inspect_progress', 'request_cancellation', 'relay_authored_results'),
+    'task': ('evaluate_evidence', 'propose_next_step', 'evaluate_outcome', 'author_explanation'),
+}
+ROLE_INSTRUCTIONS = {
+    'gateway': '''You are the conversation and card-dispatch gateway.
+Handle requests to start, cancel or inspect registered operations, manage task
+requests, and relay task-authored results with their author attribution.
+Delegate domain analysis, optimization and explanations to the card task agent.
+Unless the human explicitly selects another execution profile, omit the profile
+override: inherit this gateway interface and use the card model/effort mapping.
+Do not copy a provider or model from conversation history as a new override.
+Do not replace its judgment or silently rewrite its final explanation. If an
+explanation is unavailable, report that fact and preserve the recorded outcome.
+A gateway disconnect does not cancel, replay or transfer an admitted task.
+Model selection changes computation, never permissions or physical authority.''',
+    'task': '''You are an ordinary card task agent, including when the card is
+monitoring, diagnosis or adjustment. Evaluate the supplied evidence, propose the
+next permitted step, evaluate the outcome and author the final explanation from
+host-confirmed results. The gateway is a communication endpoint, not an extra
+scientific decision maker. Preserve the task's budget and authority boundaries;
+do not infer approval from your model, role, parent or another agent's message.''',
+}
+
+
+def role_contract(role):
+    """Responsibilities are independent of provider, cost, effort and lifetime."""
+    if not isinstance(role, str) or role not in ROLES:
+        raise ValueError('Unknown agent role')
+    return dict(schema=VERSION, role=role, responsibilities=list(RESPONSIBILITIES[role]),
+                instructions=ROLE_INSTRUCTIONS[role])
+
+
+def assignment(role, profile):
+    """Pin explicit computation settings without imposing a role-specific model."""
+    return dict(**role_contract(role), profile=profile_snapshot(profile))
+
+
+def profile_snapshot(profile):
+    """Normalize computation plus optional registry provenance, without lookup."""
+    if not isinstance(profile, dict):
+        raise ValueError('Expected execution profile')
+    provenance = {k: profile[k] for k in ('id', 'registry_revision', 'profile_revision') if k in profile}
+    for key, value in provenance.items():
+        if key == 'id':
+            safe_id(value)
+        else:
+            text(value, key, 160)
+    computation = execution_profile({k: v for k, v in profile.items() if k not in provenance})
+    return {**provenance, **computation}
+
+
+def relationship(task_id, *, gateway_id=None, parent_session=None, profile=None,
+                 purpose='card_execution'):
+    safe_id(task_id)
+    if gateway_id is not None:
+        safe_id(gateway_id)
+        if gateway_id == task_id:
+            raise ValueError('A task cannot be its own gateway')
+    # Purpose is a registered host label, not another privileged agent role.
+    safe_id(purpose)
+    if parent_session is not None:
+        text(parent_session, 'parent session', 512)
+    if profile is not None:
+        profile = profile_snapshot(profile)
+    return dict(schema=VERSION, role='task', task_id=task_id, gateway_id=gateway_id,
+        parent_session=parent_session, purpose=purpose, profile=copy.deepcopy(profile),
+        gateway_liveness_required=False, decision_source_count=1, delegation_depth=1,
+        explanation_author='task', physical_authority='domain_host_grant_only')
+
+
+def adoption_mode(value):
+    if not isinstance(value, str) or value not in ADOPTION_MODES:
+        raise ValueError('Unknown adoption mode')
+    return value
+
+
+def adoption_disposition(mode, *, verified, within_approved_scope, requires_human=False):
+    """Resolve eligibility; this grants no authority and performs no effects."""
+    adoption_mode(mode)
+    if any(type(v) is not bool for v in (verified, within_approved_scope, requires_human)):
+        raise ValueError('Adoption evidence must use explicit host booleans')
+    if not verified:
+        return 'unverified'
+    if mode == 'report_only':
+        return 'proposal_only'
+    if mode == 'human_confirmation' or requires_human or not within_approved_scope:
+        return 'awaiting_human'
+    return 'eligible_for_host_adoption'
+
+
+def explanation(text, *, task_id, session, profile, model_info):
+    safe_id(task_id)
+    if not isinstance(text, str) or not text.strip():
+        raise ValueError('Task explanation must be nonempty text')
+    profile = profile_snapshot(profile)
+    if not isinstance(session, str) or not session:
+        raise ValueError('Task explanation requires its author session')
+    if not isinstance(model_info, dict):
+        raise ValueError('Task explanation requires normalized adapter attestation')
+    if (model_info.get('confirmation') != 'server_reported' or
+            model_info.get('resolved_model') != profile.get('model') or
+            (profile.get('effort') and model_info.get('resolved_effort') != profile['effort'])):
+        raise ValueError('Explanation author profile is unconfirmed')
+    return dict(schema=VERSION, status='completed', text=text, task_id=task_id,
+        author=dict(role='task', profile=copy.deepcopy(profile), session=session,
+                    model_info=copy.deepcopy(model_info)), relay='verbatim')
+
+
+def explanation_unavailable(error):
+    return dict(schema=VERSION, status='unavailable', error_type=type(error).__name__,
+        reason=str(error), relay='no_gateway_substitution')
+
+
+def decision_deadline(task_deadline, decision_deadline):
+    """Delegation never extends a card's admitted computation deadline."""
+    if any(type(v) not in (int, float) or not math.isfinite(v)
+           for v in (task_deadline, decision_deadline)):
+        raise ValueError('Decision deadlines must be finite monotonic times')
+    return min(task_deadline, decision_deadline)

experiment_core/background.py

@@ -0,0 +1,98 @@
+"""Owner-serialized background epochs and foreground generation fencing.
+
+This coordinator performs no I/O or device writes. The application owner must
+hold its existing dispatch mutex, persist checkpoint/intent records, and prove
+restoration before calling ``complete``. A timeout never grants a handoff.
+"""
+from copy import deepcopy
+import math
+import uuid
+
+from experiment_core.errors import Conflict, StaleContext
+
+
+class BackgroundCoordinator:
+    def __init__(self, clock):
+        self.clock = clock
+        self.generation = 0
+        self.reservations = set()
+        self.epoch = None
+        self.last = None
+
+    def status(self):
+        return dict(generation=self.generation, reservations=sorted(self.reservations),
+                    epoch=deepcopy(self.epoch), last=deepcopy(self.last),
+                    foreground_ready=self.epoch is None)
+
+    def reserve(self, identifiers):
+        identifiers = set(identifiers)
+        if any(not isinstance(value, str) or not value or len(value) > 256 for value in identifiers):
+            raise ValueError('Bounded foreground request identities are required')
+        if identifiers - self.reservations:
+            self.generation += 1
+            if self.epoch:
+                self.returning('foreground', requested_at=self.clock())
+        self.reservations |= identifiers
+        return self.status()
+
+    def release(self, identifiers):
+        self.reservations -= set(identifiers)
+        return self.status()
+
+    def begin(self, expected_generation, context, checkpoint, timeout_s, identity, *, completion_mode="deadline"):
+        if completion_mode not in ("deadline", "verified_handover"):
+            raise ValueError("Unknown handoff completion mode")
+        if completion_mode == "verified_handover" and timeout_s is not None:
+            raise ValueError("Verified handover has no optical restoration deadline")
+        if completion_mode == 'deadline' and (type(timeout_s) not in (int, float) or not math.isfinite(timeout_s)
+                or not 0 < timeout_s <= 600):
+            raise ValueError('An explicit handoff deadline within 600 s is required')
+        if self.epoch or self.reservations:
+            raise Conflict('A foreground reservation or background epoch is active')
+        if expected_generation != self.generation:
+            raise StaleContext('Foreground generation changed')
+        self.epoch = dict(token=uuid.uuid4().hex, generation=self.generation,
+                          context=deepcopy(context), checkpoint=deepcopy(checkpoint),
+                          identity=deepcopy(identity), timeout_s=timeout_s, completion_mode=completion_mode,
+                          state='active', started_at=self.clock())
+        return deepcopy(self.epoch)
+
+    def validate(self, token, context, *, restoring=False):
+        epoch = self.epoch
+        if epoch is None or token != epoch['token']:
+            raise StaleContext('Background epoch is absent or replaced')
+        if context != epoch['context']:
+            self.block('Owner, policy, target or branch changed')
+            raise StaleContext('Background checkpoint context changed')
+        if epoch['state'] == 'reconciliation_required':
+            raise Conflict(epoch['reason'])
+        if not restoring and (epoch['state'] != 'active' or epoch['generation'] != self.generation
+                              or self.reservations):
+            raise StaleContext('Background proposals are fenced by foreground activity')
+        if restoring and self.clock() > epoch.get('return_deadline', math.inf):
+            self.block('Checkpoint restoration deadline exceeded')
+            raise Conflict('Checkpoint restoration deadline exceeded')
+        return deepcopy(epoch)
+
+    def returning(self, reason, *, requested_at=None):
+        if self.epoch and self.epoch['state'] == 'active':
+            now = self.clock()
+            self.epoch.update(state='returning', reason=reason, return_started_at=now,
+                              requested_at=now if requested_at is None else requested_at)
+            if self.epoch.get('completion_mode') != 'verified_handover':
+                self.epoch['return_deadline'] = now + self.epoch['timeout_s']
+        return self.status()
+
+    def block(self, reason):
+        if self.epoch:
+            self.epoch.update(state='reconciliation_required', reason=str(reason))
+        return self.status()
+
+    def complete(self, token, context, receipt, *, adopted=False):
+        epoch = self.validate(token, context, restoring=not adopted)
+        if receipt.get('confirmed') is not True or receipt.get('response_ended') is not True:
+            raise Conflict('Confirmed readback and response cleanup are required')
+        self.last = dict(epoch, state='adopted' if adopted else 'restored',
+                         completed_at=self.clock(), receipt=deepcopy(receipt))
+        self.epoch = None
+        return self.status()