Metadata-Version: 2.4
Name: XCoreRuntime
Version: 2.5.0
Summary: Plugin-first orchestration framework built on FastAPI
License-Expression: MIT
License-File: LICENSE
Keywords: xcore,plugin,runtime
Author: Eliezer Traore
Author-email: 68350805+traoreera@users.noreply.github.com
Requires-Python: >=3.12,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Provides-Extra: all
Provides-Extra: cpp
Provides-Extra: sdk
Provides-Extra: xcli
Requires-Dist: aiosqlite (>=0.22.1,<1.0.0)
Requires-Dist: alembic (>=1.16.1,<2.0.0)
Requires-Dist: apscheduler (>=3.11.0,<4.0.0)
Requires-Dist: celery (>=5.6.3,<6.0.0)
Requires-Dist: fastapi[standard] (>=0.135.1,<1.0.0)
Requires-Dist: opentelemetry-api (>=1.27.0,<2.0.0)
Requires-Dist: opentelemetry-exporter-otlp-proto-http (>=1.27.0,<2.0.0)
Requires-Dist: opentelemetry-sdk (>=1.27.0,<2.0.0)
Requires-Dist: psycopg2 (>=2.9.11,<3.0.0)
Requires-Dist: pydantic-settings (>=2.14.2,<3.0.0)
Requires-Dist: pydantic[email] (>=2.11.7,<3.0.0)
Requires-Dist: python-dotenv (>=1.1.0,<2.0.0)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: redis[hiredis] (>=7.0.0,<8.0.0)
Requires-Dist: rich (>=14.0.0,<15.0.0)
Requires-Dist: sqlalchemy (>=2.0.41,<3.0.0)
Requires-Dist: uvicorn (>=0.38.0,<1.0.0)
Requires-Dist: xcdk (>=0.1.0) ; extra == "all"
Requires-Dist: xcdk (>=0.1.0) ; extra == "sdk"
Requires-Dist: xcorecli (>=1.1.0) ; extra == "all"
Requires-Dist: xcorecli (>=1.1.0) ; extra == "xcli"
Requires-Dist: xscanner (>=0.1.0) ; extra == "all"
Requires-Dist: xscanner (>=0.1.0) ; extra == "cpp"
Description-Content-Type: text/markdown

# ⚡ XCore Framework

<p align="center">
  <img src="doc/assets/logo.svg" alt="XCore Logo" width="200" />
</p>

<p align="center">
  <b>High-performance, plugin-first orchestration framework built on FastAPI.</b>
</p>

<p align="center">
  <a href="https://xcorehub.dev">
    <img src="doc/assets/xcore_badge_v2.3.2.svg">
  </a>
  <a href="https://codecov.io/gh/traoreera/xcore" >
 <img src="https://codecov.io/gh/traoreera/xcore/graph/badge.svg?token=KyPoM6DebU"/>
 </a>
  <a href="https://github.com/traoreera/xcore/actions/workflows/ci.yml">
    <img src="https://github.com/traoreera/xcore/actions/workflows/ci.yml/badge.svg" alt="CI Status" />
  </a>
  <a href="https://github.com/traoreera/xcore/actions/workflows/docs.yml">
    <img src="https://github.com/traoreera/xcore/actions/workflows/docs.yml/badge.svg" alt="Docs Build & Deploy" />
  </a>
  <!-- ⚠️ Remplace YOUR_SITE_ID par l'API ID Netlify (Site settings → Site information) -->
  <a href="https://app.netlify.com/sites/xcore-docs/deploys">
    <img src="https://api.netlify.com/api/v1/badges/340716e8-9c34-472f-a5a3-c974bfab302b/deploy-status" alt="Netlify Status" />
  </a>
  <a href="https://github.com/traoreera/xcore/releases">
    <img src="https://img.shields.io/badge/version-2.3.5-blue.svg" alt="Version" />
  </a>
  <a href="LICENSE">
    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License" />
  </a>
  <a href="https://www.python.org/downloads/">
    <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python Support" />
  </a>
  <a href="https://fastapi.tiangolo.com/">
    <img src="https://img.shields.io/badge/FastAPI-0.135+-green.svg" alt="FastAPI" />
  </a>
