Metadata-Version: 2.4
Name: zephyrex
Version: 0.0.1
Summary: Extensible Python server framework with pluggable extensions, providers, and auto-generated SDK
Author-email: ZephyrexTechnologies <pypi@zephyrex.dev>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://git.zephyrex.dev/ZephyrexTechnologies/ServerFramework
Project-URL: Repository, https://git.zephyrex.dev/ZephyrexTechnologies/ServerFramework.git
Project-URL: Issues, https://git.zephyrex.dev/ZephyrexTechnologies/ServerFramework/issues
Keywords: api,server,framework,fastapi,extensions,graphql
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn
Requires-Dist: pydantic[email]>=2.0
Requires-Dist: ordered_set
Requires-Dist: alembic
Requires-Dist: aiosqlite
Requires-Dist: SQLAlchemy>=2.0
Requires-Dist: broadcaster
Requires-Dist: greenlet
Requires-Dist: strawberry-graphql[fastapi]
Requires-Dist: bcrypt
Requires-Dist: cryptography
Requires-Dist: pyjwt
Requires-Dist: httpx
Requires-Dist: colorama
Requires-Dist: defusedxml
Requires-Dist: distro
Requires-Dist: faker
Requires-Dist: filelock
Requires-Dist: inflect
Requires-Dist: loguru
Requires-Dist: networkx
Requires-Dist: numpy
Requires-Dist: python-dotenv
Requires-Dist: resolvelib
Requires-Dist: semver
Requires-Dist: stringcase
Requires-Dist: tldextract
Requires-Dist: tomli_w
Requires-Dist: toon-format
Requires-Dist: pyyaml
Provides-Extra: cache
Requires-Dist: redis>=4.2.0; extra == "cache"
Provides-Extra: mcp-server
Requires-Dist: mcp>=2.0; extra == "mcp-server"
Provides-Extra: acl-rbac
Provides-Extra: ai
Provides-Extra: ai-agents
Requires-Dist: croniter>=6.0.0; extra == "ai-agents"
Provides-Extra: ai-chains
Provides-Extra: ai-memories
Provides-Extra: ai-prompts
Provides-Extra: ai-tuning
Provides-Extra: audit-retention
Provides-Extra: auth-api-keys
Provides-Extra: auth-device-pairing
Provides-Extra: auth-invitations
Provides-Extra: auth-lockout
Provides-Extra: auth-magic-link
Provides-Extra: auth-marketplace
Provides-Extra: auth-merge
Provides-Extra: auth-mfa
Requires-Dist: pyotp>=2.8.0; extra == "auth-mfa"
Requires-Dist: qrcode[pil]>=7.4.0; extra == "auth-mfa"
Provides-Extra: auth-notifications
Provides-Extra: auth-privacy
Provides-Extra: auth-recovery-questions
Provides-Extra: auth-session
Provides-Extra: automotive
Provides-Extra: backup-restore
Provides-Extra: billing
Provides-Extra: book
Requires-Dist: ebooklib>=0.20; extra == "book"
Requires-Dist: markdown-it-py>=3.0; extra == "book"
Provides-Extra: cad
Provides-Extra: calendar
Provides-Extra: cloud
Requires-Dist: azure-core>=1.29.0; extra == "cloud"
Requires-Dist: azure-storage-blob>=12.19.0; extra == "cloud"
Requires-Dist: boto3>=1.26.0; extra == "cloud"
Requires-Dist: botocore>=1.29.0; extra == "cloud"
Requires-Dist: dropbox>=11.36.0; extra == "cloud"
Requires-Dist: google-api-core>=2.11.0; extra == "cloud"
Requires-Dist: google-auth>=2.0.0; extra == "cloud"
Requires-Dist: google-cloud-storage>=2.10.0; extra == "cloud"
Provides-Extra: conversations
Provides-Extra: crypto
Requires-Dist: bitcoinlib>=0.7.9; extra == "crypto"
Requires-Dist: eth-account>=0.13; extra == "crypto"
Requires-Dist: solana>=0.40; extra == "crypto"
Requires-Dist: solders>=0.29; extra == "crypto"
Requires-Dist: web3>=7.0; extra == "crypto"
Provides-Extra: database
Requires-Dist: gql>=3.4.0; extra == "database"
Requires-Dist: influxdb-client>=1.36.0; extra == "database"
Requires-Dist: influxdb>=5.3.0; extra == "database"
Requires-Dist: mysql-connector-python>=9.0.0; extra == "database"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "database"
Requires-Dist: pymongo>=4.0.0; extra == "database"
Requires-Dist: pyodbc>=5.0.0; extra == "database"
Requires-Dist: requests-toolbelt>=1.0.0; extra == "database"
Requires-Dist: requests>=2.28.0; extra == "database"
Provides-Extra: database-memory
Requires-Dist: redis>=4.2.0; extra == "database-memory"
Provides-Extra: ecommerce
Provides-Extra: email
Requires-Dist: aiosmtplib>=3.0.0; extra == "email"
Requires-Dist: google-api-python-client>=2.0.0; extra == "email"
Requires-Dist: google-auth>=2.0.0; extra == "email"
Requires-Dist: httpx>=0.27.0; extra == "email"
Requires-Dist: requests>=2.28.0; extra == "email"
Requires-Dist: sendgrid>=6.10.0; extra == "email"
Provides-Extra: erp
Provides-Extra: fdm-sla-printing
Provides-Extra: federation
Provides-Extra: fileio
Requires-Dist: psutil>=5.9.0; extra == "fileio"
Provides-Extra: forward-auth-consumer
Provides-Extra: forward-auth-provider
Provides-Extra: genealogy
Provides-Extra: health
Provides-Extra: kerberos-consumer
Requires-Dist: gssapi>=1.12.0; extra == "kerberos-consumer"
Provides-Extra: kerberos-provider
Provides-Extra: ldap-consumer
Requires-Dist: ldap3>=2.9.1; extra == "ldap-consumer"
Provides-Extra: ldap-provider
Requires-Dist: ldap3>=2.9.1; extra == "ldap-provider"
Requires-Dist: pyasn1>=0.6.1; extra == "ldap-provider"
Provides-Extra: local-ai
Requires-Dist: psutil>=5.9.0; extra == "local-ai"
Provides-Extra: local-ai-gguf
Requires-Dist: llama-cpp-python>=0.3.35; extra == "local-ai-gguf"
Provides-Extra: local-ai-torch
Requires-Dist: torch>=2.13.0; extra == "local-ai-torch"
Requires-Dist: transformers>=5.15.1; extra == "local-ai-torch"
Provides-Extra: maps
Provides-Extra: math
Requires-Dist: matplotlib>=3.7; extra == "math"
Requires-Dist: sympy>=1.12; extra == "math"
Provides-Extra: mcp-client
Requires-Dist: httpx2>=2.13; extra == "mcp-client"
Requires-Dist: mcp-types>=2.2; extra == "mcp-client"
Requires-Dist: mcp>=2.2; extra == "mcp-client"
Provides-Extra: media
Provides-Extra: messaging
Provides-Extra: meta-labels
Provides-Extra: meta-logging
Provides-Extra: meta-sdk-py
Provides-Extra: meta-sdk-rs
Provides-Extra: meta-sdk-ts
Provides-Extra: metadata
Provides-Extra: oauth-consumer
Provides-Extra: oauth-provider
Provides-Extra: observability
Requires-Dist: opentelemetry-api>=1.20.0; extra == "observability"
Requires-Dist: prometheus-client>=0.20.0; extra == "observability"
Requires-Dist: rollbar>=1.0.0; extra == "observability"
Requires-Dist: sentry-sdk>=2.0.0; extra == "observability"
Provides-Extra: payment
Provides-Extra: privacy
Provides-Extra: proxy-auth-consumer
Provides-Extra: proxy-auth-provider
Provides-Extra: quota
Provides-Extra: radius-consumer
Requires-Dist: pyrad>=2.5.4; extra == "radius-consumer"
Provides-Extra: radius-provider
Requires-Dist: pyrad>=2.5.4; extra == "radius-provider"
Provides-Extra: saml-consumer
Requires-Dist: defusedxml>=0.7.1; extra == "saml-consumer"
Requires-Dist: pysaml2<8,>=7.5.5; extra == "saml-consumer"
Provides-Extra: saml-provider
Requires-Dist: pysaml2>=7.5.5; extra == "saml-provider"
Provides-Extra: scim-consumer
Provides-Extra: scim-provider
Provides-Extra: secret-vault
Requires-Dist: hvac>=2.1.0; extra == "secret-vault"
Provides-Extra: sms
Requires-Dist: boto3>=1.26.0; extra == "sms"
Requires-Dist: botocore>=1.29.0; extra == "sms"
Requires-Dist: twilio>=9.0.0; extra == "sms"
Provides-Extra: social
Provides-Extra: source
Provides-Extra: wearable
Provides-Extra: webauthn-consumer
Requires-Dist: webauthn>=3.0.1; extra == "webauthn-consumer"
Provides-Extra: webauthn-provider
Provides-Extra: webhooks
Provides-Extra: websearch
Provides-Extra: wiki
Provides-Extra: x509-consumer
Requires-Dist: cryptography>=45.0.0; extra == "x509-consumer"
Provides-Extra: x509-provider
Requires-Dist: cryptography>=45.0.0; extra == "x509-provider"
Provides-Extra: all
Requires-Dist: zephyrex[acl-rbac]; extra == "all"
Requires-Dist: zephyrex[ai]; extra == "all"
Requires-Dist: zephyrex[ai-agents]; extra == "all"
Requires-Dist: zephyrex[ai-chains]; extra == "all"
Requires-Dist: zephyrex[ai-memories]; extra == "all"
Requires-Dist: zephyrex[ai-prompts]; extra == "all"
Requires-Dist: zephyrex[ai-tuning]; extra == "all"
Requires-Dist: zephyrex[audit-retention]; extra == "all"
Requires-Dist: zephyrex[auth-api-keys]; extra == "all"
Requires-Dist: zephyrex[auth-device-pairing]; extra == "all"
Requires-Dist: zephyrex[auth-invitations]; extra == "all"
Requires-Dist: zephyrex[auth-lockout]; extra == "all"
Requires-Dist: zephyrex[auth-magic-link]; extra == "all"
Requires-Dist: zephyrex[auth-marketplace]; extra == "all"
Requires-Dist: zephyrex[auth-merge]; extra == "all"
Requires-Dist: zephyrex[auth-mfa]; extra == "all"
Requires-Dist: zephyrex[auth-notifications]; extra == "all"
Requires-Dist: zephyrex[auth-privacy]; extra == "all"
Requires-Dist: zephyrex[auth-recovery-questions]; extra == "all"
Requires-Dist: zephyrex[auth-session]; extra == "all"
Requires-Dist: zephyrex[automotive]; extra == "all"
Requires-Dist: zephyrex[backup-restore]; extra == "all"
Requires-Dist: zephyrex[billing]; extra == "all"
Requires-Dist: zephyrex[book]; extra == "all"
Requires-Dist: zephyrex[cache]; extra == "all"
Requires-Dist: zephyrex[cad]; extra == "all"
Requires-Dist: zephyrex[calendar]; extra == "all"
Requires-Dist: zephyrex[cloud]; extra == "all"
Requires-Dist: zephyrex[conversations]; extra == "all"
Requires-Dist: zephyrex[crypto]; extra == "all"
Requires-Dist: zephyrex[database]; extra == "all"
Requires-Dist: zephyrex[database-memory]; extra == "all"
Requires-Dist: zephyrex[ecommerce]; extra == "all"
Requires-Dist: zephyrex[email]; extra == "all"
Requires-Dist: zephyrex[erp]; extra == "all"
Requires-Dist: zephyrex[fdm-sla-printing]; extra == "all"
Requires-Dist: zephyrex[federation]; extra == "all"
Requires-Dist: zephyrex[fileio]; extra == "all"
Requires-Dist: zephyrex[forward-auth-consumer]; extra == "all"
Requires-Dist: zephyrex[forward-auth-provider]; extra == "all"
Requires-Dist: zephyrex[genealogy]; extra == "all"
Requires-Dist: zephyrex[health]; extra == "all"
Requires-Dist: zephyrex[kerberos-consumer]; extra == "all"
Requires-Dist: zephyrex[kerberos-provider]; extra == "all"
Requires-Dist: zephyrex[ldap-consumer]; extra == "all"
Requires-Dist: zephyrex[ldap-provider]; extra == "all"
Requires-Dist: zephyrex[local-ai]; extra == "all"
Requires-Dist: zephyrex[local-ai-gguf]; extra == "all"
Requires-Dist: zephyrex[local-ai-torch]; extra == "all"
Requires-Dist: zephyrex[maps]; extra == "all"
Requires-Dist: zephyrex[math]; extra == "all"
Requires-Dist: zephyrex[mcp-client]; extra == "all"
Requires-Dist: zephyrex[mcp-server]; extra == "all"
Requires-Dist: zephyrex[media]; extra == "all"
Requires-Dist: zephyrex[messaging]; extra == "all"
Requires-Dist: zephyrex[meta-labels]; extra == "all"
Requires-Dist: zephyrex[meta-logging]; extra == "all"
Requires-Dist: zephyrex[meta-sdk-py]; extra == "all"
Requires-Dist: zephyrex[meta-sdk-rs]; extra == "all"
Requires-Dist: zephyrex[meta-sdk-ts]; extra == "all"
Requires-Dist: zephyrex[metadata]; extra == "all"
Requires-Dist: zephyrex[oauth-consumer]; extra == "all"
Requires-Dist: zephyrex[oauth-provider]; extra == "all"
Requires-Dist: zephyrex[observability]; extra == "all"
Requires-Dist: zephyrex[payment]; extra == "all"
Requires-Dist: zephyrex[privacy]; extra == "all"
Requires-Dist: zephyrex[proxy-auth-consumer]; extra == "all"
Requires-Dist: zephyrex[proxy-auth-provider]; extra == "all"
Requires-Dist: zephyrex[quota]; extra == "all"
Requires-Dist: zephyrex[radius-consumer]; extra == "all"
Requires-Dist: zephyrex[radius-provider]; extra == "all"
Requires-Dist: zephyrex[saml-consumer]; extra == "all"
Requires-Dist: zephyrex[saml-provider]; extra == "all"
Requires-Dist: zephyrex[scim-consumer]; extra == "all"
Requires-Dist: zephyrex[scim-provider]; extra == "all"
Requires-Dist: zephyrex[secret-vault]; extra == "all"
Requires-Dist: zephyrex[sms]; extra == "all"
Requires-Dist: zephyrex[social]; extra == "all"
Requires-Dist: zephyrex[source]; extra == "all"
Requires-Dist: zephyrex[wearable]; extra == "all"
Requires-Dist: zephyrex[webauthn-consumer]; extra == "all"
Requires-Dist: zephyrex[webauthn-provider]; extra == "all"
Requires-Dist: zephyrex[webhooks]; extra == "all"
Requires-Dist: zephyrex[websearch]; extra == "all"
Requires-Dist: zephyrex[wiki]; extra == "all"
Requires-Dist: zephyrex[x509-consumer]; extra == "all"
Requires-Dist: zephyrex[x509-provider]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-dependency; extra == "dev"
Requires-Dist: pytest-order; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# JamesonRGrieve's Zephyrex Framework Server

