What is twingraph?

TwinGraph is a small Python package for describing how a real operating system works in a way that both people and software can inspect. Think of it as a shared blueprint format for things like power grids or battery storage systems: it records what equipment exists, how the pieces connect, what is being measured, what can be controlled, what data is available when a decision needs to be made, which prediction models are referenced, and what rules make a decision valid. It is important to understand what TwinGraph is not. It does not run simulations, optimize anything, store data long term, or provide a user interface. It only defines the structure of the information, called an intermediate representation. The package itself depends on almost nothing else, just Python's standard library plus a validation library called pydantic, which keeps it lightweight and easy to trust. A TwinGraph document is built from ten basic building blocks: entities (the objects involved), relations (how they connect), variables (things that change or are measured), data bindings (where live data comes from), model bindings (references to prediction or analysis models), actions (things that can be controlled), constraints, objectives, validators, and evidence. A function called compile_graph checks that all these pieces fit together correctly, catching problems like unknown types, broken references, or mismatched units, without actually running anything. If the document passes this check, TwinGraph produces a plan describing what should happen, but leaves the actual execution to whatever software the user builds separately. The project also ships some ready made vocabularies for common domains, covering things like batteries, solar and wind power, transformers, and data center equipment such as racks and cooling systems. This is aimed at developers building operational or industrial software who need a dependable, well defined format to pass information between real world sensors and decision making systems, rather than end users looking for a finished application.