Knowledge sharing across agents is only meaningful if the epistemic provenance of each shared item is preserved and legible. This notebook demonstrates a Python implementation of the discoursegraphs.com base grammar — a formal information model for collaborative scientific and engineering reasoning. The grammar defines a small set of node types (Question, Claim, Evidence, Source) and predicates (supports, opposes, answers, informs) that together make the structure of an argument machine-readable. Here, two agents work in parallel on a lunar transfer stage propulsion trade study. AliceGroup (systems architecture) declares two sharing policies with different epistemic characters: one shares raw Evidence with full provenance; the other shares a Claim without its backing evidence. BobGroup (propulsion) must handle these differently — the Evidence is used directly, but the Claim must be promoted to an explicit eng:Assumption with declared scope. The result is a traceable, machine-checkable reasoning graph in which every knowledge transfer is formally described, every epistemic status is explicit, and every policy boundary is enforced by a compiled SPARQL query. The implementation follows scientific Python conventions throughout — Pydantic models for node authoring, type-annotated APIs, and NumPy-style docstrings — so that the formal machinery (OWL 2 DL ontology, SHACL validation, SPARQL policy compilation) stays under the hood while the surface API remains lightweight enough to integrate into existing data pipelines and analysis workflows.

Cross-Team Engineering Design Decision Example

Domain: Lunar transfer stage propulsion trade study Agents: AliceGroup (systems architecture) · BobGroup (propulsion subsystem) The dg: ontology implements the discoursegraphs.com base grammar — it defines Question, Claim, Evidence, and Source as node types, and the predicates that connect them (supports, opposes, answers, informs). It is intentionally minimal and domain-neutral: any field that reasons in argument form can use it as-is. Engineering decisions, however, require something more opinionated. When a team commits to a design choice — selecting a propulsion architecture, closing a trade study — the reasoning structure differs from a Claim: a Decision resolves a Question, is justified by Claims and Evidence, and can open downstream Questions for other teams. The eng: extension ontology adds exactly these concepts (eng:Decision, eng:Assumption, and their predicates) as subclasses and sub-properties of dg: types. It imports dg: and adds to it; it does not redefine or conflict with anything in the base grammar. The two namespaces reflect a deliberate separation of concerns: dg: is stable and shared across communities; eng: is domain-specific and can evolve independently. Other domains can define their own extensions in the same pattern without touching the base.

Technology stack

Each layer was chosen to keep formal rigour internal while exposing a Python-native interface. A developer authoring a node or declaring a policy never touches RDF syntax, SPARQL, or OWL directly — those are implementation details. A developer integrating the library into a data pipeline works with typed Pydantic models, standard Python dataclasses, and ordinary method calls. OWL 2 DL gives the ontology decidable reasoning semantics and a well-defined class hierarchy. We use it to express what kinds of things exist in a discourse graph and how they relate — not at runtime, but as a machine-checkable specification that SHACL shapes and the Python models are both derived from. SHACL enforces structural constraints on the serialized RDF graph. It catches things Pydantic cannot: relational invariants that only make sense once edges exist (e.g. an Evidence node must support or inform at least one other node). Running SHACL via verify() is explicit and may be deferred — it does not slow down every write. Pydantic + rdflib is the runtime pairing. Pydantic provides the user-facing API: typed constructors, field validation at the call site, and IDE autocompletion. rdflib provides the underlying RDF store and the named graph isolation that makes the policy mechanism possible. Neither is visible to a user who only calls add() and add_edge(). RDF + SPARQL for policy is the key architectural choice. Sharing policies are stored as first-class RDF individuals — they are inspectable, serializable, and auditable. At export time a policy is compiled to a SPARQL CONSTRUCT query. Alice never writes SPARQL; the library produces it from the RDF. The query is printed in Act 3 so the audience can verify that the boundary they specified in Python is exactly the boundary being enforced. NetworkX + Matplotlib handle visualization and graph analysis. NetworkX is the natural bridge between the RDF store and the broader scientific Python ecosystem: the discourse graph can be projected into a NetworkX DiGraph for layout, centrality analysis, path queries, or export to any tool that speaks NetworkX. Matplotlib renders the result. A developer who wants to run graph algorithms on a discourse graph does not need to learn SPARQL — they project to NetworkX and use the tools they already know.

Concern	Technology	Purpose
Ontology	OWL 2 DL (`dg:` + `eng:`)	Class hierarchy and predicate semantics
Shapes	SHACL	Structural and relational constraints
Runtime	Pydantic + rdflib	Write-time validation and RDF storage
Policy	RDF + SPARQL	Formal, inspectable sharing rules
Visualization & analysis	NetworkX + Matplotlib	Graph layout, algorithms, and rendering

Five-act narrative

The notebook builds up the demonstration in stages. Acts 1 and 2 establish the graphs independently so the sharing event in Acts 4 and 5 has something meaningful to work with. Act 3 is the pedagogical core — we peak under the hood at the RDF and SPARQL artifacts that Alice's Python calls produce before any data moves.

Act	Cells	Topic
1	2–5	Setup — load ontologies, create agents and graphs
2	6–11	Individual graphs — Alice and Bob build independently
3	12–17	Policy declaration — Alice writes two policies; inspect the Turtle and SPARQL artifacts
4	18–26	Sharing — policy A (direct evidence), policy B (hidden-backing claim), policy C (decision closure); invariants
5	27–28	Visualization and epistemic status summary

The contrast between Alice's two policies is the central argument of the notebook. Same source graph, same grantee, different permitted sets — different epistemic objects arrive in Bob's graph, and he must handle them differently. Bob's policy closes the loop by sharing his decision back to Alice.

Policy	Owner	Permitted set	Epistemic character
`evidence-sharing`	Alice → Bob	{E1}	Direct evidence: Bob receives Alice's delta-V analysis with full provenance
`arch-claim`	Alice → Bob	{C1}	Hidden-backing claim: Bob receives Alice's baseline assertion with no visible justification
`subsystem-decision`	Bob → Alice	{D2}	Decision closure: Alice receives Bob's thruster decision, resolving the question her D1 opened