Module Descriptions¶
For every module: Purpose, Scientific Meaning, Responsibilities, Dependencies, Future Extensions.
entity.py¶
Purpose. Defines Entity, the atomic unit of the QuantsMind
ontology — anything that exists and can be reasoned about (a qubit, a
particle, a portfolio, a molecule).
Scientific Meaning. Mirrors how every empirical science begins by naming a "thing" that can be measured and that persists across measurements — the referent of Identity across changing State.
Responsibilities. Own Identity, State, Properties, Attributes, Behaviours, Relationships, Constraints, and History composition; expose the entity lifecycle; participate in Interactions.
Dependencies. identity, state, property, attribute,
behaviour, relationship, constraint, lifecycle, event,
interfaces, exceptions, types.
Future Extensions. Typed Entity subclass registry per domain; schema-validated Property sets; entity-level access control.
system.py¶
Purpose. Defines System, a bounded composition of Entities and
the Relationships/Interactions between them.
Scientific Meaning. Mirrors the notion of a "system under study" in every science — a boundary drawn around a set of interacting components for the purpose of analysis.
Responsibilities. Own Entity membership, topology (via Relationship), aggregate State, and orchestrate Interactions among its members; expose System-level Observation.
Dependencies. entity, relationship, interaction, state,
lifecycle, event, interfaces, exceptions, types.
Future Extensions. Nested/composite Systems (System-of-Systems); System-level Constraint propagation; nested-boundary Observation scoping.
state.py¶
Purpose. Defines State, the complete observable condition of an
Entity or System at a point in Time.
Scientific Meaning. The instantaneous configuration from which all measurable quantities can, in principle, be derived — analogous to a physical system's microstate/macrostate distinction, generalized.
Responsibilities. Hold a timestamped, versioned snapshot of Attribute values; support diffing between States; support State history traversal.
Dependencies. time, attribute, event, interfaces,
exceptions, types.
Future Extensions. Probabilistic/superposed State representation for quantum domain; State compression for long-running simulations.
interaction.py¶
Purpose. Defines Interaction, an event through which one or more
Entities exchange influence, producing a State transition.
Scientific Meaning. The generalized notion of a "process" or "force" — anything that causes change, from a chemical reaction to a quantum gate application to a financial trade.
Responsibilities. Reference participant Entities, describe the transformation applied, record the resulting State transition, and emit lifecycle events.
Dependencies. entity, state, transformation, event, time,
interfaces, exceptions, types.
Future Extensions. Interaction composition (interaction pipelines); causal Interaction graphs; reversible Interaction contracts.
identity.py¶
Purpose. Defines Identity, the stable identifier for an Entity
across its lifetime, independent of mutable State.
Scientific Meaning. Answers "is this the same particle/portfolio/ qubit I measured before?" — the invariant that makes longitudinal observation possible.
Responsibilities. Guarantee uniqueness within a System scope; support human-readable naming alongside machine identifiers; support equality/hash contracts.
Dependencies. types, exceptions.
Future Extensions. Distributed/federated identity resolution; cryptographically verifiable identity for provenance.
property.py¶
Purpose. Defines Property, a named, typed, immutable-by-default
characteristic of an Entity (e.g. mass, symbol, dimensionality).
Scientific Meaning. Corresponds to intrinsic quantities in science that define what kind of thing an Entity is, as opposed to what state it is currently in.
Responsibilities. Own name, type, unit (if any), value, and immutability contract; support validation against a declared schema.
Dependencies. types, validators, exceptions.
Future Extensions. Unit-of-measure algebra; symbolic (non-numeric) Property values.
attribute.py¶
Purpose. Defines Attribute, a named, typed, mutable
characteristic of an Entity that changes through Interaction and is
captured inside State.
Scientific Meaning. Corresponds to extrinsic, measurable quantities that vary over time — position, velocity, balance, energy level.
Responsibilities. Own name, type, current value, and change history; participate in State snapshots.
Dependencies. types, validators, event, exceptions.
Future Extensions. Attribute-level constraints/bounds; derived (computed) Attributes.
behaviour.py¶
Purpose. Defines Behaviour, the set of rules governing how an
Entity may respond to or participate in Interactions.
Scientific Meaning. The "laws" or "rules of engagement" attached to a given kind of Entity — analogous to a particle's interaction cross section or an agent's decision policy.
Responsibilities. Declare which Interaction types an Entity may participate in and under what Constraints; provide hooks invoked before/after an Interaction.
Dependencies. interaction, constraint, event, exceptions,
types.
Future Extensions. Composable Behaviour policies; declarative Behaviour rule language.
relationship.py¶
Purpose. Defines Relationship, a typed, directed or undirected
connection between two or more Entities within a System.
Scientific Meaning. The generalized notion of a bond, force, correlation, or association between components of a System.
Responsibilities. Reference participant Entities, declare directionality and cardinality, carry Relationship-level metadata/ strength.
Dependencies. entity, types, exceptions.
Future Extensions. Weighted/typed Relationship graphs; temporal Relationship validity windows.
constraint.py¶
Purpose. Defines Constraint, a rule restricting the valid State
space of an Entity or System.
Scientific Meaning. Conservation laws, boundary conditions, regulatory limits — anything that narrows what States are physically or logically admissible.
Responsibilities. Evaluate whether a candidate State satisfies the Constraint; report violations with diagnostic detail.
Dependencies. state, exceptions, types.
Future Extensions. Soft (penalized) vs hard Constraints; Constraint solver integration.
lifecycle.py¶
Purpose. Defines Lifecycle, the ordered set of stages an Entity
or System passes through, and the state-machine contract governing
valid transitions.
Scientific Meaning. Mirrors the general notion of birth, growth, maturity, and dissolution present across every domain (particle creation/annihilation, organism life stages, financial instrument issuance/maturity).
Responsibilities. Define the canonical stage sequence, validate transitions, and emit lifecycle Events.
Dependencies. event, exceptions, enums, types.
Future Extensions. Domain-specific Lifecycle stage extensions; parallel/branching lifecycles.
event.py¶
Purpose. Defines Event and the EventBus contract used to
publish and subscribe to SDK-wide occurrences.
Scientific Meaning. The discrete, timestamped record of something happening — the raw material from which Observation and Knowledge are built.
Responsibilities. Own event type, timestamp, source reference, and payload; define the publish/subscribe contract.
Dependencies. time, types, exceptions, enums.
Future Extensions. Event replay/journaling; distributed event bus adapters.
observation.py¶
Purpose. Defines Observation, a recorded measurement of State at
a point in Space and Time.
Scientific Meaning. The act and record of measurement — the bridge between a System's internal State and externally usable data.
Responsibilities. Reference the observed Entity/System, the measured State (or partial State), the observer, and measurement metadata (uncertainty, method).
Dependencies. state, space, time, event, exceptions,
types.
Future Extensions. Observation uncertainty/error-bar modeling; observer-effect contracts for quantum measurement.
knowledge.py¶
Purpose. Defines Knowledge, structured information derived from
one or more Observations, usable for Prediction.
Scientific Meaning. The generalized notion of a model, correlation, or law inferred from data — what science produces from measurement.
Responsibilities. Reference contributing Observations, hold a structured Knowledge payload (model, rule, statistic), and expose a Prediction-generation contract point (interface only).
Dependencies. observation, types, exceptions.
Future Extensions. Confidence/provenance tracking; Knowledge composition and conflict resolution.
transformation.py¶
Purpose. Defines Transformation, a mapping that converts an
Entity, State, or System from one representation or form to another.
Scientific Meaning. The generalized notion of an operator, map, or function applied to a physical or informational quantity.
Responsibilities. Declare input/output type contracts and an
apply() interface point; support composition of Transformations.
Dependencies. state, types, exceptions.
Future Extensions. Invertible Transformation contracts; lazy/ deferred Transformation graphs (for compiler integration).
space.py¶
Purpose. Defines Space, the coordinate/topological context in
which Entities and their State are situated.
Scientific Meaning. Generalizes physical space, Hilbert space, feature space, or portfolio space — whatever coordinate system gives State its geometric meaning.
Responsibilities. Declare dimensionality, coordinate system, and metric (if any); provide membership/containment checks.
Dependencies. types, exceptions.
Future Extensions. Curved/manifold Space contracts; composite (product) Spaces.
time.py¶
Purpose. Defines Time, the ordering dimension over which State
evolves, supporting both discrete and continuous models.
Scientific Meaning. Generalizes wall-clock time, simulation timestep, and logical/causal ordering (e.g. Lamport clocks) under one contract.
Responsibilities. Provide comparison, ordering, and delta computation between Time instants; support discrete-step and continuous representations.
Dependencies. types, exceptions.
Future Extensions. Relativistic/proper-time contracts; distributed logical clocks.
interfaces.py¶
Purpose. Defines the cross-cutting capability interfaces
(Observable, Serializable, Cloneable, Validatable,
Comparable, Identifiable, Timestamped) implemented by foundation
classes.
Scientific Meaning. N/A — pure software-engineering contract layer.
Responsibilities. Declare method signatures only; no state, no implementation.
Dependencies. types, exceptions.
Future Extensions. Composable, Auditable, Versionable
interfaces as new cross-cutting needs emerge.
protocols.py¶
Purpose. Defines structural-typing Protocol classes (PEP 544)
mirroring interfaces.py for duck-typed, non-inheritance-based
conformance checking, plus protocols for callback signatures (e.g.
EventHandler, Validator, Transformer).
Scientific Meaning. N/A — software-engineering contract layer.
Responsibilities. Enable isinstance()-checkable structural
contracts without forcing inheritance from interfaces.py ABCs.
Dependencies. types.
Future Extensions. Generic Protocols parametrized over domain value types.
enums.py¶
Purpose. Defines all foundation-level enumerations: EntityStatus,
SystemStatus, LifecycleStage, EventType, RelationshipCardinality,
RelationshipDirection, ConstraintSeverity, SerializationFormat,
ObservationMethod.
Scientific Meaning. Encodes the finite vocabularies used across the ontology (e.g. lifecycle stages, event kinds).
Responsibilities. Single source of truth for every closed vocabulary used by other foundation modules.
Dependencies. None (leaf module).
Future Extensions. Domain packages may extend certain enums (e.g.
EventType) via a documented extension-point pattern rather than
editing this module directly.
validators.py¶
Purpose. Defines the Validator contract and a small library of
reusable validation rule descriptors (type, range, regex, required,
custom-predicate).
Scientific Meaning. N/A — software-engineering contract layer that enforces scientific correctness constraints defined elsewhere (units, ranges, physical bounds).
Responsibilities. Declare Validator.validate(value) ->
ValidationResult; declare composable ValidatorChain.
Dependencies. types, enums, exceptions.
Future Extensions. Unit-aware validators; async/remote validators (e.g. regulatory checks for finance).
serializers.py¶
Purpose. Defines the Serializer contract and per-format
serializer descriptors (JSON, YAML, MessagePack, Binary, Protocol
Buffers) without implementing any of them.
Scientific Meaning. N/A — software-engineering contract layer.
Responsibilities. Declare Serializer.serialize(obj) -> bytes|str
and Serializer.deserialize(data) -> obj; declare format capability
metadata (e.g. binary vs text, schema-required vs schema-free).
Dependencies. enums, types, exceptions.
Future Extensions. Streaming (de)serialization contracts; schema evolution/versioning contracts.
factories.py¶
Purpose. Defines factory contracts (EntityFactory,
SystemFactory, InteractionFactory, EventFactory) that centralize
construction, ensuring Identity assignment, default State
initialization, and lifecycle registration happen consistently.
Scientific Meaning. N/A — software-engineering contract layer.
Responsibilities. Declare factory method signatures; document
invariants a factory must guarantee (e.g. "every Entity returned has a
valid, unique Identity and is in CREATED lifecycle stage").
Dependencies. entity, system, interaction, event, identity,
lifecycle, exceptions.
Future Extensions. Registry-based factory discovery for domain-specific Entity subclasses.
exceptions.py¶
Purpose. Defines the SDK-wide exception hierarchy rooted at
QuantsMindError, specialized through FoundationError into concrete
error types.
Scientific Meaning. N/A — software-engineering contract layer.
Responsibilities. Provide a consistent, catchable, documented error taxonomy for every failure mode described in this specification.
Dependencies. None (leaf module; everything else depends on this).
Future Extensions. Domain packages define their own subclasses of
FoundationError (e.g. QuantumError(FoundationError)).
constants.py¶
Purpose. Defines SDK-wide constant values (default timeouts, version strings, reserved names, maximum nesting depth for Systems).
Scientific Meaning. N/A.
Responsibilities. Single source of truth for magic numbers/strings used across foundation modules.
Dependencies. None (leaf module).
Future Extensions. Environment-overridable constants via config
package integration.
types.py¶
Purpose. Defines shared type aliases, TypedDict payload shapes,
and generic type variables used across foundation modules (EntityId,
Timestamp, PropertyValue, StatePayload, T, TState, TEntity).
Scientific Meaning. N/A.
Responsibilities. Prevent type-definition duplication and keep signatures consistent across modules.
Dependencies. None (leaf module).
Future Extensions. Domain-specific type aliases layered on top without modifying this module.