From 9606d71df7523f47d8e81afa280b1ec18f9c3d1b Mon Sep 17 00:00:00 2001 From: agent-a6e6ec231c5f7801 Date: Mon, 20 Apr 2026 15:28:37 +0200 Subject: [PATCH] build(agent): new-agents#a6e6ec iteration --- .gitignore | 21 ++++++++++ AGENTS.md | 40 +++++++++++++++++++ README.md | 20 +++++++++- pyproject.toml | 13 +++++++ src/exprove/__init__.py | 20 ++++++++++ src/exprove/contracts.py | 76 +++++++++++++++++++++++++++++++++++++ src/exprove/engine.py | 58 ++++++++++++++++++++++++++++ test.sh | 11 ++++++ tests/test_exprove_basic.py | 51 +++++++++++++++++++++++++ 9 files changed, 308 insertions(+), 2 deletions(-) create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 pyproject.toml create mode 100644 src/exprove/__init__.py create mode 100644 src/exprove/contracts.py create mode 100644 src/exprove/engine.py create mode 100644 test.sh create mode 100644 tests/test_exprove_basic.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bd5590b --- /dev/null +++ b/.gitignore @@ -0,0 +1,21 @@ +node_modules/ +.npmrc +.env +.env.* +__tests__/ +coverage/ +.nyc_output/ +dist/ +build/ +.cache/ +*.log +.DS_Store +tmp/ +.tmp/ +__pycache__/ +*.pyc +.venv/ +venv/ +*.egg-info/ +.pytest_cache/ +READY_TO_PUBLISH diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3562cde --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,40 @@ +# ExProve SWARM Guidelines + +Architecture overview +- Canonical primitives form the Covariant IR for cross-venue execution provenance: + - LocalExecutionTask: per-instrument, per-venue planning unit + - SharedMarketContext: privacy-safe, versioned market signals + - PlanDelta: incremental routing/size/timing decisions with metadata + - Attestation/AuditLog: cryptographic attestations and append-only logs + - Graph-of-Contracts: adapters and data-contract schemas +- Edge-native solver: lightweight optimizer co-located with venue data to produce PlanDelta +- Delta-sync with deterministic replay for offline backtesting and regulatory review +- Governance ledger: cryptographic signing, policy hooks, optional cloud anchoring +- Adapters marketplace: plug-in venue adapters translating venue data into canonical IR + +MVP plan (8–12 weeks) +- Phase 0: Skeleton protocol, 2 starter adapters, toy objective (VWAP-like), deterministic delta-sync +- Phase 1: Governance scaffolding, identity management, secure aggregation for SharedMarketContext +- Phase 2: Cross-venue demo in simulated env; publish ExProve SDK and minimal contract example +- Phase 3: Backtesting harness and deterministic replay; compliance-report generator + +Deliverables +- Core data contracts: LocalExecutionTask, SharedMarketContext, PlanDelta, Attestation, AuditLog, Graph-of-Contracts +- Toy adapters (2 starters) and conformance harness +- Seed DSL for LocalExecutionTask/SharedMarketContext/PlanDelta +- Reference ExProve SDK (Python/C++ bindings) and transport layer + +Testing and QA +- Lightweight conformance harness and toy adapters (end-to-end replay tests) +- Deterministic tests for PlanDelta generation +- Audit-ready logs and crypto tagging (signatures stubs for MVP) + +Repository rules +- Use Python for core MVP; keep dependencies minimal +- Add test.sh that builds and runs tests; ensure python packaging compiles +- If you add external dependencies, update pyproject.toml and keep tests deterministic + +Contributing +- Follow the existing coding style in this repo; keep changes minimal and well-scoped +- Add tests for any bug fixes or new primitives +- Update README with usage notes and contributor guidelines diff --git a/README.md b/README.md index ce1a4f7..27ad26d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,19 @@ -# idea160-exprove-open-source +# ExProve: Open-Source Execution Provenance Engine for Cross-Venue Equity Trading -Source logic for Idea #160 \ No newline at end of file +ExProve provides a minimal, production-oriented MVP for verifiable cross-venue execution provenance. + +- Core primitives: LocalExecutionTask, SharedMarketContext, PlanDelta, Attestation, AuditLog, GraphOfContracts +- Edge-native planner: deterministic PlanDelta generation for replay and backtesting +- Deterministic delta-synchronization for offline replay +- Python-based MVP with a small test suite and packaging metadata + +- How to run + 1. Install dependencies via pyproject.toml (build uses setuptools) + 2. Run test script: bash test.sh +- What’s included + - AGENTS.md: SWARM guidelines and MVP plan + - src/exprove: core primitives and engine + - tests/test_exprove_basic.py: basic unit tests + - test.sh: build and test harness + +This README should evolve as the MVP matures and more adapters and backtests are added. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..c69e31d --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,13 @@ +[build-system] +requires = ["setuptools>=61.0", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "exprove-core" +version = "0.0.1" +description = "Open, verifiable execution provenance primitives for cross-venue equity trading" +requires-python = ">=3.8" + +[tool.setuptools.packages.find] +where = ["src"] +include = ["exprove*"] diff --git a/src/exprove/__init__.py b/src/exprove/__init__.py new file mode 100644 index 0000000..b63f6df --- /dev/null +++ b/src/exprove/__init__.py @@ -0,0 +1,20 @@ +"""ExProve core primitives package. + +This minimal MVP provides: +- LocalExecutionTask +- SharedMarketContext +- PlanDelta +- Attestation +- AuditLog +- GraphOfContracts +""" +from .contracts import LocalExecutionTask, SharedMarketContext, PlanDelta, Attestation, AuditLog, GraphOfContracts + +__all__ = [ + "LocalExecutionTask", + "SharedMarketContext", + "PlanDelta", + "Attestation", + "AuditLog", + "GraphOfContracts", +] diff --git a/src/exprove/contracts.py b/src/exprove/contracts.py new file mode 100644 index 0000000..f27cd28 --- /dev/null +++ b/src/exprove/contracts.py @@ -0,0 +1,76 @@ +from __future__ import annotations + +import json +from dataclasses import dataclass, asdict, field +from typing import Any, Dict, List, Optional + + +def to_json(obj: Any) -> str: + return json.dumps(obj, default=lambda o: o.__dict__, sort_keys=True) + + +@dataclass +class LocalExecutionTask: + task_id: str + instrument: str + venue: str + objective: str + constraints: Dict[str, Any] = field(default_factory=dict) + + def to_json(self) -> str: + return to_json(asdict(self)) + + +@dataclass +class SharedMarketContext: + signals: Dict[str, Any] + version: int + contract_id: str + + def to_json(self) -> str: + return to_json(asdict(self)) + + +@dataclass +class PlanDelta: + delta: Dict[str, Any] + timestamp: float + author: str + contract_id: str + privacy_budget: Optional[float] = None + + def to_json(self) -> str: + return to_json(asdict(self)) + + +@dataclass +class Attestation: + entry: str + signer: str + timestamp: float + contract_id: str + version: int + + def to_json(self) -> str: + return to_json(asdict(self)) + + +@dataclass +class AuditLog: + entries: List[Attestation] = field(default_factory=list) + + def add(self, at: Attestation) -> None: + self.entries.append(at) + + def to_json(self) -> str: + return to_json([asdict(e) for e in self.entries]) + + +@dataclass +class GraphOfContracts: + adapters: Dict[str, Any] + version: int + registry_id: str + + def to_json(self) -> str: + return to_json(asdict(self)) diff --git a/src/exprove/engine.py b/src/exprove/engine.py new file mode 100644 index 0000000..6410097 --- /dev/null +++ b/src/exprove/engine.py @@ -0,0 +1,58 @@ +"""A tiny, deterministic edge-native planner placeholder. + +Given a LocalExecutionTask and SharedMarketContext, produce a PlanDelta + deterministically using a stable hash seed. This is intentionally minimal + but deterministic to support replay in backtesting. +""" + +import hashlib +import time +from typing import Any, Dict + +from .contracts import LocalExecutionTask, SharedMarketContext, PlanDelta + + +def _deterministic_delta(task: LocalExecutionTask, ctx: SharedMarketContext) -> Dict[str, Any]: + seed_input = f"{task.task_id}:{task.instrument}:{task.venue}:{ctx.version}:{ctx.contract_id}" + h = hashlib.sha256(seed_input.encode("utf-8")).hexdigest() + # Deterministic small delta: a suggested route and a size adjustment heuristic + delta = { + "route": [task.venue], # naive: route to the requested venue + "size_adjustment": int(h[:6], 16) % 1000, # some deterministic sizing tweak + # Deterministic replay: timestamp set to a fixed value for determinism + "timestamp": 0.0, + "hash_seed": h, + } + return delta + + +def compute_plan_delta(task: LocalExecutionTask, ctx: SharedMarketContext, *, author: str) -> PlanDelta: + delta = _deterministic_delta(task, ctx) + return PlanDelta( + delta=delta, + timestamp=0.0, + author=author, + contract_id=ctx.contract_id, + privacy_budget=None, + ) + + +def main(): + # Simple CLI-friendly demonstration (not imported by tests) + import json + + # Example wiring; in real usage this would be from inputs + task = LocalExecutionTask( + task_id="demo-001", + instrument="AAPL", + venue="VenueA", + objective="VWAP-tracking", + constraints={"latency_ms": 50}, + ) + ctx = SharedMarketContext(signals={"depth": 5}, version=1, contract_id="contract-1") + delta = compute_plan_delta(task, ctx, author="engine") + print(delta.to_json()) + + +if __name__ == "__main__": + main() diff --git a/test.sh b/test.sh new file mode 100644 index 0000000..3c71eb0 --- /dev/null +++ b/test.sh @@ -0,0 +1,11 @@ +#!/bin/bash +set -euo pipefail + +# Build and test ExProve MVP +echo "==> Building package..." +python3 -m build + +echo "==> Running tests..." +pytest -q + +echo "==> All tests passed." diff --git a/tests/test_exprove_basic.py b/tests/test_exprove_basic.py new file mode 100644 index 0000000..cc4cfa9 --- /dev/null +++ b/tests/test_exprove_basic.py @@ -0,0 +1,51 @@ +import json +import sys +import os + +# Ensure the src/ directory is on PYTHONPATH for tests when running from repo root +repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "..")) +src_dir = os.path.join(repo_root, "src") +if src_dir not in sys.path: + sys.path.insert(0, src_dir) + +from exprove import LocalExecutionTask, SharedMarketContext, PlanDelta +from exprove.engine import compute_plan_delta + + +def test_local_execution_task_serialization(): + t = LocalExecutionTask( + task_id="t1", + instrument="GOOG", + venue="VenueX", + objective="VWAP", + constraints={"latency": 10}, + ) + s = t.to_json() + assert isinstance(s, str) + d = json.loads(s) + assert d["task_id"] == "t1" + assert d["instrument"] == "GOOG" + + +def test_engine_deterministic_delta(): + task = LocalExecutionTask( + task_id="t2", + instrument="MSFT", + venue="VenueY", + objective="VWAP", + constraints={"latency": 5}, + ) + ctx = SharedMarketContext(signals={"depth": 10}, version=2, contract_id="c-2") + delta1 = compute_plan_delta(task, ctx, author="engine") + delta2 = compute_plan_delta(task, ctx, author="engine") + assert delta1.delta == delta2.delta + assert delta1.timestamp <= delta2.timestamp # non-decreasing timestamp on re-run is fine + + +def test_attestation_and_auditlog_serialization(): + from exprove.contracts import Attestation, AuditLog + a = Attestation(entry="delta committed", signer="issuer", timestamp=1.0, contract_id="c-3", version=1) + log = AuditLog() + log.add(a) + j = log.to_json() + assert isinstance(j, str)