mainsequence-metatable 0.1.0__tar.gz

mainsequence_metatable-0.1.0/.agents/skills/client/metatables-meta-tables/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: metatables-meta-tables
+description: "Author and query application tables through the installed MetaTables Python client. Covers SQLAlchemy contracts, external registration and governed SQL in consuming applications. Excludes client-library implementation, API/server changes and repository tooling."
+---
+
+# MetaTables client contracts and queries
+
+## Client scope
+
+Apply this skill to applications that consume the installed `metatables` Python
+client. It covers application-facing models and workflows. Client-library
+implementation, this repository's development/release tooling, and API internals
+have separate ownership.
+
+In a copied skill, resolve the `docs/` and `examples/` paths below relative to
+this skill's `references/` directory. The client CLI bundles the matching version's
+guides and examples there, including their linked documents. In the MetaTables
+source checkout, read the same paths from the repository root.
+
+Use the installed `metatables` client. The API catalog resource, the client
+resource model, and a SQLAlchemy authoring class have different responsibilities.
+Read `docs/concepts/architecture.md` and
+`docs/concepts/table-contracts-and-lifecycle.md` before choosing a workflow.
+
+For actual endpoint support, consult `docs/reference/capabilities.md`. Do not
+infer API support from the presence of an inherited client method. Platform
+identity and Git source facts use SDK imports. Table operations use the client's automatic hosted discovery or an explicit
+`METATABLES_API_URL`; the API selects the effective DataSource. See
+`docs/client/installation-and-connection.md`. Local development runs the same API
+with SQLite behind it; ordinary clients never open local table files. Local
+workspaces use one SQLite database for system and user tables per checkout/branch.
+Settings explicitly initializes or selects the runtime DataSource in both modes;
+startup never runs Alembic. See `docs/operations/catalog-migrations.md`.
+
+## Authoring decisions
+
+Establish row meaning, ownership, DataSource, physical schema/name, namespace,
+logical identifier, time grain if any, and foreign-key targets from the task and
+existing models. Clarify only unresolved choices that materially change the
+contract. Preserve the user's existing authorization and scope.
+
+- Managed application tables use `PlatformManagedMetaTable` or
+  `PlatformTimeIndexMetaTable` and the migration-provider workflow. Use the
+  [migrations skill](../metatables-migrations/SKILL.md) for creation and
+  evolution.
+- Existing externally owned tables use `register_external_sqlalchemy_model` with
+  their actual physical binding. Registration does not create the physical table;
+  see `docs/client/register-existing-tables.md` and `examples/external_table.py`.
+- `backend_managed` is a separate low-level API provisioning intent. Do not use it
+  as a substitute for ordinary managed application-table migrations.
+
+A UID is catalog identity. An optional identifier is unique in the connected catalog.
+A physical binding is DataSource + schema + table name. A catalog
+namespace groups resources and grants; it is not a SQL schema. Contract hashes
+are fingerprints, not table identity. See `docs/concepts/identity-and-scope.md`.
+
+## SQLAlchemy contract rules
+
+Use `examples/tables.py` as the tested pattern. Declare an explicit
+application-prefixed physical name with `schema_table_name(app, concept)`, a
+stable logical identifier, and an intention-rich `__metatable_description__`.
+Give columns useful `info={"label": ..., "description": ...}` metadata. Explain
+row grain and downstream meaning rather than repeating types.
+
+Keep foreign keys and indexes in SQLAlchemy metadata. Reference explicit physical
+names using `ForeignKey`/`ForeignKeyConstraint`; do not ask users to hand-author
+catalog target UIDs. Alembic renders physical DDL; catalog finalization introspects
+it. The client column contract does not itself serialize all FK/index metadata.
+
+For a `PlatformTimeIndexMetaTable`, declare time first in `__index_names__`, the
+full observation grain, and a timezone-aware time column. Prefer `time_index` as
+the time name for updater compatibility. The mixin automatically creates the
+unique index for the full grain; add only additional lookup indexes. Declare
+`__cadence__` when the stable observation interval is known.
+
+Physical names remain stable across schema changes. Evolve through new Alembic
+revisions; do not recompute identity from columns or rewrite applied history.
+
+## Queries and mutations
+
+Read `docs/client/query-and-mutate.md` and `examples/query.py`. Use
+`compile_sqlalchemy_statement` with bound parameters and explicit catalog table
+scope/access. Resolve registered physical names instead of guessing them from
+identifiers. Use the documented expression subset and scopes for actual read/write targets.
+Arbitrary DDL, system relations, multiple statements and indirect view/trigger
+writes are unsupported by the governed SQL API.
+
+Column search is supported. Description search, search-index refresh, and
+legacy convenience sharing/label actions are not supported API workflows.
+Use `get_access`, `set_access` and `revoke_access` for supported Reader/Writer
+sharing. Labels can be changed through the documented table PATCH path. Authorization is
+owned by the API catalog; see `docs/concepts/permissions-namespaces-labels.md`.
+
+Updater output rollback uses `TimeIndexMetaTable.delete_after_date` with an
+inclusive time cutoff and explicit dimension/coordinate scope when appropriate.
+A null cutoff requires a scope. Do not replace that workflow with ad hoc SQL.
+Deletion/cascade requires edit access, relevant protection checks, and explicit
+cascade intent; it is not an administrator-role bypass or migration repair.
+
+## Validation
+
+Check authored models, normalization, physical naming, FK targets, and time grain
+against the actual workflow. Run relevant behavior tests and the example tests.
+State whether validation used local contracts, a disposable database, or a
+configured service. Never claim an end-to-end deployment result from an import
+check. Preserve published contracts unless the task authorizes their evolution.