![Generation Paths](./Generation.png)

## Documentation Viewing

### Recommended: Obsidian

This documentation is best viewed using [Obsidian](https://obsidian.md/) with the custom plugin included in this repository. The plugin automatically hides folders without documentation, providing a clean, focused view of all available documentation.

**Setup:**
1. Install [Obsidian](https://obsidian.md/)
2. Open this repository as an Obsidian vault
3. The custom plugin (`hide-folders-without-md`) will automatically activate
4. Navigate through the documentation using Obsidian's graph view and linked references

### Alternative: Traditional Navigation

Documentation can also be viewed directly in your text editor or GitHub, though you won't benefit from the cross-referencing and visualization features that Obsidian provides.

## Documentation Directory

### Framework Overview
- **[src/zephyrex/Framework.md](../src/zephyrex/Framework.md)** - Comprehensive framework architecture overview
- **[src/zephyrex/Framework.Test.md](../src/zephyrex/Framework.Test.md)** - Testing philosophy and patterns

### Core Library Components
- **[src/zephyrex/lib/LIB.Overview.md](../src/zephyrex/lib/LIB.Overview.md)** - Library components overview and integration
- **[src/zephyrex/lib/LIB.Dependencies.md](../src/zephyrex/lib/LIB.Dependencies.md)** - System, Python, and extension dependency management
- **[src/zephyrex/lib/LIB.Pydantic.md](../src/zephyrex/lib/LIB.Pydantic.md)** - Model utilities and registry management
- **[src/zephyrex/lib/LIB.Pydantic2FastAPI.md](../src/zephyrex/lib/LIB.Pydantic2FastAPI.md)** - Automatic FastAPI router generation
- **[src/zephyrex/lib/LIB.Logging.md](../src/zephyrex/lib/LIB.Logging.md)** - Centralized logging system

### Database Layer
- **[src/zephyrex/database/DB.Management.md](../src/zephyrex/database/DB.Management.md)** - Database management and configuration
- **[src/zephyrex/database/DB.Patterns.md](../src/zephyrex/database/DB.Patterns.md)** - Database design patterns and mixins
- **[src/zephyrex/database/DB.Permissions.md](../src/zephyrex/database/DB.Permissions.md)** - Permission system architecture
- **[src/zephyrex/database/DB.Seeding.md](../src/zephyrex/database/DB.Seeding.md)** - Data seeding and initialization
- **[src/zephyrex/database/DB.Test.md](../src/zephyrex/database/DB.Test.md)** - Database testing patterns

### Business Logic Layer
- **[src/zephyrex/logic/BLL.Patterns.md](../src/zephyrex/logic/BLL.Patterns.md)** - Business logic patterns and best practices
- **[src/zephyrex/logic/BLL.Abstraction.md](../src/zephyrex/logic/BLL.Abstraction.md)** - Abstract BLL manager functionality
- **[src/zephyrex/logic/BLL.Authentication.md](../src/zephyrex/logic/BLL.Authentication.md)** - Authentication system implementation
- **[src/zephyrex/logic/BLL.Hooks.md](../src/zephyrex/logic/BLL.Hooks.md)** - Hook system architecture and usage
- **[src/zephyrex/logic/BLL.Schema.md](../src/zephyrex/logic/BLL.Schema.md)** - Pydantic schema patterns
- **[src/zephyrex/logic/BLL.Test.md](../src/zephyrex/logic/BLL.Test.md)** - Business logic testing patterns
- **[src/zephyrex/logic/SVC.Patterns.md](../src/zephyrex/logic/SVC.Patterns.md)** - Background service patterns
- **[src/zephyrex/logic/SVC.Test.md](../src/zephyrex/logic/SVC.Test.md)** - Service testing patterns

### Endpoint Layer
- **[src/zephyrex/endpoints/EP.Patterns.md](../src/zephyrex/endpoints/EP.Patterns.md)** - API endpoint patterns and usage
- **[src/zephyrex/endpoints/EP.Abstraction.md](../src/zephyrex/endpoints/EP.Abstraction.md)** - Abstract endpoint router
- **[src/zephyrex/endpoints/EP.GQL.md](../src/zephyrex/endpoints/EP.GQL.md)** - GraphQL integration
- **[src/zephyrex/endpoints/EP.Schema.md](../src/zephyrex/endpoints/EP.Schema.md)** - API schema patterns
- **[src/zephyrex/endpoints/EP.Test.md](../src/zephyrex/endpoints/EP.Test.md)** - Endpoint testing patterns

### Extension System
- **[src/zephyrex/extensions/EXT.Patterns.md](../src/zephyrex/extensions/EXT.Patterns.md)** - Extension system architecture
- **[src/zephyrex/extensions/PRV.Patterns.md](../src/zephyrex/extensions/PRV.Patterns.md)** - Provider rotation system

### Migration System
- **[src/zephyrex/database/migrations/DB.Migrations.md](../src/zephyrex/database/migrations/DB.Migrations.md)** - Database migration patterns

## Quick Start

### Installation

From PyPI:
```sh
pip install zephyrex
```

From source (for framework development):
```sh
git clone https://git.zephyrex.dev/ZephyrexTechnologies/ServerFramework.git
cd ServerFramework
pip install -e ".[dev]"
```

Every bundled extension is included; each one's third-party packages install through an extra of the same name, hyphenated: `pip install "zephyrex[auth-mfa,secret-vault]"`. `cache` adds the Redis/Valkey client core uses for its cache and rate limiter, `mcp-server` adds what core needs to serve this API as MCP tools (`MCP=true`), and `all` installs every extra. The extras are generated from what each extension and its providers declare (`python -m zephyrex.extensions.sync_dependencies`; the test suite fails if they drift).

### Requirements
- Python 3.11+

### Running the server
```sh
python -m zephyrex run   # or the console script: `zephyrex run`
```
The server boots on port 1996 by default.

### Basic Configuration
```
APP_NAME=MyApp
SERVER_URI=http://localhost:1996
APP_EXTENSIONS=email,auth_mfa,database,payment
```

## Documentation Philosophy

1. **Architectural Focus**: Documentation describes the "why" and "how" of components, not just the "what"
2. **Minimal Code Snippets**: Code examples are minimal; the documentation focuses on patterns and concepts
3. **Cross-Referenced**: Heavy use of links between related documentation
4. **Layer Separation**: Documentation organized by architectural layer
5. **Pattern-Based**: Emphasis on reusable patterns over specific implementations

## Contributing to Documentation

When adding new documentation:

1. Follow the existing naming convention: `LAYER.Component.md`
2. Focus on architectural decisions and patterns
3. Link to related documentation using relative paths
4. Keep code snippets minimal and focused
5. Include "Best Practices" sections where appropriate

## Framework Benefits

This framework provides:

- **Pydantic-First Design**: Single source of truth for all schemas
- **Zero Boilerplate**: Automatic generation of database models, endpoints, and documentation
- **True Testing**: No mocks, real implementations with proper isolation
- **Extension Architecture**: Modular plugin system with isolated migrations
- **Type Safety**: End-to-end type checking from API to database

For a comprehensive overview, start with [Framework.md](../src/zephyrex/Framework.md)

## License

[AGPL-3.0-or-later](../LICENSE). A server built on Zephyrex offers its users its source, as section 13 of the license requires for network use: `GET /source` returns the source URL, version and license. It points at `APP_REPOSITORY`, which defaults to the canonical repository, https://git.zephyrex.dev/ZephyrexTechnologies/ServerFramework; a deployment that runs modified code sets `APP_REPOSITORY` to its own source.

Every response also carries the source, always:

| Header | Values |
|---|---|
| `Source-Link` | `APP_REPOSITORY` |
| `Source-Hash-Status` | `verified`: the running source matches the release it was installed from; `modified`: it does not; `unverified`: there is no release to check against (a source checkout) |
| `Source-Git-Status` | The running source's git state: `clean` or `dirty` in a git checkout of it; `none` when it is not one (no `.git`, as for an installed release, which `Source-Hash-Status` vouches for); `error` when git cannot say (not installed, timed out, refused) |

Each release wheel carries `zephyrex/_provenance.json`, the digest of exactly what it ships and the commit it was built from, covered by the wheel's sigstore signature; the running server hashes its own source against it at startup, offline. `GET /source` adds the version, commit, digest and, per loaded extension, its own source: a bundled extension is part of the framework's, and one loaded from your extensions directory declares `repository` in its `manifest.toml` and is checked on its own. None of this changes what the server does: it reports, it never refuses to run.
