klab-services is the Java 21 reference implementation of k.LAB's distributed semantic-modelling and digital-twin service stack, version 1.0. The version of k.LAB in daily use is still 0.11, in the separate klab repository, currently in maintenance-only mode. Version 1.0 is used in pilot projects and will become the official k.LAB release as soon as practical.
k.LAB accepts an observation request expressed as meaning in context -
conceptually, observe <observable> in <context> - and turns it into a
semantically validated, executable dataflow that creates live scientific artifacts resolving the request. The observable expression language supplies the query and semantic annotation grammar used to express meaning and catalog candidate assets. The result of an observe query is an observation, hosted in a digital twin of configurable persistence, indissolubly linked to its semantics, provenance and lifecycle state. The k.LAB paradigm enables independent providers to contribute data, models, components and compute to a shared semantic knowledge commons, and make it immediately actionable without moving every asset into one platform or specifically planning for interoperability.
The current architecture separates four kinds of artifacts, whose ownership is assigned to different services:
Resources -> projects, data, models, components and adapters
Reasoner -> worldview semantics and context-appropriate strategies
Resolver -> resolution graphs and executable dataflows
Runtime -> sessions, digital twins, execution, storage and provenance
The services are used through an Engine process, which authenticates a human user, institution or agent, discovers services (possibly also starting local instances) and creates an initial user scope that gives access to coordinated pathways across services to implement the k.LAB observation workflow. User, session and context scope abstractions are used to drive the workflow, preserving identity, permissions, service selection and digital-twin position across process boundaries.
For the conceptual and architectural overview, read docs/KLAB.md. For a code-oriented trace of the service stack, read docs/ARCHITECTURE.md.
To follow the central observation process, start with the observable-to-contextualization mapping, then read observation strategies for worldview strategy selection, recursive resolution, current implementation gaps, and the staged proposal for explicit graph composition. Resolver internals covers coverage, dataflow compilation, transport, and runtime integration. Proposed strategy syntax is distinguished from implemented behavior.
The semantic commons is instrumented through three languages, all sharing one common observable syntax to express meaning. Assets written in these languages are assembled into versioned, peer-reviewed projects, which are hosted, managed and indexed by Resources services. The latter make them available as semantic assets to their intended communities, forming the k.LAB semantic web.
| Language | Layer and purpose |
|---|---|
| Observable expressions | Shared semantic query and asset-description syntax. inherited by all three languages |
Worldview ontology language (.kwv) |
Defines the concepts and relationships maintained by a worldview community |
k.IM (.kim) |
Publishes context-explicit models, including resource annotations, algorithms with dependencies, and semantic bridges to external services and models |
k.Actors (.kactor) |
Gives observations, digital twins, users, and sessions reactive behavior, enabling agent-based models, interactive applications and monitoring systems. Also provides a k.LAB-aligned host language for scripts and unit tests. |
Observable expressions are used directly to specialized concepts in .kwv definitions and in .kim
models to annotate resources and outputs, and to specify dependencies. In value positions, such as in function parameters or metadata, they are written as {{ ... }} semantic literals;
k.Actors uses only this literal form. Together the languages separate shared
meaning, ways of producing observations, and behavior after observations enter
a digital twin.
Worldview projects also supply observation strategy documents, parsed by
the observation grammar in the sibling klab-languages repository. These guide how the Reasoner
and Resolver select and combine methods for a request; k.IM models provide the concrete methods.
The observation grammar also defines a separate dataflow form for execution plans.
The accepted observation-strategy baseline restores the previous working behavior, including
dependent-model context propagation (maintainer-confirmed 2026-09-09). The
language guide documents structural matching, guarded setup,
named producers and implicit final output. Interface-based JSON transport is preserved; S3c and
the implementation ledger distinguish working capabilities from subsequent extensions.
The pattern language
isolates strategy patterns from the shared observable grammar while retaining ordinary observable
matches. Its persistence design reconstructs
executable Dataflows from committed provenance through a builder, encodes submitted inputs with
define, and packages observation-language source as a semantically annotated Resource. This
reconstruction and replication path is planned; the current source encoder is incomplete.
| Module | Purpose |
|---|---|
klab.core.api |
Portable, no-dependencies service contracts, scopes, language objects, observations, dataflows and digital-twin APIs. |
klab.core.common |
Shared domain implementations and utilities; import to implement any client infrastructure. |
klab.core.services |
Service bases, clients, scope management and common service infrastructure. Import to develop k.LAB extensions and components. |
klab.services.resources |
Resource, workspace, project, component and adapter management. |
klab.services.reasoner |
Worldview loading, semantic inference and observation strategies. |
klab.services.resolver |
Context-sensitive resolution graphs and dataflow compilation. |
klab.services.runtime |
Digital twins, knowledge graphs, transactions, scheduling, execution, storage and provenance. |
*.server modules |
Stand-alone server applications for the corresponding core services |
klab.modeler |
Modeler-side orchestration and support for modeling workflows. Base for user-facing IDEs and command-line drivers. |
klab.cli |
Command-line tooling (will probably be provided separately). |
klab.distribution |
Distribution and local service-stack management |
support |
Graph database, language-server and AMQP messaging support modules for local deployments. |
The k.LAB Modeler IDE, a specialized Maven plug-in to aid deployment and testing, and several plug-in components are available in this same Github repository as separate projects.
The project uses Maven and requires JDK 21. From the repository root:
.\mvnw.cmd clean installThe build is a multi-module reactor and may require access to configured snapshot repositories and sibling k.LAB language artifacts. Use targeted module builds while developing when the complete dependency set is not available, for example:
.\mvnw.cmd -pl klab.services.resolver -am testIndividual server modules contain their Spring application configuration under src/main/resources. Deployment, certificates, service discovery and components are environment-specific; do not assume that compiling the repository creates a connected public k.LAB network.
No release is available yet, but the artifacts are deployed as SNAPSHOTs in the Maven Central snapshot repository.
- k.LAB technical note: the semantic commons, service architecture, federated network and composable digital twins
- Architecture: service ownership and end-to-end observation lifecycle
- Observable expressions, worldview ontologies, k.IM and k.Actors: the user-facing language guides
- Semantic modeling and ODO-IM: the conceptual knowledge model
- Resources: resource service contract
- Resolution: resolver internals, dataflow compilation, limitations and tests
- Observation strategies: end-to-end strategy trace, named-graph composition proposal, scenario walkthroughs, and staged implementation prompts
- Classification and characterization: semantic-update lifecycle, implementation status, and staged acceptance tests
- Running strategy example: supplied strategy corpus, comparative translation, and required compatibility cases
- Draft observation grammar: evolving Observation.xtext sketch, strategy/context/dataflow fixtures, and integration requirements
- Scopes: identity, propagation and digital-twin lifetime
- Storage and provenance: runtime state and traceability
- Agent compiler: k.Actors runtime and behavior execution internals
- Components: plug-ins, adapters and service extensions
This repository is under active development toward the k.LAB 1.0 architecture. The four core service APIs and implementations are present, but not every network capability is complete. In particular, global semantic and capability discovery is planned work, and some external dataflow transport and execution paths remain transitional. The older node/engine terminology describes pre-1.0 deployments and should not be used as the organizing model for new code.
k.LAB is licensed under the GNU Affero General Public License v3. Project and partnership information is available from Integrated Modelling.