</p>
---

**XCore** is designed to load, isolate, and manage modular extensions (plugins) in a secure, sandboxed environment. It provides a robust foundation for building scalable applications where features can be dynamically added, removed, or updated without affecting the core system.

## ✨ Key Features

- 🔌 **Plugin-First Architecture**: Everything is a plugin. Keep your core lean and your features modular.
- ⚡ **High-Performance Runtime**: Optimized EventBus and Warm Pool for minimal latency (Ephemeral/Serverless mode).
- 🛡️ **Advanced Sandboxing**: AST-based scanning, resource restriction, and C++ security core.
- 🌐 **Native Multi-tenancy**: Resource isolation (DB/Cache) and tenant-aware routing out of the box.
- 🚀 **Built on FastAPI**: Leverage the speed and ecosystem of one of the fastest Python frameworks.
- 📦 **Service Container**: Seamless management of Databases (SQLAlchemy), Cache (Redis or tiered Memory+Redis), and Schedulers.
- 🛠️ **Dev-Friendly CLI**: Hot-reload plugins, sign manifests, and verify system health with one command.
- 📊 **Production Ready**: Structured logging, Prometheus metrics, and comprehensive test coverage.
- 🔭 **Distributed Tracing**: Real OpenTelemetry integration — a single trace_id follows a request across HTTP, plugin calls, and sandboxed subprocess IPC hops.

---

## 📺 Demo

Integrating XCore into your FastAPI application is straightforward:

```python
from fastapi import FastAPI
from xcore import Xcore
from contextlib import asynccontextmanager

# 1. Initialize the Kernel
xcore = Xcore(config_path="integration.yaml")

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 2. Boot XCore (loads plugins and services)
    await xcore.boot(app)
    yield
    # 3. Graceful shutdown
    await xcore.shutdown()

app = FastAPI(lifespan=lifespan)

@app.get("/compute")
async def compute(value: int):
    # 4. Call a plugin method dynamically
    result = await xcore.plugins.call("math_plugin", "calculate", {"x": value})
    return {"result": result}
```

---

## 🚀 Getting Started

### Installation

```bash
# Clone the repository
git clone https://github.com/traoreera/xcore.git
cd xcore

# Install using Poetry
make install
```

### Quick Run

Start the development server with auto-reload enabled:

```bash
make dev
```

---

## 🏗️ Architecture

XCore follows a "minimal core" philosophy. Most business logic resides in plugins, which are managed by the **Plugin Supervisor**.

```mermaid
flowchart TB
    subgraph Core["XCore Kernel"]
        X[Orchestrator] --> PS[Plugin Supervisor]
        X --> EB[Event Bus]
        X --> SC[Service Container]
    end

    PS --> Trusted[Trusted Plugins]
    PS --> Sandbox[Sandboxed Plugins]

    SC --> DB[(Database)]
    SC --> RD[(Redis)]
    SC --> SCH[Scheduler]
```

---

## 🛠️ CLI Reference

The `xcore` CLI is your control center for managing the framework.

| Command | Description |
| :--- | :--- |
| `xcore plugin list` | List all loaded plugins |
| `xcore plugin reload <name>` | Hot-reload a plugin without restarting the server |
| `xcore plugin info <name>` | Inspect plugin manifest and permissions |
| `xcore plugin sign <path>` | Generate a security signature for a plugin |
| `xcore services status` | Check the health of DB, Cache, and Scheduler |
| `xcore health` | Perform a global system health check |
| `xcore worker start` | Start the background task worker |

---

## 🧪 Development & Quality

We maintain high standards for code quality and security:

```bash
make test              # Run the full test suite
make lint-fix          # Auto-format and fix linting issues
make security-check    # Run Bandit security audit
make benchmark         # Run performance benchmarks
```

---

## 📄 License

This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

---

<p align="center">
  Built with ❤️ by the <b>XCore Team</b>
</p>

