domain-context-graph 0.4.0

Domain Context Graph protocol for grounding AI in verified domain knowledge.

Domain Context Graph (DCG)

An open protocol for structuring domain knowledge so AI systems reason about your product — not just your code.

---

The Problem

AI coding assistants write confident code that violates business rules nobody documented. Security scanners flag vulnerabilities without knowing which domain owns the affected service. Incident responders trace call graphs without understanding blast radius across business capabilities.

• LLM training data is generic. Models know what "payments" means in general — not what your Payments domain is, who owns it, or what depends on it.
• Code graphs capture structure, not semantics. They see imports and call chains — not that two modules serve the same bounded context.
• Documentation decays instantly. Wikis are stale, unstructured, and not machine-queryable.
• Knowledge is tool-siloed. Your security scanner's vulnerability data can't connect to your code graph's ownership data because there's no shared schema.

DCG fills this gap: a standard, machine-readable protocol for domain knowledge that any AI system can consume — versioned, git-backed, and federated across teams and repos.

Core Concepts

• Wikibase-compatible entities — same JSON format used by Wikidata's 100M+ items. Labels, descriptions, aliases, and attributes with full snak structure.
• Content-addressed identity — entity UIDs are deterministic hashes (dcg:sha256:...). Same entity always gets the same ID, regardless of who creates it or when.
• Two-axis classification — every entity has a structural type (instance of Function/Class/Endpoint) and domain membership (part of Payments/Security). These are orthogonal.
• Retraction and purge — entities can be retracted (soft-deleted) and later permanently purged from the graph.
• Composition — stack multiple domain graphs via dcg-stack.yml manifests with extends chains. Query across layers; entities resolve upward through the chain.
• Federation — multiple graphs reference each other's entities via cross-graph resolution. Each team owns their graph independently.

Install

pip install domain-context-graph

With git-backed persistence:

pip install domain-context-graph[git]

Quick Start

from dcg.core import GraphStore, entity_uid, builders as kb

store = GraphStore()

# Define a domain
payments_uid = entity_uid(name="Payments")
store.add_entity(kb.entity(
    uid=payments_uid,
    label="Payments",
    description="Payment processing domain",
    attributes=[kb.attribute("instance of", kb.ref_value("dcg:meta:Domain"))],
))

# Place a code entity in that domain
fn_uid = entity_uid(name="charge_card", path="src/payments/charge.py")
store.add_entity(kb.entity(
    uid=fn_uid,
    label="charge_card",
    attributes=[
        kb.attribute("instance of", kb.ref_value("dcg:meta:Function")),
        kb.attribute("part of", kb.ref_value(payments_uid)),
        kb.attribute("file path", kb.string_value("src/payments/charge.py")),
    ],
))

# Query
functions = store.query(instance_of="dcg:meta:Function")

CLI

dcg init <name> [--path .] [--description "..."]   # Create a new domain graph project
dcg serve --project <path>                          # Start MCP server (single project)
dcg serve --stack <manifest>                        # Start MCP server (multi-layer stack)
dcg compose <manifest>                              # Validate a dcg-stack.yml manifest
dcg purge <path>                                    # Remove retracted entities and relations
dcg query <path> [--type Function] [--domain Pay]   # Query entities

MCP Server

DCG includes a built-in Model Context Protocol server with 28 tools for reading, writing, and querying domain graphs.

# Single project
dcg serve --project ./my-graph

# Multi-layer stack (cross-layer queries)
dcg serve --stack ./dcg-stack.yml

Tools include dcg_create_entity, dcg_create_domain, dcg_connect, dcg_query, dcg_snapshot, dcg_bulk_add, and more. Stack-mode adds dcg_stack_info, dcg_query_stack, and dcg_resolve_cross_layer.

Composition

Stack multiple domain graphs with a dcg-stack.yml manifest:

stack: my-appsec-stack
layers:
  - name: security
    source: ./graphs/security-domain

  - name: product
    source: ./graphs/product-domain
    extends: security

  - name: code
    source: ./graphs/code
    extends: product

The extends chain defines resolution order. When querying the code layer for an entity, DCG walks code → product → security until found. Cross-layer queries deduplicate by UID (nearest layer wins).

Package Structure

src/dcg/
  __init__.py              # Public API re-exports
  cli.py                   # CLI entry point (dcg command)
  project.py               # DomainProject — manifest-based project manager
  core/
    uid.py                 # Content-addressed entity/relation IDs
    model.py               # Entity, Relation, Attribute dataclasses
    ontology.py            # Type and property registries
    builders.py            # Wikibase JSON entity/attribute construction
    store.py               # GraphStore — in-memory implementation
    compose.py             # DcgStack — multi-project composition
    federation.py          # Cross-graph registry and resolution
    purge.py               # Retraction purge
    git_store.py           # GitGraphStore — dulwich-backed persistence
  mcp/
    server.py              # FastMCP server (28 tools)
    helpers.py             # Shared MCP utilities

Specification

Document	Description
RFC DCG-002	Formal protocol specification (IETF RFC 2119). Defines Core, Persistent, and Federated conformance levels.
Design Spec	Full architecture, entity model, ontology, and integration patterns.

The RFC is the authoritative source. This Python package is one implementation — others can implement the same spec in any language.

Extensibility

• Custom domains — register_global_type() to add domain-specific types
• Custom properties — register_property() with Wikidata P-ID aliases
• Custom backends — implement GraphStoreProtocol for any storage
• Federation — implement GraphRegistry and BoundaryResolver for cross-graph resolution

Related Projects

Project	Description
appsec-ctx-graph	3-layer security + product + code domain graph built on DCG

License

Apache-2.0