Metadata-Version: 2.4
Name: XCoreRuntime
Version: 2.0.0
Summary: for base html core app
License: MIT
Author: XcoreTEAM
Author-email: team@xcore.dev
Requires-Python: >=3.11,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: aiocache (>=0.12.3,<0.13.0)
Requires-Dist: aiosqlite (>=0.22.1,<0.23.0)
Requires-Dist: alembic (>=1.16.1,<2.0.0)
Requires-Dist: apscheduler (>=3.11.0,<4.0.0)
Requires-Dist: bcrypt (==4.0.1)
Requires-Dist: fastapi[standard] (>=0.135.1,<0.136.0)
Requires-Dist: markdown (>=3.8.2,<4.0.0)
Requires-Dist: mysql-connector-python (>=9.4.0,<10.0.0)
Requires-Dist: passlib[bcrypt] (>=1.7.4,<2.0.0)
Requires-Dist: pillow (>=11.2.1,<13.0.0)
Requires-Dist: pip (==26.0.1)
Requires-Dist: psutil (>=7.0.0,<8.0.0)
Requires-Dist: psycopg2 (>=2.9.11,<3.0.0)
Requires-Dist: pydantic-settings (>=2.12.0,<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: python-jose (>=3.4.0,<4.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: toml (>=0.10.2,<0.11.0)
Requires-Dist: user-agents (>=2.2.0,<3.0.0)
Requires-Dist: uvicorn (>=0.38.0,<0.39.0)
Requires-Dist: watchdog (>=6.0.0,<7.0.0)
Description-Content-Type: text/markdown

# ⚡ XCore Framework

[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/traoreera/xcore)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.118+-green.svg)](https://fastapi.tiangolo.com/)

**XCore** is a high-performance, plugin-first orchestration framework built on top of **FastAPI**. It is designed to load, isolate, and manage modular extensions (plugins) in a secure, sandboxed environment.

## 🏗️ Architecture Overview

XCore follows a "minimal core" philosophy where most features are provided via plugins or shared services.

```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]
```

---

## 🚀 Getting Started

### Prerequisites

- **Python 3.11+**
- **Poetry** (Package Manager)

### Installation

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

2. **Install dependencies**:
   ```bash
   poetry install
   ```

3. **Run the development server**:
   ```bash
   make run-dev
   ```
### or use pip to install and use it
    ```bash
        uv add https://github.com/traoreera/xcore
    ```

---

## 💻 Usage

### 1. Integration with FastAPI

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

xcore = Xcore(config_path="xcore.yaml")

@asynccontextmanager
async def lifespan(app: FastAPI):
    await xcore.boot(app)
    yield
    await xcore.shutdown()

app = FastAPI(lifespan=lifespan)
```

### 2. Standalone Usage

```python
from xcore import Xcore

async def main():
    app = Xcore()
    await app.boot()
    
    # Call a plugin action
    result = await app.plugins.call("users_plugin", "get_user", {"id": 1})
    print(result)
    
    await app.shutdown()
```

---

## 🔌 Plugin Development

Plugins reside in the `plugins/` directory. A standard plugin structure looks like this:

```text
plugins/my_plugin/
├── plugin.yaml      # Manifest (metadata & entry point)
├── plugin.sig       # Security signature (for trusted plugins)
└── src/
    └── main.py      # Core logic
```

### Example `plugin.yaml`
```yaml
name: my_plugin
version: "2.0.0"
author: Your Name
description: "A sample plugin"
execution_mode: trusted  # or "sandboxed"
framework_version: ">=2.0"
entry_point: src/main.py

permissions:
  - resource: "cache.*"
    actions: ["read", "write"]
    effect: allow

resources:
  timeout_seconds: 30
  rate_limit:
    calls: 100
    period_seconds: 60
```

---

## 🛠️ CLI Reference

XCore comes with a powerful CLI for management and security.

| Command | Description |
| :--- | :--- |
| `xcore plugin list` | List all loaded plugins |
| `xcore plugin load <name>` | Load a specific plugin |
| `xcore plugin reload <name>` | Hot-reload a plugin |
| `xcore plugin sign <path>` | Generate a security signature for a plugin |
| `xcore plugin validate <path>`| Validate plugin manifest and structure |
| `xcore services status` | Check the health of DB, Cache, and Scheduler |
| `xcore health` | Perform a global system health check |

---

## 📜 Makefile Commands

| Command | Description |
| :--- | :--- |
| `make init` | Initialize project (install + run) |
| `make test` | Run the test suite |
| `make lint-fix` | Auto-format code (Black, Isort) |
| `make docker-dev` | Spin up development environment with Docker |
| `make logs-live` | View real-time structured logs |

---

## 📄 License

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

---

<p align="center">
  Built with ❤️ by <b>Xcore team's</b>
</p>


<!-- Automated minor fix for issue #46 -->