mainsequence_metatable-0.1.0/.agents/skills/client/metatables-migrations/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: metatables-migrations
+description: "Create and evolve managed application tables through Alembic migration providers with the installed MetaTables Python client. Covers provider scope, scaffolding, offline revisions, approved API-side execution, and reservation or finalization failures. Excludes API catalog migrations, client-library implementation, API/server changes and repository tooling."
+---
+
+# MetaTables client application migrations
+
+## Client scope
+
+Apply this skill to applications that consume the installed `metatables` Python
+client. It covers application-facing models and workflows. Client-library
+implementation, this repository's development/release tooling, and API internals
+have separate ownership.
+
+In a copied skill, resolve the `docs/` and `examples/` paths below relative to
+this skill's `references/` directory. The client CLI bundles the matching version's
+guides and examples there, including their linked documents. In the MetaTables
+source checkout, read the same paths from the repository root.
+
+Read `docs/client/define-and-migrate-tables.md`,
+`docs/concepts/table-contracts-and-lifecycle.md`, and the tested
+`examples/tables.py`. Managed authoring is migration-first: define SQLAlchemy
+models, select a provider, author a revision, then let the API apply it and
+finalize the catalog bindings. Use the
+[table skill](../metatables-meta-tables/SKILL.md) for contract design.
+
+Check `docs/reference/capabilities.md` and `metatables migrations --help` before
+promising a command. The API's own catalog migrations are a separate history that
+an admin runs from Settings; see `docs/operations/catalog-migrations.md`. They
+are not application-provider revisions.
+
+## Source and runtime context
+
+- The API selects its active runtime DataSource. Do not accept a caller-supplied
+  DataSource, database URL, revision path, or branch override.
+- Git source facts come from the current checkout through the SDK. Do not ask the
+  user to choose a branch or environment for a migration.
+- An explicit `METATABLES_API_URL` selects an API endpoint, not a branch or a
+  storage binding. See `docs/client/installation-and-connection.md`.
+- Provider aliases are API deployment configuration, not Python import paths
+  supplied by a request.
+
+## Author the migration
+
+1. Define the SQLAlchemy models with stable, application-prefixed physical names.
+2. Identify one provider module, migration namespace, target `MetaData`, model
+   registry, and prefixed Alembic version-table binding.
+3. Keep provider scope explicit. Do not scan all imported models or installed
+   packages.
+4. Scaffold only when the application has no provider yet:
+
+   ```bash
+   metatables migrations scaffold \
+     --package ledger \
+     --module ledger.migrations \
+     --namespace ledger \
+     --base ledger.tables:Base \
+     --metadata ledger.tables:Base.metadata
+   ```
+
+5. Edit the generated `registry.py` so it returns exactly the models owned by
+   that migration stream. Scaffolding alone selects no models and creates no
+   tables.
+6. Create and review an offline Alembic revision:
+
+   ```bash
+   metatables migrations revision \
+     --provider ledger.migrations:migration \
+     --no-autogenerate \
+     --message "create ledger"
+   ```
+
+Use `--source-root` and `--code-repository-root` when the application does not
+use the default `src/` layout. Keep applied revisions immutable; add a new
+revision for every later schema change.
+
+## Execute through the approved runtime
+
+Client-side `current`, `upgrade`, `downgrade`, direct migration connections, and
+database autogeneration are unsupported. `--sqlalchemy-url` does not bypass that
+boundary.
+
+The API applies a provider through `POST /application-migrations/upgrade/`, which
+accepts only an alias listed in its `application_migration_providers`. The
+deployment must already install the reviewed provider code. The API reserves the
+provider's catalog rows, runs Alembic to the provider head, and finalizes the
+physical bindings. The caller needs Writer access to every existing provider
+table and cannot upload revisions, choose a database or target revision, or
+downgrade. See `docs/api/tables-and-migrations.md`.
+
+Use the application's tested setup entry point when one exists;
+`examples/scripts/setup_metatables.py` and `docs/client/tutorial.md` show the
+pattern. Do not replace it with direct model registration or an undocumented
+request body.
+
+## Lifecycle invariants
+
+- Provider tables and the Alembic registry are `platform_managed` +
+  `alembic_managed`.
+- Reservation precedes physical migration; reconciliation moves catalog rows
+  from `reserved` to `active`.
+- The registry is the provider root and has no parent. Provider tables bind to
+  that registry.
+- Physical identity is DataSource UID + physical schema + physical table name.
+  A logical identifier or contract hash does not replace it. See
+  `docs/concepts/identity-and-scope.md`.
+- Repeated setup reuses compatible bindings and applied revision history.
+- `.register()` is lifecycle plumbing, not the ordinary way to create an
+  application table. External registration cannot stand in for a managed
+  migration registry.
+
+## Failure handling
+
+Read `docs/operations/recovery-and-observability.md`.
+
+- If provider loading fails, verify the import path, model registry, metadata,
+  version-table binding, and installed `metatables` version.
+- If reservation fails, compare provider scope and physical identities before
+  changing code. Do not create a second catalog row for the same table.
+- If Alembic succeeds but finalization fails, physical DDL may already be
+  committed. Inspect every per-table result and the actual schema before
+  retrying.
+- Treat an uncertain journal outcome as reconciliation work. Do not blindly
+  retry, stamp, downgrade, cascade-delete, or register around it.
+- Destructive catalog deletion is not migration recovery and never bypasses
+  schema-management protection.
+
+## Validation
+
+Verify provider scope, revision content, the approved-provider configuration,
+repeat execution, and final active bindings. Report separately what was checked
+offline and what was exercised against a configured API.

