Metadata-Version: 2.4
Name: muscles
Version: 1.1.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

Muscles is the 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).

### Keyed Dependencies

For extension points whose providers are selected by a stable string key, the
core dependency API supports a fallback and priority-ordered registrations:

```python
from muscles import Dependency

Dependency.provide("access.user_directory", AccountsUserDirectory)

@Dependency.init("access.user_directory", priority=10)
class WorkspaceUserDirectory:
    ...

directory = Dependency.get("access.user_directory")
```

`Dependency.get()` instantiates the highest-priority provider, falling back to
the default when no candidate is registered. `Dependency.get_candidates()`
returns providers in priority order for callers that can try several
implementations; `Dependency.list()` reports registrations and the selected
provider. Equal top priorities are reported as ambiguous. Existing type-based
dependency registration and injection remain available.

## 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 framework packages are distributed through PyPI. Install the core
framework with:

```bash
pip install "muscles>=1.0.0,<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.0,<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
```

