muscles 1.0.0__tar.gz

muscles-1.0.0/PKG-INFO

@@ -0,0 +1,420 @@
+Metadata-Version: 2.4
+Name: muscles
+Version: 1.0.0
+Summary: Muscles framework core
+License: MIT
+Author: Denis B.
+Author-email: denis@butko.info
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: dnspython (==2.6.1)
+Requires-Dist: jsonschema (>=4.18,<5)
+Requires-Dist: pyyaml (>=6.0.0,<6.1.0)
+Requires-Dist: watchdog (>=4.0.0,<5.0.0)
+Project-URL: Documentation, https://github.com/butkoden/muscles#readme
+Project-URL: Homepage, https://github.com/butkoden/muscles
+Project-URL: PyPI, https://pypi.org/project/muscles/
+Project-URL: Repository, https://github.com/butkoden/muscles
+Project-URL: Releases, https://github.com/butkoden/muscles/releases
+Project-URL: muscles-data, https://pypi.org/project/muscles-data/
+Project-URL: muscles-ai, https://pypi.org/project/muscles-ai/
+Project-URL: muscles-documents, https://pypi.org/project/muscles-documents/
+Project-URL: muscles-benchmarks, https://pypi.org/project/muscles-benchmarks/
+Description-Content-Type: text/markdown
+
+# Muscles Core (Release Candidate)
+
+Muscles is the release-candidate framework core. The core package contains the
+application lifecycle, configuration, shared schema objects, routing tree and
+strategy interface. HTTP, ASGI and CLI packages reuse these primitives instead
+of implementing their own framework model.
+
+## Application Shape
+
+`muscles-cli`, `muscles-asgi` and `muscles-wsgi` use the same core application
+model. The selected runtime supplies a strategy; `Context` dispatches through
+it:
+
+```python
+from muscles import ApplicationMeta, Configurator, Context
+from muscles.asgi import AsgiStrategy
+
+
+class App(metaclass=ApplicationMeta):
+    config = Configurator(obj={"main": {"HOST": "0.0.0.0", "PORT": "8080"}})
+    context = Context(AsgiStrategy, params={})
+
+    def run(self, *args):
+        return self.context.execute(*args, shutup=True)
+```
+
+For WSGI or CLI, use the corresponding strategy from `muscles.wsgi` or
+`muscles.cli`. The runtime-specific package owns route declaration and server
+startup; core does not require an extra `wsgi_runtime()` or `runtime.rest_api()`
+factory. See [docs/golden-path.md](docs/golden-path.md).
+
+## Packages
+
+- `muscles` - core classes, schemas, routing and application metaclass.
+- `muscles-wsgi` - WSGI runtime, pages, REST API and Swagger UI.
+- `muscles-asgi` - ASGI runtime with the same routing and REST API model.
+- `muscles-cli` - console command strategy built on the same route/group idea.
+- `muscles-jsonrpc` - JSON-RPC projection for core actions.
+- `muscles-sse` - Server-Sent Events projection for streaming actions.
+- `muscles-mcp` - Model Context Protocol projection for AI tools.
+- `muscles-data` - typed data ports, resource runtime and migration registry.
+- `muscles-data-sql` - native SQL connections, repositories and SQL migrations.
+- `muscles-data-sqlalchemy` - SQLAlchemy adapter for `muscles-data` resources.
+- `muscles-otel` - optional lifecycle telemetry hooks and tracer provider.
+- `muscles-documents` - document loading, parsing, chunking and sync actions.
+- `muscles-ai` - read-only AI/RAG actions and runtime contracts.
+- `muscles-benchmarks` - benchmark and regression suite for the ecosystem.
+- `muscular-example` - layered learning examples for Muscles applications.
+
+## How Packages Fit Together
+
+`muscles` is the core contract. Runtime packages such as `muscles-asgi`,
+`muscles-wsgi` and `muscles-cli` project the same app model into a concrete
+transport. Extension packages such as `muscles-otel`, `muscles-data`,
+`muscles-data-sql`, `muscles-documents` and `muscles-ai` add services, actions and diagnostics
+through the package lifecycle:
+
+```python
+from muscles import install_package, inspect_application, doctor_application
+from muscles.otel import OtelPackage
+
+app = App()
+tracer = install_package(app, {"enabled": True}, OtelPackage())
+
+contract = inspect_application(app)
+doctor = doctor_application(app)
+```
+
+Use the `DependencyContainer` for live objects that app code resolves at
+runtime. Use `ApplicationRegistry` for metadata that tools can inspect: routes,
+actions, package capabilities, doctor checks and generator providers. In plain
+terms: the container is for running the app, the registry is for understanding
+the app.
+
+More detail: [docs/package-lifecycle.md](docs/package-lifecycle.md).
+
+## Repository Map
+
+Core and runtimes:
+
+- [`muscles`](https://github.com/butkoden/muscles) - framework core and canonical documentation.
+- [`muscles-asgi`](https://github.com/butkoden/muscles-asgi) - ASGI HTTP/API runtime.
+- [`muscles-wsgi`](https://github.com/butkoden/muscles-wsgi) - WSGI HTTP/API runtime.
+- [`muscles-cli`](https://github.com/butkoden/muscles-cli) - CLI runtime, project scaffolding and inspection commands.
+
+Protocol projections:
+
+- [`muscles-jsonrpc`](https://github.com/butkoden/muscles-jsonrpc) - JSON-RPC 2.0 projection over actions.
+- [`muscles-sse`](https://github.com/butkoden/muscles-sse) - SSE delivery for `StreamResult` action output.
+- [`muscles-mcp`](https://github.com/butkoden/muscles-mcp) - MCP tools/resources generated from Muscles contracts.
+
+Framework extensions:
+
+- [`muscles-data`](https://github.com/butkoden/muscles-data) - typed ports, resource runtime, policies and migration registry.
+- [`muscles-data-sql`](https://github.com/butkoden/muscles-data-sql) - native SQL connections and migrations; the repository is `muscles-data-sql`.
+- [`muscles-data-sqlalchemy`](https://github.com/butkoden/muscles-data-sqlalchemy) - SQLAlchemy-backed `muscles-data` resource adapter.
+- [`muscles-migrations`](https://github.com/butkoden/muscles-migrations) - migration compatibility imports.
+- [`muscles-permissions`](https://github.com/butkoden/muscles-permissions) - permission catalog and policy contracts.
+- [`muscles-otel`](https://github.com/butkoden/muscles-otel) - optional lifecycle telemetry hooks for package, strategy and action execution.
+- [`muscles-documents`](https://github.com/butkoden/muscles-documents) - document source ingestion, parsing, chunking and sync planning.
+- [`muscles-ai`](https://github.com/butkoden/muscles-ai) - AI/RAG actions that can use document and data integrations.
+
+Support repositories:
+
+- [`muscles-benchmarks`](https://github.com/butkoden/muscles-benchmarks) - golden-path benchmarks and regression checks.
+- [`muscular-example`](https://github.com/butkoden/muscular-example) - layered example application.
+- [`muscles-landing`](https://github.com/butkoden/muscles-landing) - product site/application built on Muscles.
+- [`muscular-asgi`](https://github.com/butkoden/muscular-asgi) - deprecated ASGI compatibility package.
+
+## Installation
+
+The release-candidate packages are distributed through PyPI. Install the core
+framework with:
+
+```bash
+pip install "muscles>=1.0.0rc5,<2.0.0"
+```
+
+For local development, source checkouts and the full ecosystem matrix, see
+[docs/installation.md](docs/installation.md).
+
+Installation matrix:
+
+- core only: `pip install "muscles>=1.0.0rc5,<2.0.0"`
+- ASGI runtime: `pip install muscles-asgi`
+- WSGI runtime: `pip install muscles-wsgi`
+- CLI tooling: `pip install muscles-cli`
+- JSON-RPC projection: install `muscles-jsonrpc` from PyPI
+- SSE projection: install `muscles-sse` from PyPI
+- MCP projection: `pip install muscles-mcp`
+- Data contracts: `pip install muscles-data`
+- Native SQL: `pip install muscles-data-sql`
+- SQLAlchemy resource adapter: `pip install muscles-data-sqlalchemy`
+- OTel extension: `pip install muscles-otel`
+- documents extension: `pip install muscles-documents`
+- AI extension: `pip install muscles-ai`
+- full/dev (source checkouts): clone all repositories and use `PYTHONPATH` with sibling `src` paths.
+
+More detail: [docs/installation.md](docs/installation.md).
+Repository ownership map: [docs/repositories.md](docs/repositories.md).
+
+Core documentation:
+
+- English: [docs/doc.md](docs/doc.md)
+- Russian: [docs/doc.ru.md](docs/doc.ru.md)
+- Framework package lifecycle: [docs/package-lifecycle.md](docs/package-lifecycle.md)
+- Public API reference: [docs/public-api.md](docs/public-api.md)
+- Справочник публичного API: [docs/public-api.ru.md](docs/public-api.ru.md)
+
+## Naming
+
+Use `Muscles` as the public framework name. Keep `muscles` for the Python
+package/import name and `muscles-*` for official package identifiers.
+
+More detail: [docs/naming.md](docs/naming.md).
+
+## Positioning
+
+Muscles is a framework for a **single application model** that can be projected
+into multiple runtimes (WSGI, ASGI, CLI). It is not optimized for the shortest
+"one endpoint in five minutes" path. It is optimized for consistency: the same
+schemas, routing tree, lifecycle hooks and rules metadata stay reusable across
+transports.
+
+### When To Use Muscles
+
+- you need Web/API/CLI to share one domain model and metadata;
+- you want routing, schemas and rules to be declared once and reused;
+- you want AI-assisted changes to follow a stable project structure.
+
+### When Not To Use Muscles
+
+- you only need a tiny HTTP service with no shared model beyond one runtime;
+- your team prefers runtime-specific framework patterns per interface;
+- you need mature batteries-included admin/ORM stack out of the box.
+
+### FastAPI Relation
+
+FastAPI is a strong choice for API-first delivery speed. Muscles targets a
+different trade-off: one reusable model for API, pages and CLI workflows. These
+tools can coexist in a portfolio; Muscles should not claim production maturity
+or performance superiority without benchmark evidence.
+
+More detail: [docs/positioning.md](docs/positioning.md).
+The current project structure and conventions are documented in
+[docs/golden-path.md](docs/golden-path.md).
+
+## Golden Path Structure
+
+Use the official Muscles project structure as the default style for people and
+AI assistants:
+
+```text
+app/
+  application.py
+  config.py
+  domain/
+  schemas/
+  web/
+  api/
+  cli/
+  rules/
+  templates/
+  static/
+tests/
+```
+
+More detail: [docs/golden-path.md](docs/golden-path.md).
+Tutorial: [docs/golden-tutorial.md](docs/golden-tutorial.md).
+
+## Application Shape
+
+An application is usually a class with `ApplicationMeta`, a `Configurator` and a
+`Context` bound to a strategy:
+
+```python
+from muscles import ApplicationMeta, Configurator, Context
+from muscles.wsgi import WsgiStrategy
+
+
+class App(metaclass=ApplicationMeta):
+    config = Configurator(obj={"main": {"DEBUG": True}})
+    context = Context(WsgiStrategy, params={})
+
+    def run(self, *args):
+        return self.context.execute(*args, shutup=True)
+```
+
+`Context` owns lifecycle hooks and strategy execution. Keep it instance-local:
+lists of hooks and params must not be shared between app instances.
+
+## Routing
+
+The core routing tree lives in `muscles.core.schema.itinerary`. It is used as a
+generic structure for:
+
+- page routes;
+- REST API controllers/actions;
+- CLI groups and commands;
+- URL building and reverse lookup.
+
+The current implementation indexes routes by `(path, method)` and keeps a match
+cache. Static routes are checked before dynamic routes, so common paths avoid
+walking the whole tree. Duplicate route registration is idempotent by route
+name, which keeps repeated imports from making routing slower.
+
+More detail: [docs/architecture.md](docs/architecture.md).
+
+Backend primitives such as route groups, guards, middleware, exception mapping,
+Bearer JWT auth, CORS and response helpers are documented in
+[docs/backend-framework.md](docs/backend-framework.md).
+
+`BackendPipeline` is the shared execution contract for runtime adapters. It
+handles typed handler arguments, dependency resolution, guards, route-level
+security and middleware, while ASGI/WSGI keep protocol parsing and response
+serialization. `DependencyContainer` adds explicit `app`, `request` and
+`transient` scopes for integrations that need more structure than legacy global
+dependency registration.
+
+## Schemas And OpenAPI
+
+Schema classes (`Model`, `Collection`, `Column`, `String`, `Key`, request and
+response bodies) describe data once and can be reused by runtime strategies. The
+WSGI and ASGI packages read these structures to build OpenAPI automatically.
+
+More detail: [docs/schema.md](docs/schema.md).
+
+## Rules
+
+Decorators such as `@rules` are intended to attach access control and metadata
+to the same objects that routing uses. The important design rule is that a route,
+API action or command should carry its permissions and properties together with
+its schema, so every strategy can enforce or expose them consistently.
+
+Practical examples: [docs/value-objects-rules.md](docs/value-objects-rules.md).
+
+## Actions And Protocol Projections
+
+Actions are first-class application contracts in core. Declare an action once
+on a Muscles application instance, then let HTTP, CLI, MCP, JSON-RPC, SSE or
+other protocol projections call it through the same dispatcher:
+
+```python
+from muscles import ApplicationMeta, Context, ActionDispatcher
+
+
+class BookingApp(metaclass=ApplicationMeta):
+    context = Context(MyStrategy, transport="app", params={})
+
+
+app = BookingApp()
+
+
+@app.action(
+    name="bookings.create",
+    description="Create a booking request",
+    input_schema={
+        "type": "object",
+        "properties": {
+            "title": {"type": "string"},
+            "guest_count": {"type": "integer"},
+        },
+        "required": ["title"],
+    },
+    rules=["bookings.public_create"],
+    transports=["http", "cli", "mcp"],
+)
+def create_booking(payload, context):
+    return {"title": payload["title"], "transport": context.transport}
+
+
+result = ActionDispatcher(app).execute(
+    "bookings.create",
+    {"title": "Discovery call"},
+    transport="mcp",
+)
+```
+
+`inspect_application(app)` is the source of truth for discovery. Protocol
+packages should build tools, methods, routes or stream metadata from this
+contract and send execution back to `ActionDispatcher`. They should not keep a
+second validation, permissions or business model.
+
+The action registry is application-scoped. New protocol projections should avoid
+mutable module-level registries as their source of truth, because those leak
+state between app instances and tests.
+
+### Stream Results
+
+English:
+
+Streaming actions return `StreamResult(source=...)` with business
+`StreamEvent(type="progress" | "log" | "result" | "error", data=...)` items.
+The core contract is protocol-neutral: SSE heartbeat, MCP envelopes, JSON-RPC
+notifications and CLI progress lines are transport projections over the same
+events. Transports should preserve backpressure with bounded delivery and call
+`close()` on disconnect when the source supports it. Long-blocking sources must
+cooperate by unblocking the active `next()` call after `close()`.
+
+Русский:
+
+Streaming actions возвращают `StreamResult(source=...)` с business events
+`StreamEvent(type="progress" | "log" | "result" | "error", data=...)`.
+Core contract не зависит от протокола: SSE heartbeat, MCP envelopes,
+JSON-RPC notifications и CLI progress lines являются transport-проекциями одних
+и тех же событий. Transport должен сохранять backpressure через bounded delivery
+и вызывать `close()` при disconnect, если source это поддерживает. Долгие
+blocking sources должны быть cooperative: `close()` должен разблокировать
+активный `next()`.
+
+User docs:
+
+- English: [docs/action-contract.en.md](docs/action-contract.en.md)
+- Русский: [docs/action-contract.ru.md](docs/action-contract.ru.md)
+
+## AI Workflow
+
+Official AI-oriented instructions:
+
+- [docs/ai/AGENTS.md](docs/ai/AGENTS.md)
+- [docs/ai/cursor-rules.md](docs/ai/cursor-rules.md)
+- [docs/ai/copilot-instructions.md](docs/ai/copilot-instructions.md)
+
+## Production Deploy
+
+Umbrella guide: [docs/production-deploy.md](docs/production-deploy.md).
+
+## Benchmarks
+
+Benchmark docs: [docs/benchmarks.md](docs/benchmarks.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Development
+
+Run tests from each repository with its local `src` on `PYTHONPATH`:
+
+```bash
+PYTHONPATH=src python -m pytest -q
+```
+
+When testing an integration app that uses all packages from sibling checkouts:
+
+```bash
+PYTHONPATH=../muscles/src:../muscles-wsgi/src:../muscles-asgi/src:../muscles-cli/src:../muscles-jsonrpc/src:../muscles-sse/src:../muscles-mcp/src:../muscles-data/src:../muscles-data-sql/src:../muscles-data-sqlalchemy/src:../muscles-otel/src:../muscles-documents/src:../muscles-ai/src python -m pytest -q
+```
+