blackboardx

A group of agents works on one problem. Each writes what it finds into a single shared record, every agent can read all of it, and no agent calls another; the record is the only channel between them. The blackboard literature calls a system skeletal when it supplies this structure with no domain knowledge inside, so that an application system is built on it by adding knowledge and control. blackboardx is skeletal in that sense. It supplies the board and the control component; an application creates a model by supplying its regions, agents, seed, admission rule, termination predicate, and budgets.

The distribution name is blackboardx; the import name is blackboard. The documentation, including the API reference, is at https://moeinroghani.github.io/blackboardx/.

Install

pip install blackboardx

The board

The board stores contributions in named regions under one total order, and it never reads what it stores. A region has one of two kinds. A level accumulates contributions in arrival order, and nothing stored is altered. A register holds one current value for a premise of the case; a write replaces the whole value under the version the writer read, and fails with the register's current version when another writer moved it first. One counter orders every write across all regions, so a contribution in one region stands in a definite order against a write in any other.

Public API

Every public name is exported from blackboard; every other module is internal.

Name Holds
Board The board: declare, append, set, read_level, read_register, read_board
Level, Register The two region declarations
Written, Conflict A register write the board sequenced, and one that named a stale version
Contribution One unit read back from a level
RegisterState A register's current value and version
BoardChange One write to any region, as read_board returns it
BlackboardError The base of every error the library raises
UndeclaredRegionError An operation named a region that no declaration created
DuplicateRegionError A declaration named a region that already exists
RegionKindError An operation that takes a level named a register, or the reverse
UnsetRegisterError A register was read before any write gave it a value
BoardReader The three read operations, as the admission rule receives them
ProposedContribution, ProposedRegisterWrite, ProposedWrite A write as the admission rule sees it, before sequencing
Accept, Reject The admission rule's two verdicts
AdmissionRule The type of the rule the application supplies
Accepted, Rejected A write the control component admitted, and one it refused
RejectionCause The closed set of causes for a refused write
WriteAccepted, WriteRejected, AuditEvent The audit's records of writes that reached the board and writes that did not
Agent An agent declaration: name, acknowledgment deadline, wake cap, and the delivery callback
Notification, NotificationId One wake, and the identifier an acknowledgment names
NotificationDispatched, NotificationAcknowledged, DeadlineExtended, PresumedFailed, WakeCapReached The audit's records of dispatch, acknowledgment, extension, presumed failure, and a reached wake cap
DuplicateAgentError A registration named an agent that is already registered
UnknownNotificationError The named notification was never issued to the acknowledging agent
Clock, ScheduledCall The protocol for reading time and arming calls, and an armed call's handle
TerminationDecision, TerminationPredicate The predicate's two answers, and the type of the predicate the application supplies
RunBudgets, BudgetKind The three run-wide limits, and their names
Complete, FinishedWithFailures, BudgetExhausted, Aborted, RunOutcome The four states a run closes in, and their union
BudgetReached, RunClosed The audit's records of a limit reached and of the run closing
RunClosedError A declaration or registration reached a run that has closed
Model, create_model A running model's read handle and control component, and the one creation path
Control The control component an application drives: writes, acknowledgment and extension, mid-run declaration and registration, abort, the audit, and the outcome
SeedError The seed's names are not exactly the declared registers
RegisterSeeded The audit's record of the seed writing one register when the run opened
SystemClock The default clock, the library's only reader of the operating system clock
ManualClock The deterministic clock a test advances by hand

Example

from datetime import timedelta

from blackboard import Agent, Complete, Level, Register, RunBudgets, create_model

wakes = []

model = create_model(
    regions=[Level("platform"), Register("window")],
    agents=[
        Agent(
            name="ocp",
            acknowledgment_deadline=timedelta(minutes=5),
            wake_cap=10,
            notify=wakes.append,
        )
    ],
    seed={"window": ("2026-08-16T20:00", "2026-08-16T22:00")},
    budgets=RunBudgets(
        wall_clock=timedelta(minutes=10), total_writes=100, total_notifications=100
    ),
)

# The agent's cycle: read the premises, contribute, acknowledge.
(wake,) = wakes
window = model.reader.read_register("window").value
model.control.write("ocp", "platform", {"window": window, "findings": ["oom"]})
model.control.ack("ocp", wake.notification_id)

assert model.control.outcome() == Complete()
for contribution in model.reader.read_level("platform"):
    print(contribution.sequence, contribution.content)

License

Apache-2.0. The license text is in LICENSE, and every distribution carries it.

Project links

Data verified by PyPI on Aug 17, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for venus-enterprise from gravatar.com venus-enterprise

Credits

Author: Moein Roghani

GitHub Statistics

Data verified by PyPI on Aug 17, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

blackboardx-0.2.1.tar.gz (121.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

blackboardx-0.2.1-py3-none-any.whl (22.2 kB view details)

Uploaded Python 3

File details

Details for the file blackboardx-0.2.1.tar.gz.

File metadata

  • Download URL: blackboardx-0.2.1.tar.gz
  • Upload date:
  • Size: 121.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for blackboardx-0.2.1.tar.gz
Algorithm Hash digest
SHA256 ae32bce3753c00f704d28654e5c6c1a0bc283a490e9444c629dc40464a582cf1
MD5 7fd846369ec7a7b923475bbc91de38f8
BLAKE2b-256 33c2afc17f4cd21ac24e538714bf12c68ebabc45515fd7c642c5be99bf1588d5

See more details on using hashes here.

Provenance

The following attestation bundles were made for blackboardx-0.2.1.tar.gz:

Publisher: publish.yml on MoeinRoghani/blackboardx

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file blackboardx-0.2.1-py3-none-any.whl.

File metadata

  • Download URL: blackboardx-0.2.1-py3-none-any.whl
  • Upload date:
  • Size: 22.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for blackboardx-0.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 2abdd5dc11ebf214c560e78f90d34b6b9758b18c1b5ee3de54fc59df7fce874e
MD5 62597c0c7c6163bff7247489b775119d
BLAKE2b-256 1f9370647d61bc4a7a8e5de66c4feff666ad1b65f4edb85dd171166933ae0ff5

See more details on using hashes here.

Provenance

The following attestation bundles were made for blackboardx-0.2.1-py3-none-any.whl:

Publisher: publish.yml on MoeinRoghani/blackboardx

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.3.0

2 files

This release

0.2.1 This release

2 files

0.2.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page