Metadata-Version: 2.4
Name: domain-context-graph
Version: 0.4.0
Summary: Domain Context Graph protocol for grounding AI in verified domain knowledge.
License-Expression: Apache-2.0
Keywords: ai-grounding,domain-graph,domain-model,graph-protocol,llm-context
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: mcp>=1.27
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: ingest
Requires-Dist: requests>=2.28; extra == 'ingest'
Provides-Extra: ui
Description-Content-Type: text/markdown

# 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

```bash
pip install domain-context-graph
```

With git-backed persistence:

```bash
pip install domain-context-graph[git]
```

## Quick Start

```python
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

```bash
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](https://modelcontextprotocol.io) server with 28 tools for reading, writing, and querying domain graphs.

```bash
# 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:

```yaml
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](spec/rfc.md) | Formal protocol specification (IETF RFC 2119). Defines Core, Persistent, and Federated conformance levels. |
| [Design Spec](spec/design.md) | 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](https://github.me/atishio/appsec-ctx-graph) | 3-layer security + product + code domain graph built on DCG |

## License

Apache-2.0
