UModel

中文版本：README_CN.md

UModel (Unified Model) is a vendor-neutral semantic runtime for enterprise AI, data governance, and operational intelligence. It turns fragmented schemas, entities, business objects, telemetry links, and topology relations into workspace-scoped graph context that humans, systems, and AI agents can understand and use through one local service.

With UModel, you can:

• Author and import model packs that define enterprise objects, operational objects, datasets, links, storage, and topology semantics.
• Query models, entities, and topology through one SPL surface: .umodel, .entity, and .topo.
• Explore the workspace through a local Web UI.
• Connect agent clients through AgentGateway and MCP.
• Use public REST, CLI, and SDK contracts without depending on server internals.

Demo

An AI agent reads across the object graph in the quickstart-multidomain workspace (90 seconds): it discovers services, walks cross-domain topology, and pulls metrics and logs through model-scoped query plans, without hand-writing a single query.

Why UModel

• Accelerate enterprise AI at scale. A unified semantic standard helps AI models understand data meaning across platforms, departments, tools, and domains, improving the path to intelligent operations, customer service, analytics, prediction, and agent workflows.
• Reduce data governance cost. A shared language for multi-source enterprise data frees data teams from repetitive metric alignment, field translation, and context reconstruction, so more effort goes into extracting value from data.
• Preserve vendor neutrality and choice. UModel is independent of any single platform, data tool, observability stack, or AI vendor, helping organizations avoid semantic lock-in while building digital infrastructure.
• Build an enterprise semantic operating system. UModel moves beyond a passive data dictionary toward a live, programmable semantic runtime that AI agents can query, reason over, and use as shared context for future multi-agent collaboration.

Project Scope

This repository includes the local UModel service, umctl CLI, MCP server, OpenAPI contract, React Web UI, generated SDK assets, example packs, Docker/Compose assets, and test suites.

The open-source core focuses on local operation, public contracts, semantic modeling, agent integration, and contributor-friendly extension points. Cloud-hosted control planes, multi-tenant authorization, Aliyun internal frontend packages, and domain-specific read APIs outside Query Service are outside the public core.

Five-Minute Quick Start

Requirements:

• Go 1.22 or newer.
• Make.
• Node.js 22 or newer for the Web UI.
• pnpm 9 or newer is preferred; corepack or npm exec fallback is supported by the Makefile.

Check the local toolchain:

make check-env

Start the API and Web UI with a preloaded demo workspace:

make quickstart

make quickstart starts a local API, starts the Web UI, preloads the demo workspace with GRAPHSTORE=memory, and leaves no local demo data behind after the process stops.

Next steps:

• Open http://localhost:5173, select demo, and inspect the workspace through Explorer, Query, Data Store, and Agent views.
• Integrate an agent through AgentGateway or MCP. Start with umctl agent discover demo, then connect an MCP client through umodel-mcp.
• Query models, entities, and topology through CLI or REST using Query Service.

Detailed flows:

• Quick Start
• Web UI Guide
• Query Service Guide
• MCP Reference

Stop local services:

make stop-all

Agent Skills

Loadable skills let a skill-aware agent drive UModel directly — read entities, relations, topology, and the model itself, then run model-guided root-cause analysis over the object graph. In Claude Code, install both skills in one command:

/plugin marketplace add alibaba/UnifiedModel
/plugin install umodel@unifiedmodel

Qoder, Codex, Cursor, and other agents load the same two SKILL.md files — copy them into the agent’s skills directory (.qoder/skills/ for Qoder, .agents/skills/ for Codex, .claude/skills/ for Claude Code). See Agent Skills for the catalog and the skills quickstart for per-agent install.

Architecture

UModel runs as a local service around one workspace-scoped object graph:

• Model packs define the object vocabulary: EntitySets, datasets, links, storage, and relation semantics.
• EntityStore writes runtime entities and topology relations that instantiate the model.
• Query Service is the unified read surface for .umodel, .entity, and .topo.
• AgentGateway and MCP expose discovery, resources, query examples, and safe tools for agent clients.
• Web UI, CLI, REST, and SDK clients operate against the same public contracts.

Architecture details:

• Architecture Overview
• Runtime Flow
• Query And Agent Architecture

Documentation

Start with the bilingual documentation index: docs/README.md.

Chinese documentation: docs/zh/README.md.

Development

Install local dependencies:

make install-env

Build:

make build

Run focused checks:

make guard
make test-service
make verify
make example-validate

Run the local CI gate:

make ci

Generated Go and Python model SDKs live under sdk/. The Java SDK currently remains under generated/java/. The minimal Go service client lives under sdk/go/service and wraps public REST contracts.

GraphStore Providers

Runtime GraphStore providers are selected with --graphstore.

Provider details: GraphStore Providers.

Governance And Support

• License: Apache-2.0
• Contributions: CONTRIBUTING.md
• Security policy: SECURITY.md
• Support channels: SUPPORT.md
• Code of conduct: CODE_OF_CONDUCT.md
• Changelog: CHANGELOG.md