mainsequence_metatable-0.1.0/.agents/skills/client/metatables-time-index-table-updates/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: metatables-time-index-table-updates
+description: "Build or review TimeIndexTableUpdater producers, configuration hashing, dependencies, incremental frames and table readers in applications using the MetaTables Python client. Excludes client-library implementation, API routes, scheduling and runtime administration."
+---
+
+# MetaTables client time-index producers
+
+## Client scope
+
+Apply this skill to applications that consume the installed `metatables` Python
+client. It covers application-facing models and workflows. Client-library
+implementation, this repository's development/release tooling, and API internals
+have separate ownership.
+
+In a copied skill, resolve the `docs/` and `examples/` paths below relative to
+this skill's `references/` directory. The client CLI bundles the matching version's
+guides and examples there, including their linked documents. In the MetaTables
+source checkout, read the same paths from the repository root.
+
+Read `docs/client/build-an-updater.md`,
+`docs/concepts/time-index-tables-and-updates.md`, and the tested
+`examples/updater.py`. Use `docs/client/read-existing-time-index-tables.md` and
+`examples/reader.py` for consumers that only need existing output.
+
+The storage contract is a `PlatformTimeIndexMetaTable` SQLAlchemy class. The
+producer is a `TimeIndexTableUpdater`; the API record is `TimeIndexTableUpdate`.
+Use the [table skill](../metatables-meta-tables/SKILL.md) for storage design and the
+[migrations skill](../metatables-migrations/SKILL.md) for table evolution. API
+route behavior is documented in `docs/api/time-index-and-updates.md` and supported
+capabilities in `docs/reference/capabilities.md`.
+
+## Establish the contract
+
+Infer dataset meaning, time grain, identity dimensions, output columns, upstream
+choices, first-run/backfill bounds, and whether identity must be preserved from
+the task and existing code. Clarify only unresolved choices that change the
+published contract. Keep storage description, namespace, identifier, cadence,
+columns, and FK/index metadata on the authoring model, not the updater config.
+Use intention-rich table and column descriptions; see `examples/tables.py`.
+
+Migrate and bind the output class before constructing the producer. Pass explicit
+`config` and `output_table`; do not create/register tables inside `update()`.
+The optional `hash_namespace` separates producer identities, **not output tables**.
+A test namespace alone does not protect shared physical rows. Use a disposable
+output binding or explicitly authorized row scope for mutation tests.
+
+## Configuration and dependencies
+
+Use `TimeIndexTableUpdateConfig` with described `Field` values and realistic
+examples where useful. Fields affect `update_hash` by default. Values that change
+output, source selection, dependencies, or producer scope must stay hashed.
+Keep implementation constants in `ClassVar` or runtime configuration. For a
+strictly descriptive Pydantic field, the supported exclusion is
+`json_schema_extra={"hash_excluded": True}`; do not invent alternate markers.
+
+The client owns configuration version 2 serialization/validation. A configured
+upstream authoring class hashes by its bound table UID and must already be bound.
+`output_table` is a constructor contract, not an ordinary config field. Removed
+configuration forms and `test_node` are unsupported; use explicit namespaces.
+
+Declare a deterministic `dependencies()` mapping. Executable dependencies are
+other updater instances; read-only dependencies are `TimeIndexTableRef` objects.
+References contribute lineage and reads without executing a producer. Do not
+construct a changing dependency graph inside `update()`.
+
+## Incremental output
+
+Use `UpdateStatistics` to determine the next interval, including a first-run
+fallback. Return rows matching the bound storage contract and avoid full-history
+writes unless the task explicitly needs them.
+
+Every non-empty frame must put `time_index` first and use exactly
+`datetime64[ns, UTC]` for that index level. Construct it explicitly with
+`pd.DatetimeIndex(..., dtype="datetime64[ns, UTC]")`; timestamp normalization alone
+can retain microsecond precision. For a MultiIndex, declare all dimension levels
+in storage-grain order and keep payload columns separate.
+
+The time-index mixin creates the unique index for the complete observation grain.
+Do not duplicate it manually. Additional indexes and foreign keys belong in
+SQLAlchemy/Alembic metadata and should use application-prefixed physical names.
+Changing a table contract requires a new migration, not an updater config field.
+
+## Tail repair
+
+Use the documented `TimeIndexMetaTable.delete_after_date` workflow for updater
+output rollback. The cutoff is inclusive. Supply `dimension_filters` to select
+value sets or `index_coordinates` to select exact streams. A null cutoff requires
+one of those scopes and deletes all rows only in that scope. An unscoped null
+cutoff must fail. Do not replace this workflow with direct connections, SQL,
+truncation, or private endpoints.
+
+The API route is `/time-index-meta-tables/{uid}/delete-after-date/`; deployment
+prefixes belong in `METATABLES_API_URL`. See `docs/client/query-and-mutate.md`.
+
+## Review and verification
+
+Check hashing effects, deterministic dependencies, incremental bounds, configured
+output identity, time dtype, dimension order, columns, and tail-delete scope.
+Use the relevant updater tests and executable example tests. Report what was
+actually exercised: pure frame logic, disposable storage, or a configured API.
+Do not claim a scheduling/release workflow from producer tests. If a published
+contract decision remains unknown, resolve that decision while continuing any
+independent authorized work.

