govgraph 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- govgraph-0.1.0/.gitignore +17 -0
- govgraph-0.1.0/CHANGELOG.md +35 -0
- govgraph-0.1.0/LICENSE +202 -0
- govgraph-0.1.0/PKG-INFO +265 -0
- govgraph-0.1.0/README.md +224 -0
- govgraph-0.1.0/docs/adapters.md +175 -0
- govgraph-0.1.0/docs/ontology.md +395 -0
- govgraph-0.1.0/docs/publishing.md +39 -0
- govgraph-0.1.0/docs/security.md +113 -0
- govgraph-0.1.0/examples/online_store/Dockerfile +14 -0
- govgraph-0.1.0/examples/online_store/docker-compose.yml +79 -0
- govgraph-0.1.0/examples/online_store/out/.gitkeep +0 -0
- govgraph-0.1.0/examples/online_store/run_demo.py +237 -0
- govgraph-0.1.0/pyproject.toml +103 -0
- govgraph-0.1.0/src/govgraph/__init__.py +55 -0
- govgraph-0.1.0/src/govgraph/__main__.py +3 -0
- govgraph-0.1.0/src/govgraph/adapters/__init__.py +6 -0
- govgraph-0.1.0/src/govgraph/adapters/base.py +49 -0
- govgraph-0.1.0/src/govgraph/adapters/csv_json.py +162 -0
- govgraph-0.1.0/src/govgraph/adapters/datahub.py +255 -0
- govgraph-0.1.0/src/govgraph/adapters/dbt.py +264 -0
- govgraph-0.1.0/src/govgraph/adapters/openmetadata.py +290 -0
- govgraph-0.1.0/src/govgraph/adapters/registry.py +51 -0
- govgraph-0.1.0/src/govgraph/cli.py +357 -0
- govgraph-0.1.0/src/govgraph/engines/__init__.py +5 -0
- govgraph-0.1.0/src/govgraph/engines/puppygraph.py +150 -0
- govgraph-0.1.0/src/govgraph/errors.py +58 -0
- govgraph-0.1.0/src/govgraph/export.py +67 -0
- govgraph-0.1.0/src/govgraph/ids.py +63 -0
- govgraph-0.1.0/src/govgraph/ingest.py +95 -0
- govgraph-0.1.0/src/govgraph/mcp/__init__.py +5 -0
- govgraph-0.1.0/src/govgraph/mcp/server.py +110 -0
- govgraph-0.1.0/src/govgraph/py.typed +0 -0
- govgraph-0.1.0/src/govgraph/records.py +97 -0
- govgraph-0.1.0/src/govgraph/samples.py +337 -0
- govgraph-0.1.0/src/govgraph/spec/__init__.py +6 -0
- govgraph-0.1.0/src/govgraph/spec/docs.py +71 -0
- govgraph-0.1.0/src/govgraph/spec/loader.py +301 -0
- govgraph-0.1.0/src/govgraph/spec/model.py +177 -0
- govgraph-0.1.0/src/govgraph/spec/ontologies/core-1.0.yaml +228 -0
- govgraph-0.1.0/src/govgraph/spec/ontology.schema.json +91 -0
- govgraph-0.1.0/src/govgraph/store/__init__.py +14 -0
- govgraph-0.1.0/src/govgraph/store/base.py +104 -0
- govgraph-0.1.0/src/govgraph/store/ddl.py +93 -0
- govgraph-0.1.0/src/govgraph/store/memory.py +134 -0
- govgraph-0.1.0/src/govgraph/store/postgres.py +373 -0
- govgraph-0.1.0/src/govgraph/store/queries.py +168 -0
- govgraph-0.1.0/src/govgraph/tools/__init__.py +18 -0
- govgraph-0.1.0/src/govgraph/tools/context.py +203 -0
- govgraph-0.1.0/src/govgraph/tools/limits.py +38 -0
- govgraph-0.1.0/src/govgraph/tools/results.py +125 -0
- govgraph-0.1.0/src/govgraph/tools/schemas.py +113 -0
- govgraph-0.1.0/src/govgraph/tools/toolkit.py +603 -0
- govgraph-0.1.0/src/govgraph/validation.py +157 -0
- govgraph-0.1.0/src/govgraph/viewer/__init__.py +32 -0
- govgraph-0.1.0/src/govgraph/viewer/viewer.html +84 -0
- govgraph-0.1.0/src/govgraph/viewer/viewer.js +476 -0
- govgraph-0.1.0/tests/__init__.py +0 -0
- govgraph-0.1.0/tests/conftest.py +112 -0
- govgraph-0.1.0/tests/test_adapters_catalogs.py +726 -0
- govgraph-0.1.0/tests/test_adapters_files.py +308 -0
- govgraph-0.1.0/tests/test_cli.py +366 -0
- govgraph-0.1.0/tests/test_docs.py +94 -0
- govgraph-0.1.0/tests/test_engines.py +163 -0
- govgraph-0.1.0/tests/test_example.py +45 -0
- govgraph-0.1.0/tests/test_export_viewer.py +122 -0
- govgraph-0.1.0/tests/test_ids_records.py +108 -0
- govgraph-0.1.0/tests/test_imports.py +33 -0
- govgraph-0.1.0/tests/test_ingest.py +130 -0
- govgraph-0.1.0/tests/test_mcp.py +120 -0
- govgraph-0.1.0/tests/test_ontology.py +360 -0
- govgraph-0.1.0/tests/test_postgres.py +296 -0
- govgraph-0.1.0/tests/test_postgres_offline.py +102 -0
- govgraph-0.1.0/tests/test_sql.py +204 -0
- govgraph-0.1.0/tests/test_store.py +224 -0
- govgraph-0.1.0/tests/test_tools.py +958 -0
- govgraph-0.1.0/tests/test_validation.py +198 -0
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
__pycache__/
|
|
2
|
+
*.py[cod]
|
|
3
|
+
.venv/
|
|
4
|
+
build/
|
|
5
|
+
dist/
|
|
6
|
+
*.egg-info/
|
|
7
|
+
.coverage
|
|
8
|
+
.coverage.*
|
|
9
|
+
htmlcov/
|
|
10
|
+
coverage.xml
|
|
11
|
+
.mypy_cache/
|
|
12
|
+
.pytest_cache/
|
|
13
|
+
.ruff_cache/
|
|
14
|
+
.env
|
|
15
|
+
.DS_Store
|
|
16
|
+
examples/online_store/out/*
|
|
17
|
+
!examples/online_store/out/.gitkeep
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are recorded here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
|
|
5
|
+
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
## [0.1.0] - 2026-11-17
|
|
8
|
+
|
|
9
|
+
First public release.
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Core ontology 1.0.0, shipped as YAML and validated against a JSON schema: ten node types
|
|
14
|
+
(`DataAsset`, `BusinessTerm`, `CriticalDataElement`, `Regulation`, `DataProduct`, `Owner`,
|
|
15
|
+
`DQRule`, `DQResult`, `DQFailure`, `LineageEdge`) and eleven edge types (`DEFINES`,
|
|
16
|
+
`CLASSIFIED_AS`, `GOVERNED_BY`, `OWNED_BY`, `VALIDATES`, `PROTECTS`, `DERIVES_FROM`,
|
|
17
|
+
`FAILED_ON`, `IMPACTS`, `RESULT_OF`, `RAISED_FROM`).
|
|
18
|
+
- Ontology extensions in YAML, with dangling edge types and conflicting definitions
|
|
19
|
+
rejected.
|
|
20
|
+
- Deterministic node and edge IDs derived from the natural key.
|
|
21
|
+
- PostgreSQL store with one table per node and edge type generated from the ontology,
|
|
22
|
+
idempotent merging upserts, and a reader that is read-only, runs only allow-listed
|
|
23
|
+
parameterized statements and refuses a role that can write.
|
|
24
|
+
- In-memory store backed by NetworkX, with the same behaviour.
|
|
25
|
+
- PuppyGraph schema generation from the ontology.
|
|
26
|
+
- Agent tools `get_asset_context`, `explain_failure`, `impact_of`, `upstream_causes` and
|
|
27
|
+
`find_by_term`, with JSON-schema signatures, hard limits on depth, rows and runtime,
|
|
28
|
+
citations on every claim, and an audit event per call.
|
|
29
|
+
- MCP server that serves the tools over standard input and output.
|
|
30
|
+
- Adapters for CSV, JSON, dbt artifacts, OpenMetadata exports and DataHub exports,
|
|
31
|
+
discovered through the `govgraph.adapters` entry-point group.
|
|
32
|
+
- Bounded JSON export and a dependency-free SVG viewer.
|
|
33
|
+
- `govgraph` command-line interface.
|
|
34
|
+
- A synthetic online-store dataset, and an example that runs it on PostgreSQL and
|
|
35
|
+
PuppyGraph with Docker Compose.
|
govgraph-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
govgraph-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: govgraph
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Turn data-governance metadata into a typed knowledge graph that AI agents traverse through bounded, auditable tools.
|
|
5
|
+
Project-URL: Homepage, https://github.com/onlinekartik/govgraph
|
|
6
|
+
Project-URL: Repository, https://github.com/onlinekartik/govgraph
|
|
7
|
+
Project-URL: Issues, https://github.com/onlinekartik/govgraph/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/onlinekartik/govgraph/blob/main/CHANGELOG.md
|
|
9
|
+
Author: The govgraph contributors
|
|
10
|
+
License-Expression: Apache-2.0
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: agents,data governance,data quality,knowledge graph,lineage
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Database
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: jsonschema>=4.18
|
|
24
|
+
Requires-Dist: networkx>=3.0
|
|
25
|
+
Requires-Dist: pyyaml>=6.0
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: mcp<3,>=2; extra == 'dev'
|
|
28
|
+
Requires-Dist: mypy>=1.10; extra == 'dev'
|
|
29
|
+
Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
|
|
30
|
+
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
|
|
31
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
32
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
33
|
+
Requires-Dist: types-jsonschema; extra == 'dev'
|
|
34
|
+
Requires-Dist: types-networkx; extra == 'dev'
|
|
35
|
+
Requires-Dist: types-pyyaml; extra == 'dev'
|
|
36
|
+
Provides-Extra: mcp
|
|
37
|
+
Requires-Dist: mcp<3,>=2; extra == 'mcp'
|
|
38
|
+
Provides-Extra: postgres
|
|
39
|
+
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
|
|
40
|
+
Description-Content-Type: text/markdown
|
|
41
|
+
|
|
42
|
+
# govgraph
|
|
43
|
+
|
|
44
|
+
govgraph turns data-governance metadata into a typed knowledge graph, and gives AI agents
|
|
45
|
+
a small set of bounded, auditable tools for reading it.
|
|
46
|
+
|
|
47
|
+
The metadata is the kind a data catalog holds: tables and columns, business terms, critical
|
|
48
|
+
data elements, regulations, owners, data-quality rules and failures, and lineage. An agent
|
|
49
|
+
can ask "why did this check fail?" or "what breaks if this table is wrong?" and get an
|
|
50
|
+
answer in which every statement cites the graph nodes that support it.
|
|
51
|
+
|
|
52
|
+
- **Typed.** Node and edge types live in one versioned YAML ontology. Tables, validation,
|
|
53
|
+
graph-engine mappings and tools are all derived from it. You extend it with your own YAML.
|
|
54
|
+
- **Bounded.** Every tool call has hard limits on depth, rows and runtime.
|
|
55
|
+
- **Read-only.** Tools get a reader that cannot write, run only allow-listed, parameterized
|
|
56
|
+
queries, and never return SQL.
|
|
57
|
+
- **Vendor-neutral.** Runs in memory with no server, or on PostgreSQL. Adapters are plugins.
|
|
58
|
+
|
|
59
|
+
Status: alpha (0.1.0). The API may change before 1.0.
|
|
60
|
+
|
|
61
|
+
## Quickstart
|
|
62
|
+
|
|
63
|
+
You need Python 3.10 or later. Install govgraph from PyPI:
|
|
64
|
+
|
|
65
|
+
```console
|
|
66
|
+
python -m pip install govgraph
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Then run this. It needs no database and no network.
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
import govgraph as gg
|
|
73
|
+
from govgraph.samples import online_store
|
|
74
|
+
|
|
75
|
+
ontology = gg.load_ontology() # the built-in core ontology
|
|
76
|
+
store = gg.MemoryStore(ontology) # in-memory graph, no server needed
|
|
77
|
+
gg.ingest(online_store(), store) # a synthetic dataset that ships with the package
|
|
78
|
+
|
|
79
|
+
tools = gg.Toolkit(store.reader()) # the tools only ever get a read-only reader
|
|
80
|
+
failure = gg.node_id("DQFailure", {"failure_id": "F-1002"})
|
|
81
|
+
|
|
82
|
+
result = tools.explain_failure(failure)
|
|
83
|
+
for claim in result.claims:
|
|
84
|
+
print("-", claim.statement)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
It prints 17 statements. The first and last are:
|
|
88
|
+
|
|
89
|
+
```text
|
|
90
|
+
- DQFailure 'F-1002' (critical, open, detected 2024-03-01T06:20:00+00:00): 310 orders have a missing or negative total.
|
|
91
|
+
- Possible cause: DQFailure 'F-1001' (high, open, detected 2024-03-01T06:05:00+00:00) failed on DataAsset 'raw.payments.amount', 2 steps upstream of DataAsset 'marts.order_facts.order_total'
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Each claim also carries `citations`, the IDs of the nodes it rests on, and
|
|
95
|
+
`result.to_dict()` gives the whole answer as JSON. The same thing from the command line:
|
|
96
|
+
|
|
97
|
+
```console
|
|
98
|
+
govgraph tool explain_failure --sample \
|
|
99
|
+
--args "{\"failure_id\": \"$(govgraph id DQFailure failure_id=F-1002)\"}"
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## How it fits together
|
|
103
|
+
|
|
104
|
+
| Layer | What it does | Where |
|
|
105
|
+
| --- | --- | --- |
|
|
106
|
+
| Spec | One declarative ontology is the single source of truth for node and edge types. | [`spec/`](src/govgraph/spec), [docs/ontology.md](docs/ontology.md) |
|
|
107
|
+
| Store | PostgreSQL, one table per node and edge type, generated from the spec. Upserts are idempotent and IDs are a hash of the natural key. An in-memory NetworkX store works without a server. | [`store/`](src/govgraph/store) |
|
|
108
|
+
| Graph engine | A PuppyGraph schema generated from the same spec, so Cypher and Gremlin run over the SQL tables with no copy. | [`engines/`](src/govgraph/engines) |
|
|
109
|
+
| Adapters | Plugins that turn a source into normalized records. They never touch a store. | [`adapters/`](src/govgraph/adapters), [docs/adapters.md](docs/adapters.md) |
|
|
110
|
+
| Tools | Five read-only functions with JSON-schema signatures, plus an MCP server. | [`tools/`](src/govgraph/tools), [`mcp/`](src/govgraph/mcp) |
|
|
111
|
+
| Viewer | One HTML file that draws a JSON export as an SVG graph. No dependencies. | [`viewer/`](src/govgraph/viewer) |
|
|
112
|
+
|
|
113
|
+
## The tools
|
|
114
|
+
|
|
115
|
+
| Tool | Answers | Limit |
|
|
116
|
+
| --- | --- | --- |
|
|
117
|
+
| `get_asset_context(asset_id)` | What is this asset, who owns it, what governs and checks it, and what is next to it in lineage? | one step, plus regulations |
|
|
118
|
+
| `explain_failure(failure_id)` | Where did this failure happen, what raised it, who owns the data, what does it affect, and what upstream may have caused it? | 3 steps upstream |
|
|
119
|
+
| `impact_of(entity_id, depth=2)` | What is affected if this node has a problem? | depth at most 3 |
|
|
120
|
+
| `upstream_causes(asset_id, depth=3)` | Which failures are recorded on this asset, on its table or columns, and on the assets it is built from? | depth at most 5 |
|
|
121
|
+
| `find_by_term(term)` | Which business terms match this text, and what do they define? | text match on term names |
|
|
122
|
+
|
|
123
|
+
Every call also runs under `Limits(max_rows=200, timeout_s=5.0)`. You can change these up
|
|
124
|
+
to fixed ceilings of 1000 rows and 30 seconds. A call that hits a limit returns what it has
|
|
125
|
+
found with `truncated` set, and never states a conclusion that needs the missing data. A
|
|
126
|
+
depth above a tool's cap is rejected.
|
|
127
|
+
|
|
128
|
+
To use the tools from an agent framework, register them from their schemas and dispatch
|
|
129
|
+
through `call`, which validates the arguments first:
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
for schema in tools.schemas(): # name, description, input_schema (JSON Schema)
|
|
133
|
+
register_with_your_framework(schema)
|
|
134
|
+
|
|
135
|
+
result = tools.call("impact_of", {"entity_id": some_id, "depth": 2}) # raises gg.ToolError
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Every call produces an audit event. By default it is logged as one JSON line to the
|
|
139
|
+
`govgraph.audit` logger at INFO level, which your application has to route somewhere to
|
|
140
|
+
keep. Pass `Toolkit(reader, audit=your_function)` to handle the events yourself. The
|
|
141
|
+
`govgraph tool` and `govgraph mcp` commands write them to standard error, or to a file with
|
|
142
|
+
`--audit-log`.
|
|
143
|
+
|
|
144
|
+
### MCP
|
|
145
|
+
|
|
146
|
+
```console
|
|
147
|
+
pip install "govgraph[mcp]"
|
|
148
|
+
govgraph mcp --sample # the sample graph, to try a client against
|
|
149
|
+
GOVGRAPH_READER_DSN=... govgraph mcp # your graph in PostgreSQL
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
This serves the same five tools over standard input and output.
|
|
153
|
+
|
|
154
|
+
## Your own metadata
|
|
155
|
+
|
|
156
|
+
Adapters read a source and yield records. Bundled ones:
|
|
157
|
+
|
|
158
|
+
| Adapter | Reads |
|
|
159
|
+
| --- | --- |
|
|
160
|
+
| `csv` | a directory of `<Type>.csv` files |
|
|
161
|
+
| `json` | one JSON document of nodes and edges |
|
|
162
|
+
| `dbt` | `manifest.json` and, optionally, `run_results.json` |
|
|
163
|
+
| `openmetadata` | a JSON export of tables, glossary terms, test cases and lineage |
|
|
164
|
+
| `datahub` | a JSON file of metadata change proposals |
|
|
165
|
+
|
|
166
|
+
The catalog adapters read exported files. They do not call any API. See
|
|
167
|
+
[docs/adapters.md](docs/adapters.md) for the formats and for writing your own.
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
from govgraph import adapters
|
|
171
|
+
|
|
172
|
+
adapter = adapters.load("dbt", manifest_path="target/manifest.json")
|
|
173
|
+
report = gg.ingest(adapter, store) # validates every record, then writes
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
`ingest` is the only path from an adapter to a store. By default one invalid record
|
|
177
|
+
rejects the whole batch and nothing is written.
|
|
178
|
+
|
|
179
|
+
## PostgreSQL
|
|
180
|
+
|
|
181
|
+
```console
|
|
182
|
+
pip install "govgraph[postgres]"
|
|
183
|
+
export GOVGRAPH_DSN="postgresql://..." # a role that may create tables and write
|
|
184
|
+
govgraph init # creates the schema from the ontology
|
|
185
|
+
govgraph ingest dbt -o manifest_path=target/manifest.json
|
|
186
|
+
govgraph grant-reader agent_reader # SELECT only, for an existing role
|
|
187
|
+
export GOVGRAPH_READER_DSN="postgresql://..." # that read-only role
|
|
188
|
+
govgraph tool find_by_term --args '{"term": "revenue"}'
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
Connection strings are read from the environment only, never from arguments. A reader
|
|
192
|
+
refuses to work with a role that is able to change the graph, so pointing
|
|
193
|
+
`GOVGRAPH_READER_DSN` at the writing role fails with an explanation. In Python:
|
|
194
|
+
|
|
195
|
+
```python
|
|
196
|
+
store = gg.PostgresStore(ontology, writer_dsn)
|
|
197
|
+
store.create_schema()
|
|
198
|
+
gg.ingest(adapter, store)
|
|
199
|
+
store.grant_reader("agent_reader")
|
|
200
|
+
tools = gg.Toolkit(store.reader(reader_dsn))
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## PuppyGraph
|
|
204
|
+
|
|
205
|
+
```console
|
|
206
|
+
govgraph puppygraph-schema --out schema.json
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
writes a PuppyGraph schema for the same tables, which you upload to PuppyGraph. Cypher and
|
|
210
|
+
Gremlin then query PostgreSQL in place. Node and edge `id` values are the same IDs the tools
|
|
211
|
+
cite. An edge type that connects more than one pair of node types becomes one PuppyGraph
|
|
212
|
+
label per pair, and its own name works as an alias for all of them, so
|
|
213
|
+
`MATCH ()-[:OWNED_BY]->()` matches every kind of ownership.
|
|
214
|
+
|
|
215
|
+
## Viewer
|
|
216
|
+
|
|
217
|
+
```console
|
|
218
|
+
govgraph export "$(govgraph id DQFailure failure_id=F-1002)" --sample --depth 3 --out graph.json
|
|
219
|
+
govgraph viewer --data graph.json --out graph.html
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
`graph.html` is one self-contained file. Open it in a browser to pan, zoom, drag nodes,
|
|
223
|
+
filter by type and inspect properties. It loads nothing from the network.
|
|
224
|
+
|
|
225
|
+
## Example: an online store
|
|
226
|
+
|
|
227
|
+
[`examples/online_store`](examples/online_store) starts PostgreSQL and PuppyGraph, loads
|
|
228
|
+
the synthetic dataset, runs every tool through a read-only role, and checks that a Cypher
|
|
229
|
+
query through PuppyGraph gives the same answer as `explain_failure`.
|
|
230
|
+
|
|
231
|
+
```console
|
|
232
|
+
cd examples/online_store
|
|
233
|
+
docker compose up --build
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
The PuppyGraph image is about 3.4 GB. No password is stored in the repository: the first
|
|
237
|
+
start generates random ones into a Docker volume. To run only the tools, with no services:
|
|
238
|
+
|
|
239
|
+
```console
|
|
240
|
+
python examples/online_store/run_demo.py --memory
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
## Documentation
|
|
244
|
+
|
|
245
|
+
- [Ontology reference](docs/ontology.md): every node and edge type, and how to extend them.
|
|
246
|
+
- [Writing an adapter](docs/adapters.md)
|
|
247
|
+
- [Security notes](docs/security.md): what the safety properties are and how they are enforced.
|
|
248
|
+
- [Changelog](CHANGELOG.md)
|
|
249
|
+
- [Publishing guide](docs/publishing.md)
|
|
250
|
+
|
|
251
|
+
## Development
|
|
252
|
+
|
|
253
|
+
```console
|
|
254
|
+
pip install -e ".[dev]"
|
|
255
|
+
ruff check . && ruff format --check .
|
|
256
|
+
mypy
|
|
257
|
+
pytest
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
Tests use only synthetic data generated in code. The PostgreSQL tests are skipped unless
|
|
261
|
+
`GOVGRAPH_TEST_DSN` points at a disposable database; see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
262
|
+
|
|
263
|
+
## Licence
|
|
264
|
+
|
|
265
|
+
[Apache-2.0](LICENSE). Versions follow [Semantic Versioning](https://semver.org/).
|