Metadata-Version: 2.4
Name: xmi2sdc
Version: 4.0.0
Summary: Agentic XMI/UML to SDC4 data model converter
Author-email: "Timothy W. Cook" <tim@semanticdatacharter.org>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: adk,agents,data-modeling,enterprise-architect,magicdraw,sdc4,uml,xmi,xml
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8
Requires-Dist: google-adk>=1.25
Requires-Dist: httpx>=0.27
Requires-Dist: litellm>=1.75.5
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: black>=24; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# XMI2SDC

[![CI](https://github.com/SemanticDataCharter/XMI2SDC/actions/workflows/ci.yml/badge.svg)](https://github.com/SemanticDataCharter/XMI2SDC/actions/workflows/ci.yml)
![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

![XMI2SDC — Agentic XMI/UML to SDC4 Converter](images/XMI2SDC_Hero.png)

Agentic XMI/UML to SDC4 data model converter.

XMI2SDC converts enterprise UML models exported from Sparx Enterprise Architect, MagicDraw, and other tools into SDC4-compliant data models. It uses a multi-agent pipeline to parse, analyze, map, and assemble models via the SDCStudio Assembly API.

Built for **air-gapped, self-hosted** environments. No cloud dependencies required.

## Agents

| Agent | Tools | LLM | Description |
|---|---|---|---|
| parser | 3 | No | Parse XMI files, auto-detect dialect, normalize to intermediate model |
| analyzer | 3 | Yes | Semantic analysis of class intent, inheritance, associations |
| mapper | 3 | Edge cases | Apply UML-to-SDC4 type mapping rules, produce mapping plan |
| reviewer | 2 | Yes | Review mapping completeness, generate conversion report |
| assembler | 3 | No | Execute mapping plan via SDCStudio Assembly API |
| orchestrator | -- | Yes | Multi-agent coordinator: parse, analyze, map, review, assemble |

## Type Mapping

| UML Type | SDC4 Type | Notes |
|---|---|---|
| Boolean | XdBoolean | |
| Integer (non-negative) | XdCount | |
| Integer (signed) | XdQuantity | Integer restriction |
| Real / Float / Double | XdQuantity | |
| String | XdString | |
| Enumeration | XdString | Literals become enumerations |
| Date / DateTime / Time | XdTemporal | |
| Class (composite) | Cluster | |
| Composition association | Cluster containment | |

## Requirements

- **Python 3.11+**
- **An LLM endpoint** reachable via [litellm](https://github.com/BerriAI/litellm), a frontier-model API key or a local model, for the LLM-assisted analysis and edge-case mapping steps.
- **For `assemble` only:** a reachable **SDCStudio Assembly API** (the hosted [sdcstudio.axius-sdc.com](https://sdcstudio.axius-sdc.com/) or a self-hosted instance) plus an API key via `SDCSTUDIO_API_KEY` (or `--api-key`).

`convert` (parse + map to a mapping plan) runs fully standalone; only `assemble` needs SDCStudio access.

## Installation

```bash
# Install the package and its dependencies
pip install -e .

# Development (tests, linters)
pip install -e ".[dev]"
```

A `requirements.txt` mirroring the runtime dependencies is provided to build an environment directly: `pip install -r requirements.txt`.

## Quick Start

### Convert an XMI file

```bash
# Configure
cp xmi2sdc.example.yaml xmi2sdc.yaml

# Parse and map (produces JSON mapping plan)
xmi2sdc convert model.xmi

# Specify output path
xmi2sdc convert model.xmi -o mapping_plan.json
```

### MCP Mode

Expose toolsets as MCP servers for LLM clients (Claude Code, Cursor, etc.):

```bash
xmi2sdc serve --mcp parser
xmi2sdc serve --mcp mapper
```

### ADK Agent Mode

For standalone agent orchestration, a local LLM is required:

```bash
ollama pull qwen2.5:7b-instruct
# Agents use ollama/qwen2.5:7b-instruct by default via LiteLLM
```

## CLI Commands

```bash
xmi2sdc convert FILE       # Parse XMI and produce SDC4 mapping plan
xmi2sdc serve --mcp AGENT  # Start MCP stdio server for an agent toolset
xmi2sdc info               # Display config summary and agent inventory
xmi2sdc validate-config    # Validate configuration file
xmi2sdc audit show         # Display audit log with filters
```

## Configuration

Create `xmi2sdc.yaml`:

```yaml
sdcstudio:
  base_url: "http://localhost:8000"
  api_key: "${SDC_API_KEY}"

cache:
  root: ".xmi2sdc-cache"

audit:
  path: ".xmi2sdc-cache/audit.jsonl"
  log_level: "standard"  # or "verbose"

output:
  directory: "./output"
```

Environment variables in `${VAR}` syntax are substituted at load time. Missing variables cause an immediate error (fail closed).

## Supported Dialects

- **Generic XMI 2.x** -- Standard OMG XMI exports
- **Sparx Enterprise Architect** -- Auto-detected via `sparxsystems.com` namespace
- **MagicDraw / Cameo** -- Auto-detected via `nomagic.com` namespace

Dialect is detected automatically from namespace declarations in the XMI file. All dialects normalize to the same `ParsedXmiModel` intermediate representation.

## Docker

```bash
docker build -t xmi2sdc .

# MCP server mode
docker run -v $(pwd)/xmi2sdc.yaml:/home/sdc/xmi2sdc.yaml:ro \
    -e XMI2SDC_AGENT=parser \
    xmi2sdc

# CLI mode
docker run -v $(pwd)/xmi2sdc.yaml:/home/sdc/xmi2sdc.yaml:ro \
    xmi2sdc info
```

## Development

### Branch Workflow

- **`main`**: Production code (protected, PR required)
- **`dev`**: Active development

All work happens on `dev`. Create a Pull Request to merge into `main`.

### Testing

```bash
pip install -e ".[dev]"
pytest

# With coverage
pytest --cov=xmi2sdc --cov-report=term-missing
```

### Linting

```bash
ruff check src/ tests/
black --check src/ tests/
```

## Architecture

```
XMI File ──> Parser Agent ──> ParsedXmiModel ──> Mapper Agent ──> Mapping Plan JSON
                                                                        |
                                                                        v
                               Conversion Report <── Reviewer <── Assembler ──> SDCStudio API
```

The pipeline separates **deterministic** operations (parsing, type mapping) from **LLM-assisted** operations (semantic analysis, edge-case resolution). If any stage fails, earlier results are cached and the pipeline can resume without re-processing.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines and contribution workflow.

## Security

See [SECURITY.md](SECURITY.md) for the security policy and vulnerability reporting process.

## Related Projects

- [SDCStudio](https://sdcstudio.axius-sdc.com/) — the SDC4 data model platform and Assembly API provider that XMI2SDC targets.
- [SDC repositories](https://semanticdatacharter.com/repositories.html) — the open-source SDC ecosystem (validators, agents, and tooling).

## License

Apache License 2.0. Copyright 2026 Axius SDC, Inc. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
