pythia-core 0.1.0__tar.gz

pythia_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thaild
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pythia_core-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: pythia-core
+Version: 0.1.0
+Summary: Shared core of the pythia family: the engine contract, connection resolution and the write gate every pythia-<engine> package drives.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/thaildhe172591/pythia-core
+Project-URL: Changelog, https://github.com/thaildhe172591/pythia-core/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/thaildhe172591/pythia-core/issues
+Keywords: database,agent-skills,sql,postgresql,sql-server,mongodb
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pythia-core
+
+**English** · [Tiếng Việt](https://github.com/thaildhe172591/pythia-core/blob/main/README.vi.md)
+
+The part of pythia that is the same for every database. Engine packages
+build on it: [pythia-postgres](https://github.com/thaildhe172591/pythia-postgres),
+[pythia-mssql](https://github.com/thaildhe172591/pythia-mssql) and
+[pythia-mongo](https://github.com/thaildhe172591/pythia-mongo).
+
+**Alpha (0.1.0).** What is here today:
+- the engine contract and its conformance check;
+- per-engine connection resolution;
+- the query-contract lint;
+- the commands every engine's command line inherits:
+  - `version`, `connections` and `check`;
+  - the read commands `ls`, `src`, `cols`, `ddl`, `grep`, `deps`, `impact`
+    and `errors`, windowed and never truncated silently;
+  - the write gate: `apply` (snapshot, rehearse inside a transaction and
+    roll back — or, for what cannot be rehearsed, predict, then write once
+    and check what landed — preview), `approve` (the developer: at a console, or from
+    chat through AskUserQuestion and `approve --hook`, or the MCP approver
+    `mcp`),
+    `apply --confirm` (commits only what was approved), `policy`,
+    `journal list | show | restore` and `history`;
+  - `deploy <files>`: a release rehearsed and committed as one transaction,
+    under one approval — all of it lands, or none of it;
+  - `autopilot request | on | off | status | report`: a lease the developer
+    approves once, covering only the connection, groups and limits its card
+    names;
+  - `lint <files>` (and `lint --rules`): the engine's rules and the team's
+    severities and naming patterns over a change, shown in every preview;
+  - the harness: `hook pre-tool` (the guard that denies the ways around the
+    gate and waves through what cannot write), `hook session-start` (the
+    rules and the project's state), `install` (connections scaffold,
+    `.gitignore`, hooks, the MCP approver in this machine's own files,
+    instruction blocks, skills — a second run changes nothing), `doctor` and
+    `skill lint`.
+
+What each gate stops, and what it does not, is in
+[SECURITY.md](https://github.com/thaildhe172591/pythia-core/blob/main/SECURITY.md). The plan, and how each idea maps to each
+database, is in [DESIGN.md](https://github.com/thaildhe172591/pythia-core/blob/main/DESIGN.md).
+
+[pythia](https://github.com/thaildhe172591/pythia) for Oracle is a separate,
+self-contained tool. It does not use this package and is not changed by it.
+
+## Install
+
+```bash
+pip install pythia-core
+```
+
+pythia-core alone has no command: install an engine package —
+`pythia-postgres`, `pythia-mssql` or `pythia-mongo` — and it comes with it.
+It depends on nothing outside the Python standard library, by contract. The
+development version is the main branch:
+
+```bash
+pip install "git+https://github.com/thaildhe172591/pythia-core"
+```
+
+## Writing an engine
+
+```python
+from pythia_core import cli
+from pythia_core.engine import engine_problems
+
+class PostgresEngine:
+    name, label, command = "postgres", "PostgreSQL", "pythia-pg"
+    env_prefix, version, bind_style = "PYTHIA_PG", "0.1.0", "pyformat"
+    # ...the connect tier: driver_errors, connect, session, close,
+    # connect_failure, schema_of, target_of, server_version, current_schema
+    # ...the read tier: object_names, source, columns (which may name a
+    # blind spot, when its columns are inferred), ddl, grep, dependencies,
+    # dependents, compile_errors
+    # ...and the write tier: classify, prepare_statement, parse_object,
+    # destructive_reason, dml_probe, measure_row_set, snapshot, rehearse,
+    # restore_statement, privilege_warning
+    # ...the predict tier, for statements that cannot be rehearsed:
+    # execute, verify_written
+    # ...the harness tier: raw_client_pattern, write_sql_pattern,
+    # script_pattern, connections_template, skills_dir
+    # ...the release tier: split_script
+    # ...and the lint tier: lint_rules
+
+assert engine_problems(PostgresEngine(),
+                       ("connect", "read", "write", "harness", "release",
+                        "lint")) == []
+
+def main(argv=None):
+    return cli.main(PostgresEngine(), argv)          # your console script
+```
+
+Each engine keeps its connections in `.pythia/<engine>/connections.json`.
+That is never pythia for Oracle's `.pythia/connections.json`, so one project
+can use both safely.
+
+## Tests (no database, no driver)
+
+```bash
+python tests/test_core.py
+python tests/test_cli.py
+python tests/test_read.py
+python tests/test_gate.py
+python tests/test_harness.py
+python tests/test_doors.py
+python tests/test_release.py
+python tests/test_lease.py
+python tests/test_lint.py
+python tests/test_family.py     # several engines in one project, with two fakes
+```
+
+CI runs them on Ubuntu, Windows and macOS, Python 3.9 and 3.13. Its
+`family` job also installs pythia for Oracle and the three engines into one
+project and runs `tests/family_check.py`: every install keeps the others'
+hooks and blocks, a second run changes nothing, each doctor passes, each
+guard and answer hook acts for its own engine only.
+
+## License
+
+MIT

pythia_core-0.1.0/README.md

@@ -0,0 +1,120 @@
+# pythia-core
+
+**English** · [Tiếng Việt](https://github.com/thaildhe172591/pythia-core/blob/main/README.vi.md)
+
+The part of pythia that is the same for every database. Engine packages
+build on it: [pythia-postgres](https://github.com/thaildhe172591/pythia-postgres),
+[pythia-mssql](https://github.com/thaildhe172591/pythia-mssql) and
+[pythia-mongo](https://github.com/thaildhe172591/pythia-mongo).
+
+**Alpha (0.1.0).** What is here today:
+- the engine contract and its conformance check;
+- per-engine connection resolution;
+- the query-contract lint;
+- the commands every engine's command line inherits:
+  - `version`, `connections` and `check`;
+  - the read commands `ls`, `src`, `cols`, `ddl`, `grep`, `deps`, `impact`
+    and `errors`, windowed and never truncated silently;
+  - the write gate: `apply` (snapshot, rehearse inside a transaction and
+    roll back — or, for what cannot be rehearsed, predict, then write once
+    and check what landed — preview), `approve` (the developer: at a console, or from
+    chat through AskUserQuestion and `approve --hook`, or the MCP approver
+    `mcp`),
+    `apply --confirm` (commits only what was approved), `policy`,
+    `journal list | show | restore` and `history`;
+  - `deploy <files>`: a release rehearsed and committed as one transaction,
+    under one approval — all of it lands, or none of it;
+  - `autopilot request | on | off | status | report`: a lease the developer
+    approves once, covering only the connection, groups and limits its card
+    names;
+  - `lint <files>` (and `lint --rules`): the engine's rules and the team's
+    severities and naming patterns over a change, shown in every preview;
+  - the harness: `hook pre-tool` (the guard that denies the ways around the
+    gate and waves through what cannot write), `hook session-start` (the
+    rules and the project's state), `install` (connections scaffold,
+    `.gitignore`, hooks, the MCP approver in this machine's own files,
+    instruction blocks, skills — a second run changes nothing), `doctor` and
+    `skill lint`.
+
+What each gate stops, and what it does not, is in
+[SECURITY.md](https://github.com/thaildhe172591/pythia-core/blob/main/SECURITY.md). The plan, and how each idea maps to each
+database, is in [DESIGN.md](https://github.com/thaildhe172591/pythia-core/blob/main/DESIGN.md).
+
+[pythia](https://github.com/thaildhe172591/pythia) for Oracle is a separate,
+self-contained tool. It does not use this package and is not changed by it.
+
+## Install
+
+```bash
+pip install pythia-core
+```
+
+pythia-core alone has no command: install an engine package —
+`pythia-postgres`, `pythia-mssql` or `pythia-mongo` — and it comes with it.
+It depends on nothing outside the Python standard library, by contract. The
+development version is the main branch:
+
+```bash
+pip install "git+https://github.com/thaildhe172591/pythia-core"
+```
+
+## Writing an engine
+
+```python
+from pythia_core import cli
+from pythia_core.engine import engine_problems
+
+class PostgresEngine:
+    name, label, command = "postgres", "PostgreSQL", "pythia-pg"
+    env_prefix, version, bind_style = "PYTHIA_PG", "0.1.0", "pyformat"
+    # ...the connect tier: driver_errors, connect, session, close,
+    # connect_failure, schema_of, target_of, server_version, current_schema
+    # ...the read tier: object_names, source, columns (which may name a
+    # blind spot, when its columns are inferred), ddl, grep, dependencies,
+    # dependents, compile_errors
+    # ...and the write tier: classify, prepare_statement, parse_object,
+    # destructive_reason, dml_probe, measure_row_set, snapshot, rehearse,
+    # restore_statement, privilege_warning
+    # ...the predict tier, for statements that cannot be rehearsed:
+    # execute, verify_written
+    # ...the harness tier: raw_client_pattern, write_sql_pattern,
+    # script_pattern, connections_template, skills_dir
+    # ...the release tier: split_script
+    # ...and the lint tier: lint_rules
+
+assert engine_problems(PostgresEngine(),
+                       ("connect", "read", "write", "harness", "release",
+                        "lint")) == []
+
+def main(argv=None):
+    return cli.main(PostgresEngine(), argv)          # your console script
+```
+
+Each engine keeps its connections in `.pythia/<engine>/connections.json`.
+That is never pythia for Oracle's `.pythia/connections.json`, so one project
+can use both safely.
+
+## Tests (no database, no driver)
+
+```bash
+python tests/test_core.py
+python tests/test_cli.py
+python tests/test_read.py
+python tests/test_gate.py
+python tests/test_harness.py
+python tests/test_doors.py
+python tests/test_release.py
+python tests/test_lease.py
+python tests/test_lint.py
+python tests/test_family.py     # several engines in one project, with two fakes
+```
+
+CI runs them on Ubuntu, Windows and macOS, Python 3.9 and 3.13. Its
+`family` job also installs pythia for Oracle and the three engines into one
+project and runs `tests/family_check.py`: every install keeps the others'
+hooks and blocks, a second run changes nothing, each doctor passes, each
+guard and answer hook acts for its own engine only.
+
+## License
+
+MIT

pythia_core-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pythia-core"
+version = "0.1.0"
+description = "Shared core of the pythia family: the engine contract, connection resolution and the write gate every pythia-<engine> package drives."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+# stdlib only, by contract (tests/test_core.py): a driver belongs to the
+# engine package that needs it, so nobody installs one they do not use
+dependencies = []
+keywords = ["database", "agent-skills", "sql", "postgresql", "sql-server", "mongodb"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development",
+]
+
+[project.urls]
+Repository = "https://github.com/thaildhe172591/pythia-core"
+Changelog = "https://github.com/thaildhe172591/pythia-core/blob/main/CHANGELOG.md"
+Issues = "https://github.com/thaildhe172591/pythia-core/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

pythia_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pythia_core-0.1.0/src/pythia_core/__init__.py

@@ -0,0 +1,6 @@
+"""pythia-core: the part of pythia that is the same for every database.
+
+Engine packages (pythia-postgres first) build on it; see DESIGN.md. pythia
+for Oracle is a separate, self-contained tool and does not use this package.
+"""
+__version__ = "0.1.0"     # kept equal to pyproject.toml (tests/test_core.py)