DOCSEARCHbyAlgolia
Submit Docs

UModel (Unified Model)

repository·main·Indexed 42 days ago

https://github.com/alibaba/unifiedmodel

A vendor-neutral semantic runtime for enterprise AI, data governance, and operational intelligence. UModel provides a unified way to model and query complex enterprise entities and topologies via a local service, supporting multiple GraphStore providers including memory, file.memory, and local.ladybug. It features a flexible adapter layer with OpenAPI and Model Context Protocol (MCP) specifications, and allows for extensible storage backends through query families.

Tokens
118.6K
Snippets
350
Records
560
Agent score
52%

What's inside UModel

  1. Overview of UModel SDK examples

    main

    The UModel SDK surface provides runnable examples for several core workflows:

    • Model Inspection: Using generated SDKs (Go or Python) to check UModel model packages, parse YAML/JSON, validate envelopes, list metadata, and show link endpoints.
    • Service Integration: Combining generated model SDKs with REST service clients.
    • Contract-based Development: Writing application code that depends on public contracts rather than internal server packages.

    Available Examples

    PathEntrypointPurpose
    full-flow.zh-CN.mdEnd-to-end flowSDK generation, service startup, and running SDK examples.
    go/model-inspectorGenerated Go model SDKParsing UModel files, validating envelopes, listing metadata, and showing link endpoints.
    go/service-quickstartGo REST clientCreating workspaces, importing model packages, querying UModel elements, and viewing Agent discovery.
    python/inspect_model_pack.pyGenerated Python model SDKScanning model packages and outputting kind/domain/name/link summaries.

  2. Overview of the UModel Python SDK

    main

    The UModel Python SDK is a generated library used to construct, parse, and validate UModel schema model objects within Python environments. It ensures that your Python code remains consistent with the official UModel schema definitions.

    Key Use Cases:

    • Constructing UModel elements using Python.
    • Reading or generating YAML/JSON model definitions.
    • Maintaining type consistency with schema-generated types.

  3. Overview of UModel entry points

    main

    UModel provides three primary entry points depending on your integration needs:

    • umodel-server/: An HTTP service for UModel.
    • umctl/: A CLI tool designed to interact with the public REST API.
    • umodel-mcp/: A Model Context Protocol (MCP) server using stdio communication.

  4. Understand the UModel public domain and contract layer

    main

    The pkg/ directory contains the public-facing domain models, service contracts, and error definitions for UModel. Developers should use these packages to interact with UModel services, while server-side implementation details are kept in internal/ and should not be accessed directly.

    Key components include:

    • model/: Contains domain model types for workspaces, UModel instances, entities, relations, and queries.
    • contract/: Defines service interface contracts, including GraphStore and workspace management interfaces.
    • errors/: Provides a shared error envelope and a set of stable error codes for consistent error handling across the system.

  5. Explore UModel API definitions and protocols

    main

    The UModel API layer is defined through an adapter layer that uses standardized protocols. You can find the following specification files in the api/ directory:

    • OpenAPI Specifications: Located in openapi/, these define the RESTful interface.
    • MCP Schema Definitions: Located in mcp/, these define the Model Context Protocol schemas.

  6. UModel Binary Entry Points

    main

    The UModel project provides three primary binary entry points depending on your use case:

    • umodel-server: The UModel server implementation.
    • umctl: The Command Line Interface (CLI) tool.
    • umodel-mcp: The Model Context Protocol (MCP) Server.

  7. Validate UModel YAML/JSON configurations with UModel Validator

    main

    The UModel Validator is a tool used to ensure that UModel YAML or JSON configuration files adhere to the defined schema specifications. It is primarily used to:

    • Validate model packages located in the examples/ directory.
    • Check newly added or modified UModel elements before submission.
    • Detect issues related to field types, required fields, enum values, and reference relationships.

  8. Review UModel API specifications

    main

    The UModel adapter layer defines its API protocols through two primary specification directories:

    • openapi/: Contains the OpenAPI specifications (Spec 08).
    • mcp/: Contains the Model Context Protocol (MCP) schema definitions (Spec 07).

  9. Understand the UModel Go SDK V2 file structure

    main

    The SDK is organized into several files based on the role of the types they define:

    • umodel.go: The package entry point. It contains the type registry and parsing helpers.
    • base_types.go: Contains fundamental base types, such as semantic strings.
    • shared_types.go: Contains shared schema components used across multiple schemas, such as MetadataV1, SchemaV1, and link definitions.
    • {schema_name}.go: Contains the specific generated implementation for an individual schema.

  11. Use the UModel Web UI features

    main

    The UModel Web UI serves as a local console for managing workspaces, model definitions, and runtime data. Key functional areas include:

    • Workspace Launcher: Create or select workspaces, check API health, and override API endpoints for non-default local ports.
    • Explorer: View imported UModel definitions (EntitySets, Datasets, DataLinks, EntitySetLinks, Storage, and StorageLinks) in both graph and table views.
    • Query: An interactive surface to test and validate .umodel, .entity, and .topo workflows before implementing them in a CLI, SDK, or MCP.
    • Imports & Writes: Manage local workflows for importing UModel models and performing entity or relation writes. Note: Always review payloads before submitting write operations.
    • Data Store: View runtime entity and topology data. After running make quickstart, this section displays the bundled multi-domain sample data.
    • Agent: Inspect AgentGateway metadata, including discovery output, tools, resources, query examples, and suggested next actions.
    • Settings And API Map: Monitor API health, identify the active provider, and view common endpoints and public REST paths used by the UI.

  12. Use the UModel Query Service

    main

    The Query Service is the single public read path for all UModel definitions, entities, relations, topology, and EntitySet call planning. Instead of using separate APIs for entity lookup or graph traversal, all reads are unified through the Query Service using SPL (Simple Pipe Language) strings. This ensures consistency across the CLI, Web UI, REST API, MCP tools, and SDK clients.

    Supported SPL entry points:

    • .umodel: Reads UModel definitions.
    • .entity: Reads runtime entity records.
    • .entity_set: Handles EntitySet method calls and planning.
    • .topo: Reads runtime topology relations.
    • .runbook_set: (Implicitly supported entry point).
    # Example CLI usage to run a query
go run ./cmd/umctl --addr http://localhost:8080 query run demo ".umodel | limit 5"