mainsequence_metatable-0.1.0/.mainsequence/workflows/metatables-api.yaml

@@ -0,0 +1,10 @@
+api_version: "2.3.0"
+name: metatables-api
+resources:
+  - key: metatables-api
+    kind: fastapi
+    spec:
+      source_path: api/metatables/main.py
+      automatic_deployment: true
+      min_scale: 1
+      revision_retention_count: 3

mainsequence_metatable-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MainSequence GmbH
+
+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.

mainsequence_metatable-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include alembic.ini mkdocs.yml uv.lock compose.database-tests.yml
+include .mainsequence/workflows/metatables-api.yaml
+include api/metatables/configuration.yaml
+recursive-include docs *.md *.json *.py *.csv *.mako *.svg
+recursive-include examples *.md *.json *.py *.csv *.mako
+recursive-include scripts *.py
+recursive-include tests *.py *.json Dockerfile Dockerfile.dockerignore
+graft .agents/skills/client
+global-exclude __pycache__ *.py[cod]

mainsequence_metatable-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: mainsequence-metatable
+Version: 0.1.0
+Summary: Main Sequence MetaTables Python client and standalone API
+Author-email: Main Sequence GmbH <dev@main-sequence.io>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mainsequence-projects/MetaTables
+Project-URL: Issues, https://github.com/mainsequence-projects/MetaTables/issues
+Project-URL: Documentation, https://potential-doodle-wn39mnm.pages.github.io/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mainsequence[server]<9,>=8.1.25
+Requires-Dist: alembic<2,>=1.18
+Requires-Dist: cachetools
+Requires-Dist: cryptography<51,>=46
+Requires-Dist: fastapi<1,>=0.110
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: keyring<26,>=25
+Requires-Dist: numpy
+Requires-Dist: opentelemetry-api
+Requires-Dist: opentelemetry-exporter-otlp
+Requires-Dist: opentelemetry-sdk
+Requires-Dist: pandas
+Requires-Dist: psutil
+Requires-Dist: psycopg2-binary<3,>=2.9
+Requires-Dist: pyodbc<6,>=5
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: pyyaml
+Requires-Dist: requests>=2.33.0
+Requires-Dist: sqlalchemy<3,>=2
+Requires-Dist: psycopg[binary]<4,>=3.2
+Requires-Dist: structlog
+Requires-Dist: tqdm<5,>=4.66
+Requires-Dist: typer<1,>=0.12
+Requires-Dist: urllib3>=2.7.0
+Requires-Dist: uvicorn==0.52.4
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: ruff>=0.14; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+Requires-Dist: packaging>=24.2; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Provides-Extra: mysql
+Requires-Dist: PyMySQL[rsa]<1.2,>=1.1.1; extra == "mysql"
+Provides-Extra: mssql
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/branding/metatables.svg" alt="MetaTables logo" width="80" height="80" />
+</p>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/branding/mainsequence-dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/branding/mainsequence-light.png" />
+    <img src="docs/assets/branding/mainsequence-light.png" alt="Main Sequence logo" width="280" />
+  </picture>
+</p>
+
+# MetaTables
+
+MetaTables is a Python client and API for describing, registering, querying, and
+updating database tables through a governed catalog.
+
+Its PyPI distribution is `mainsequence-metatable`; imports and the command are
+named `metatables`. See [publishing](docs/contributing/releasing.md) for the
+release process and the current published SDK prerequisite.
+
+The **Python client** provides SQLAlchemy table definitions, application-table
+migrations, query objects, time-index readers and update processes,
+and the `metatables` command. The **MetaTables API** stores table identities,
+contracts, permissions, and update history, and executes authorized operations on
+physical databases.
+
+A catalog record describes a table; the table's rows live in its DataSource.
+The Main Sequence SDK supplies platform authentication, identity, repository
+context, and platform Secrets. MetaTables owns its table behavior and storage
+adapters. Local development runs the same API with one SQLite database for system metadata and table rows. Initialize it explicitly
+through Settings; startup never runs Alembic.
+
+## Start here
+
+- [Install and connect](docs/client/installation-and-connection.md), including the current local SDK prerequisite.
+- [Understand the concepts](docs/concepts/architecture.md) and [identity and scope](docs/concepts/identity-and-scope.md).
+- [Understand the security model](docs/security/index.md): administration, Reader/Writer table ownership, sharing, and implementation status.
+- [Follow the market-data tutorial](docs/client/tutorial.md) with its complete examples folder.
+- [Define and migrate managed tables](docs/client/define-and-migrate-tables.md).
+- [Register existing tables](docs/client/register-existing-tables.md).
+- [Manage DataSources](docs/concepts/data-sources.md): PostgreSQL, MySQL and MSSQL configuration, driver setup, examples and current operation limits.
+- [Build an updater](docs/client/build-an-updater.md) or [read an existing time-index table](docs/client/read-existing-time-index-tables.md).
+- [Run the API locally](docs/operations/local-runtime.md) or [operate a hosted API](docs/operations/hosted-runtime.md).
+
+The [documentation index](docs/index.md) separates client, API, operations, and
+contributor guides. The [capability reference](docs/reference/capabilities.md)
+records implemented and unavailable operations, including inherited methods and
+CLI commands. Runnable guide assets live in [examples](examples/README.md).
+
+## Client skills
+
+Copy the installed client's skills into a consuming application explicitly:
+
+```bash
+metatables copy-metatables-skills --path /path/to/application
+```
+
+The command uses the Main Sequence SDK helper, writes to
+`.agents/skills/metatables/`, and records the client version. It works without
+login or an API. Use `--dry-run` to preview the copy, or put global `--json` before
+the command for structured output. See [installation](docs/client/installation-and-connection.md#copy-client-skills-into-an-application)
+for refresh behavior and the bundled references.
+
+## Development
+
+Python 3.13 or newer is required. After installing the compatible local SDK:
+
+```bash
+python -m pip install -e '.[dev,docs]'
+python -m metatables.sdk_compat
+python -m pytest -q
+python -m scripts.check_project
+mkdocs build --strict
+```
+
+Physical PostgreSQL checks use explicitly configured disposable databases;
+see [testing](docs/contributing/testing.md). No separate frontend is needed to
+use the Python client or run the API.
+
+## License
+
+MetaTables is licensed under the MIT License. See [LICENSE](LICENSE) for the
+complete terms.

mainsequence_metatable-0.1.0/README.md

@@ -0,0 +1,83 @@
+<p align="center">
+  <img src="docs/assets/branding/metatables.svg" alt="MetaTables logo" width="80" height="80" />
+</p>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/branding/mainsequence-dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/branding/mainsequence-light.png" />
+    <img src="docs/assets/branding/mainsequence-light.png" alt="Main Sequence logo" width="280" />
+  </picture>
+</p>
+
+# MetaTables
+
+MetaTables is a Python client and API for describing, registering, querying, and
+updating database tables through a governed catalog.
+
+Its PyPI distribution is `mainsequence-metatable`; imports and the command are
+named `metatables`. See [publishing](docs/contributing/releasing.md) for the
+release process and the current published SDK prerequisite.
+
+The **Python client** provides SQLAlchemy table definitions, application-table
+migrations, query objects, time-index readers and update processes,
+and the `metatables` command. The **MetaTables API** stores table identities,
+contracts, permissions, and update history, and executes authorized operations on
+physical databases.
+
+A catalog record describes a table; the table's rows live in its DataSource.
+The Main Sequence SDK supplies platform authentication, identity, repository
+context, and platform Secrets. MetaTables owns its table behavior and storage
+adapters. Local development runs the same API with one SQLite database for system metadata and table rows. Initialize it explicitly
+through Settings; startup never runs Alembic.
+
+## Start here
+
+- [Install and connect](docs/client/installation-and-connection.md), including the current local SDK prerequisite.
+- [Understand the concepts](docs/concepts/architecture.md) and [identity and scope](docs/concepts/identity-and-scope.md).
+- [Understand the security model](docs/security/index.md): administration, Reader/Writer table ownership, sharing, and implementation status.
+- [Follow the market-data tutorial](docs/client/tutorial.md) with its complete examples folder.
+- [Define and migrate managed tables](docs/client/define-and-migrate-tables.md).
+- [Register existing tables](docs/client/register-existing-tables.md).
+- [Manage DataSources](docs/concepts/data-sources.md): PostgreSQL, MySQL and MSSQL configuration, driver setup, examples and current operation limits.
+- [Build an updater](docs/client/build-an-updater.md) or [read an existing time-index table](docs/client/read-existing-time-index-tables.md).
+- [Run the API locally](docs/operations/local-runtime.md) or [operate a hosted API](docs/operations/hosted-runtime.md).
+
+The [documentation index](docs/index.md) separates client, API, operations, and
+contributor guides. The [capability reference](docs/reference/capabilities.md)
+records implemented and unavailable operations, including inherited methods and
+CLI commands. Runnable guide assets live in [examples](examples/README.md).
+
+## Client skills
+
+Copy the installed client's skills into a consuming application explicitly:
+
+```bash
+metatables copy-metatables-skills --path /path/to/application
+```
+
+The command uses the Main Sequence SDK helper, writes to
+`.agents/skills/metatables/`, and records the client version. It works without
+login or an API. Use `--dry-run` to preview the copy, or put global `--json` before
+the command for structured output. See [installation](docs/client/installation-and-connection.md#copy-client-skills-into-an-application)
+for refresh behavior and the bundled references.
+
+## Development
+
+Python 3.13 or newer is required. After installing the compatible local SDK:
+
+```bash
+python -m pip install -e '.[dev,docs]'
+python -m metatables.sdk_compat
+python -m pytest -q
+python -m scripts.check_project
+mkdocs build --strict
+```
+
+Physical PostgreSQL checks use explicitly configured disposable databases;
+see [testing](docs/contributing/testing.md). No separate frontend is needed to
+use the Python client or run the API.
+
+## License
+
+MetaTables is licensed under the MIT License. See [LICENSE](LICENSE) for the
+complete terms.

mainsequence_metatable-0.1.0/alembic.ini

@@ -0,0 +1,3 @@
+[alembic]
+script_location = api/backend/migrations
+

mainsequence_metatable-0.1.0/api/__init__.py

@@ -0,0 +1,3 @@
+from metatables.sdk_compat import require_sdk_capabilities
+
+require_sdk_capabilities(server=True)

mainsequence_metatable-0.1.0/api/app/auth/__init__.py

@@ -0,0 +1 @@
+"""Inbound FastAPI caller authentication."""