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.

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.0.tar.gz (104.8 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.0-py3-none-any.whl (22.1 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: blackboardx-0.2.0.tar.gz
  • Upload date:
  • Size: 104.8 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.0.tar.gz
Algorithm Hash digest
SHA256 6447679e4655eee8e872d3a8fcccbce134a066e7fe85b9e10be148535f9d7ea9
MD5 63a04b692caee99a59bc5fb58c749d1a
BLAKE2b-256 c2dc5a2bab18cb905d0c3431b0ef0a407c251afd7f3f5c8e3c586ae04272335a

See more details on using hashes here.

Provenance

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

Publisher: publish.yml on MoeinRoghani/blackboard

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.0-py3-none-any.whl.

File metadata

  • Download URL: blackboardx-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 22.1 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.0-py3-none-any.whl
Algorithm Hash digest
SHA256 db71ba38de3b892782e4e10c82bddca1e294b25b8657e10c7156a0136e4f5eed
MD5 9e0cd3e84c6316c7adc989f6b9dec220
BLAKE2b-256 5ca108f2fd20e3c2f5015b0c56529643440b23a9ba47c4f59e4a0237eb16fc27

See more details on using hashes here.

Provenance

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

Publisher: publish.yml on MoeinRoghani/blackboard

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

0.2.1

2 files

This release

0.2.0 This release

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