doin-plugins

Status: ACTIVE — component of the DOIN family.

doin-plugins provides the reusable plugin implementations for DOIN, the Decentralized Optimization and Inference Network. Every class here subclasses the abstract interfaces defined in doin-core (OptimizationPlugin, InferencePlugin, SyntheticDataPlugin) and is registered under the entry-point groups doin.optimization, doin.inference, and doin.synthetic_data, so the unified runtime doin-node can discover them by name from a per-machine JSON config.

Research origin

The DOIN family derives from Harvey Demian Bastidas Caicedo's 2018 Master's in Engineering thesis at Pontificia Universidad Javeriana Cali, Computación Evolutiva Descentralizada de Modelo Híbrido usando Blockchain y Prueba de Trabajo de Optimización. This repository implements the modern plugin boundary added as the original research platform evolved into the current doin-core protocol library and unified doin-node runtime.

Read the original thesis in the doin-core repository: Hybrid-Model Decentralized Evolutionary Computing Using Blockchain and Proof-of-Work Optimization.

Role and non-responsibilities

Role: concrete plugin implementations — a self-contained quadratic reference domain plus adapters that connect external domain optimizers (timeseries predictor, agent-multi trading) to the DOIN protocol.

Not in this repository:

• No plugin ABCs or entry-point group definitions — those live in doin-core (doin_core.plugins.base / doin_core.plugins.loader).
• No node runtime, consensus, networking, or OLAP — that is doin-node.
• Not the home of domain models. Domain optimizers remain external installable packages that work locally without DOIN. The predictor and trading plugins here are adapters: the real optimizers stay in their own repositories, and these plugins only add DOIN migration callbacks and the plugin contract (see the module docstring of src/doin_plugins/trading/optimizer.py).

Registered entry points

From pyproject.toml (names as doin-node configs must reference them):

Name	doin.optimization	doin.inference	doin.synthetic_data
simple_quadratic	quadratic_optimizer.py	quadratic_inferencer.py	quadratic_synthetic.py
predictor	predictor/optimizer.py	predictor/inferencer.py	predictor/synthetic.py
binary_predictor	predictor/binary_optimizer.py	predictor/binary_inferencer.py	—
trading_asset	trading/optimizer.py	trading/inferencer.py	—
trading_scenario	—	—	trading/synthetic.py

The plugin families:

• simple_quadratic — self-contained reference domain (hill-climbing on a quadratic loss). No ML frameworks; used to exercise the full DOIN pipeline.
• predictor / binary_predictor — adapters around the external predictor timeseries system's genetic-algorithm optimizer, adding island-model champion migration callbacks. Require that package and its ML stack at runtime.
• trading_asset / trading_scenario — adapters around the external agent-multi trading optimizer. src/doin_plugins/trading/runtime.py (AgentMultiRuntime) resolves an agent-multi checkout from the plugin config (agent_multi_root), loads its canonical experiment JSON and entry-point plugins, and exposes the same local pipeline that agent-multi --load_config uses. The local optimizer remains in agent-multi; this package never replaces it.

Requirements

From pyproject.toml:

• Python >=3.10
• doin-core>=0.1.0, numpy>=1.24, pandas>=2.1
• Runtime-only extras not declared in packaging metadata: the predictor / binary_predictor plugins import the external predictor package (with its TensorFlow stack), and the trading_* plugins import an agent-multi checkout resolved at configure time. The simple_quadratic family has no such requirement.

Installation

git clone https://github.com/harveybc/doin-core.git
git clone https://github.com/harveybc/doin-plugins.git
pip install -e doin-core -e doin-plugins

Verified 2026-08-10 in the maintainer's Python 3.12 environment: importing doin_plugins succeeds and all five entry-point names above are visible via importlib.metadata.entry_points. No PyPI release; install from source.

Smallest working example

Load the quadratic reference plugins through the entry-point loader, run one optimization step, verify it, and hash deterministic synthetic data. Executed successfully on 2026-08-10:

from doin_core.plugins.loader import (
    load_optimization_plugin,
    load_inference_plugin,
    load_synthetic_data_plugin,
)

optimizer = load_optimization_plugin("simple_quadratic")()
inferencer = load_inference_plugin("simple_quadratic")()
synthetic = load_synthetic_data_plugin("simple_quadratic")()

config = {"n_params": 4, "step_size": 0.5, "seed": 42,
          "target": [1.0, -2.0, 3.0, 0.5]}
optimizer.configure(config)
inferencer.configure(config)
synthetic.configure(config)

params, reported = optimizer.optimize(None, None)
verified = inferencer.evaluate(params)          # same value as reported
data, data_hash = synthetic.generate_with_hash(seed=1234)
print(round(reported, 4), round(verified, 4), data_hash[:16])

Using these plugins in a DOIN network

For a complete agent-oriented adaptation path, including exact repository paths, local/trusted/untrusted acceptance rungs and a pasteable assignment, see docs/ADAPT_A_NEW_DOMAIN_WITH_AN_AGENT.md.

doin-node configs reference plugins by entry-point name, for example the domain block of doin-node's single-node quadratic example:

{
  "domain_id": "quadratic",
  "optimize": true,
  "evaluate": true,
  "optimization_plugin": "simple_quadratic",
  "inference_plugin": "simple_quadratic",
  "synthetic_data_plugin": "simple_quadratic"
}

examples/run_predictor_network.py is a historical walkthrough that boots a node together with the retired standalone doin-optimizer / doin-evaluator clients; it additionally requires the external predictor stack and those legacy packages. Current deployments run everything through doin-node roles instead.

Tests

pip install -e .[dev]
pytest -q

Observed 2026-08-10: pytest -q --collect-only | tail -1 reports 44 tests collected across 7 test files in tests/, including the end-to-end optimae lifecycle (tests/test_e2e_lifecycle.py) and the trading adapter contract (tests/test_trading_plugins.py). (Collection count only; run pytest -q for a full pass.)

Artifacts and outputs

The quadratic plugins keep everything in memory. The predictor/trading adapters delegate artifact handling (models, training stats) to their external packages and report metrics back to the calling doin-node, which owns on-chain persistence, deduplication, and OLAP recording.

Safety and trading disclaimer

The trading_asset / trading_scenario plugins operate on historical or synthetic market data through agent-multi's simulation/backtest pipeline. They place no live orders and require no exchange, broker, or API credentials. Nothing in this repository is financial advice.

Limitations

• predictor, binary_predictor, and trading_* plugins are unusable without their external packages present at runtime; only simple_quadratic is fully self-contained.
• Version 0.1.0 (alpha); no PyPI distribution.

Related repositories

• doin-core — protocol primitives and the plugin ABCs implemented here
• doin-node — unified participant runtime that loads these plugins by entry-point name
• predictor and agent-multi — external domain packages wrapped by the adapter plugins

License

Declared MIT in pyproject.toml; the repository does not currently ship a standalone LICENSE file.