TidalFlowBridge

A secure, bidirectional communication bridge that enables TidalShift (causal pathway analysis) and FlowTrace (market/trade analysis) to share intelligence and collaborate on cross-domain financial insights.

Features

• Continuous Signal Sharing -- periodic exchange of market intelligence signals (pathway alerts, trade signals, market confirmations, etc.)
• Cross-Consultation Queries -- each system can query the other for on-demand analysis
• Budget Protection -- enforces daily/hourly spending limits on cross-system LLM queries
• Anti-Amplification Guards -- prevents echo chambers via evidence weighting and corroboration requirements
• Secure Pairing -- cryptographic trust establishment using a shared cluster passphrase + Ed25519 keys
• Flexible Transport -- supports local (SQLite) and remote (HTTP) communication modes with automatic routing

Requirements

• Python 3.10+

Installation

# Install from source
pip install -e .

# With dev dependencies
pip install -e ".[dev]"

Quick Start

1. Setup

Run interactive setup on each system to generate identity keys and configuration:

tidalflowbridge-setup [--config-dir PATH]

2. Pair Systems

Remote pairing (different machines):

tidalflowbridge-pair --peer-url http://<host>:<port> [--config-dir PATH]

Local pairing (same machine):

tidalflowbridge-pair --local --peer-identity <path> [--sqlite-path <shared-db>] [--config-dir PATH]

3. Check Status

tidalflowbridge-status [--config-dir PATH]

4. Integrate

Implement the BaseBridgeAdapter for your system and wire up the orchestrator:

from tidalflowbridge.protocol.bridge_orchestrator import BridgeOrchestrator

adapter = YourBridgeAdapter()
bridge = BridgeOrchestrator(
    adapter=adapter,
    config_path="bridge_config.json",
    base_dir=".",
    cluster_passphrase=passphrase,
)

await bridge.start()
# ... bridge runs in background, sharing signals and handling queries
await bridge.stop()

For FastAPI applications, mount the bridge router:

router = bridge.get_fastapi_router()
app.include_router(router)

Configuration

Copy bridge_config.example.json to bridge_config.json and adjust settings. Key sections:

Section	Controls
transport	Communication mode, port, polling interval, retries
continuous_sharing	Signal publishing interval, types, confidence thresholds
cross_consultation	Query depth, caching
budget	Daily/per-query spend limits, hourly query caps
anti_amplification	Max cross-project influence, corroboration requirements
evidence_weights	Importance of each signal type in joint analysis

The bridge is disabled by default (enabled: false) and requires a valid cluster passphrase to activate.

Security Model

• Cluster Passphrase -- shared secret used to derive a cluster ID and HMAC signing key
• Node Identity -- unique Ed25519 keypair per system instance
• Message Authentication -- HMAC-SHA256 on envelope bodies + Ed25519 signatures
• Peers are registered during pairing and tracked in bridge_peers.json

License

This project is licensed under the Apache License 2.0.