classifiedai 0.1.0__tar.gz

classifiedai-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: classifiedai
+Version: 0.1.0
+Summary: Classified trading analysis platform
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: ccxt
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: aiohttp
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Requires-Dist: matplotlib
+Requires-Dist: mplfinance
+Requires-Dist: ta
+Requires-Dist: websockets
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# CLASSIFIED
+
+### Market Data Infrastructure · Real-Time Streaming · Multi-Timeframe Intelligence
+
+**A unified market-data infrastructure package for exchange connectivity, normalized OHLCV data, multi-timeframe requests, and HTTP/WebSocket delivery.**
+
+CLASSIFIED provides shared market-data infrastructure for charting applications, analytical engines, and specialist trading systems. It centralizes exchange connectivity and market-data handling so independent consumers can work with a consistent foundation rather than implementing their own exchange integrations.
+
+The package is published under the distribution name `classifiedai`, while its Python import namespace remains `classified`.
+
+> **Core principle:** One market-data foundation. Multiple independent consumers. A consistent data contract.
+
+---
+
+## Features
+
+- **Exchange connectivity** — integrate with supported exchanges through CCXT.
+- **Normalized OHLCV data** — work with Open, High, Low, Close, and Volume candle data.
+- **Multi-timeframe requests** — request market data at different candle intervals.
+- **Historical market data** — retrieve candles for charting and analysis.
+- **Adaptive candle requirements** — centralize candle-count requirements for data consumers where supported by the active implementation.
+- **HTTP API** — expose market data through HTTP endpoints.
+- **WebSocket streaming** — support persistent connections for live market-data delivery.
+- **Shared infrastructure** — allow independent applications to reuse the same market-data foundation.
+
+CLASSIFIED is infrastructure, not a trading strategy or trade-execution engine.
+
+---
+
+## Installation
+
+Install the package from PyPI:
+
+```bash
+python -m pip install classifiedai
+```
+
+### Requirements
+
+- Python 3.12 or newer.
+- Network access to the configured exchange where live exchange data is required.
+- Appropriate exchange configuration for the selected data source.
+
+### Verify the installation
+
+```bash
+python -c "import classified; print(classified.__file__)"
+```
+
+The distribution name used by `pip` is `classifiedai`. The import namespace used in Python remains `classified`.
+
+### Install optional test dependencies
+
+```bash
+python -m pip install "classifiedai[test]"
+```
+
+This command is available when the published release includes the `test` optional dependency extra.
+
+---
+
+## Architecture
+
+```text
+                  EXCHANGE DATA SOURCE
+                          |
+                          v
+                +----------------------+
+                |   CLASSIFIED Core    |
+                |                      |
+                | Exchange Connectivity|
+                | OHLCV Normalization  |
+                | Multi-Timeframe Data |
+                | Candle Requirements  |
+                | Cache & Freshness    |
+                +----------+-----------+
+                           |
+                           v
+                +----------------------+
+                |     API Gateway      |
+                |                      |
+                | HTTP / REST          |
+                | WebSocket Streaming  |
+                +----------+-----------+
+                           |
+              +------------+------------+
+              |            |            |
+              v            v            v
+         Visualization  Analytical   Other Data
+          Applications   Systems     Consumers
+```
+
+*Conceptual architecture. The precise responsibilities and available capabilities depend on the installed implementation and its configuration.*
+
+---
+
+## Market Data
+
+CLASSIFIED is designed to provide a common interface for market-data consumers that need historical candles, multiple timeframes, or continuous updates.
+
+### OHLCV data
+
+OHLCV represents:
+
+| Field | Meaning |
+|---|---|
+| Open | Opening price for a candle |
+| High | Highest price reached during the candle |
+| Low | Lowest price reached during the candle |
+| Close | Closing price for a candle |
+| Volume | Volume recorded during the candle |
+
+### Multi-timeframe access
+
+Example candle intervals include:
+
+| Timeframe | Typical analytical use |
+|---|---|
+| `4h` | Higher-timeframe market structure |
+| `1h` | Intermediate market context |
+| `15m` | Intraday price action |
+| `5m` | Short-term price monitoring |
+
+These are example intervals, not trading signals. Actual supported intervals and candle limits depend on the exchange and implementation.
+
+---
+
+## API Gateway
+
+The gateway provides HTTP-based access and WebSocket streaming through an asynchronous server using `aiohttp`.
+
+The documented local server address is:
+
+```text
+http://127.0.0.1:8080
+```
+
+The server must be started separately when using the gateway endpoints.
+
+### Start the gateway
+
+From an environment where CLASSIFIED and its dependencies are installed, run:
+
+```bash
+python -m classified.api.server
+```
+
+The server is configured to listen on port `8080` in the documented setup.
+
+### 1. Health check
+
+**Method:** `GET`
+
+```http
+GET /health
+```
+
+Local URL:
+
+```text
+http://127.0.0.1:8080/health
+```
+
+Use this endpoint to check whether the gateway is responding.
+
+### 2. Historical candle data
+
+**Method:** `GET`
+
+```http
+GET /api/v1/market-data/candles
+```
+
+Query parameters:
+
+| Parameter | Description | Example |
+|---|---|---|
+| `symbol` | Trading pair | `BTC/USDT` |
+| `timeframe` | Candle interval | `5m` |
+| `candle_count` | Requested candle count | `150` |
+
+Example URL:
+
+```text
+http://127.0.0.1:8080/api/v1/market-data/candles?symbol=BTC%2FUSDT&timeframe=5m&candle_count=150
+```
+
+PowerShell example:
+
+```powershell
+Invoke-RestMethod `
+  "http://127.0.0.1:8080/api/v1/market-data/candles?symbol=BTC%2FUSDT&timeframe=5m&candle_count=150"
+```
+
+The endpoint is intended to supply historical candle data to charting and analytical consumers. Consult the active server implementation for the exact response schema and error behavior.
+
+### 3. Live market-data stream
+
+**Protocol:** WebSocket
+
+```text
+ws://127.0.0.1:8080/api/v1/market-data/stream
+```
+
+Query parameters:
+
+| Parameter | Description | Example |
+|---|---|---|
+| `symbol`

classifiedai-0.1.0/README.md

@@ -0,0 +1,209 @@
+# CLASSIFIED
+
+### Market Data Infrastructure · Real-Time Streaming · Multi-Timeframe Intelligence
+
+**A unified market-data infrastructure package for exchange connectivity, normalized OHLCV data, multi-timeframe requests, and HTTP/WebSocket delivery.**
+
+CLASSIFIED provides shared market-data infrastructure for charting applications, analytical engines, and specialist trading systems. It centralizes exchange connectivity and market-data handling so independent consumers can work with a consistent foundation rather than implementing their own exchange integrations.
+
+The package is published under the distribution name `classifiedai`, while its Python import namespace remains `classified`.
+
+> **Core principle:** One market-data foundation. Multiple independent consumers. A consistent data contract.
+
+---
+
+## Features
+
+- **Exchange connectivity** — integrate with supported exchanges through CCXT.
+- **Normalized OHLCV data** — work with Open, High, Low, Close, and Volume candle data.
+- **Multi-timeframe requests** — request market data at different candle intervals.
+- **Historical market data** — retrieve candles for charting and analysis.
+- **Adaptive candle requirements** — centralize candle-count requirements for data consumers where supported by the active implementation.
+- **HTTP API** — expose market data through HTTP endpoints.
+- **WebSocket streaming** — support persistent connections for live market-data delivery.
+- **Shared infrastructure** — allow independent applications to reuse the same market-data foundation.
+
+CLASSIFIED is infrastructure, not a trading strategy or trade-execution engine.
+
+---
+
+## Installation
+
+Install the package from PyPI:
+
+```bash
+python -m pip install classifiedai
+```
+
+### Requirements
+
+- Python 3.12 or newer.
+- Network access to the configured exchange where live exchange data is required.
+- Appropriate exchange configuration for the selected data source.
+
+### Verify the installation
+
+```bash
+python -c "import classified; print(classified.__file__)"
+```
+
+The distribution name used by `pip` is `classifiedai`. The import namespace used in Python remains `classified`.
+
+### Install optional test dependencies
+
+```bash
+python -m pip install "classifiedai[test]"
+```
+
+This command is available when the published release includes the `test` optional dependency extra.
+
+---
+
+## Architecture
+
+```text
+                  EXCHANGE DATA SOURCE
+                          |
+                          v
+                +----------------------+
+                |   CLASSIFIED Core    |
+                |                      |
+                | Exchange Connectivity|
+                | OHLCV Normalization  |
+                | Multi-Timeframe Data |
+                | Candle Requirements  |
+                | Cache & Freshness    |
+                +----------+-----------+
+                           |
+                           v
+                +----------------------+
+                |     API Gateway      |
+                |                      |
+                | HTTP / REST          |
+                | WebSocket Streaming  |
+                +----------+-----------+
+                           |
+              +------------+------------+
+              |            |            |
+              v            v            v
+         Visualization  Analytical   Other Data
+          Applications   Systems     Consumers
+```
+
+*Conceptual architecture. The precise responsibilities and available capabilities depend on the installed implementation and its configuration.*
+
+---
+
+## Market Data
+
+CLASSIFIED is designed to provide a common interface for market-data consumers that need historical candles, multiple timeframes, or continuous updates.
+
+### OHLCV data
+
+OHLCV represents:
+
+| Field | Meaning |
+|---|---|
+| Open | Opening price for a candle |
+| High | Highest price reached during the candle |
+| Low | Lowest price reached during the candle |
+| Close | Closing price for a candle |
+| Volume | Volume recorded during the candle |
+
+### Multi-timeframe access
+
+Example candle intervals include:
+
+| Timeframe | Typical analytical use |
+|---|---|
+| `4h` | Higher-timeframe market structure |
+| `1h` | Intermediate market context |
+| `15m` | Intraday price action |
+| `5m` | Short-term price monitoring |
+
+These are example intervals, not trading signals. Actual supported intervals and candle limits depend on the exchange and implementation.
+
+---
+
+## API Gateway
+
+The gateway provides HTTP-based access and WebSocket streaming through an asynchronous server using `aiohttp`.
+
+The documented local server address is:
+
+```text
+http://127.0.0.1:8080
+```
+
+The server must be started separately when using the gateway endpoints.
+
+### Start the gateway
+
+From an environment where CLASSIFIED and its dependencies are installed, run:
+
+```bash
+python -m classified.api.server
+```
+
+The server is configured to listen on port `8080` in the documented setup.
+
+### 1. Health check
+
+**Method:** `GET`
+
+```http
+GET /health
+```
+
+Local URL:
+
+```text
+http://127.0.0.1:8080/health
+```
+
+Use this endpoint to check whether the gateway is responding.
+
+### 2. Historical candle data
+
+**Method:** `GET`
+
+```http
+GET /api/v1/market-data/candles
+```
+
+Query parameters:
+
+| Parameter | Description | Example |
+|---|---|---|
+| `symbol` | Trading pair | `BTC/USDT` |
+| `timeframe` | Candle interval | `5m` |
+| `candle_count` | Requested candle count | `150` |
+
+Example URL:
+
+```text
+http://127.0.0.1:8080/api/v1/market-data/candles?symbol=BTC%2FUSDT&timeframe=5m&candle_count=150
+```
+
+PowerShell example:
+
+```powershell
+Invoke-RestMethod `
+  "http://127.0.0.1:8080/api/v1/market-data/candles?symbol=BTC%2FUSDT&timeframe=5m&candle_count=150"
+```
+
+The endpoint is intended to supply historical candle data to charting and analytical consumers. Consult the active server implementation for the exact response schema and error behavior.
+
+### 3. Live market-data stream
+
+**Protocol:** WebSocket
+
+```text
+ws://127.0.0.1:8080/api/v1/market-data/stream
+```
+
+Query parameters:
+
+| Parameter | Description | Example |
+|---|---|---|
+| `symbol`

classifiedai-0.1.0/classified/api/__init__.py

@@ -0,0 +1 @@
+"""Classified market-data transport APIs."""

classifiedai-0.1.0/classified/api/app.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import os
+
+from aiohttp import web
+
+from classified.exchange.ccxt_adapter import CCXTExchangeAdapter
+from classified.market_data.manager import MarketDataManager
+
+from .routes import register_routes
+from .stream import create_stream_registry
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def create_manager() -> MarketDataManager:
+    exchange_id = os.getenv("CLASSIFIED_EXCHANGE_ID", "bingx").strip().lower()
+    adapter = CCXTExchangeAdapter(
+        exchange_id,
+        api_key=os.getenv("CLASSIFIED_EXCHANGE_API_KEY") or None,
+        secret=os.getenv("CLASSIFIED_EXCHANGE_SECRET") or None,
+        password=os.getenv("CLASSIFIED_EXCHANGE_PASSWORD") or None,
+        sandbox=_env_bool("CLASSIFIED_EXCHANGE_SANDBOX", False),
+        enable_rate_limit=True,
+        timeout=int(os.getenv("CLASSIFIED_EXCHANGE_TIMEOUT_MS", "30000")),
+    )
+    return MarketDataManager(adapter)
+
+
+def _cors_middleware() -> web.middleware:
+    raw = os.getenv(
+        "CLASSIFIED_API_CORS_ORIGINS",
+        "http://localhost:5173,http://127.0.0.1:5173",
+    )
+    allowed_origins = frozenset(
+        origin.strip() for origin in raw.split(",") if origin.strip()
+    )
+
+    @web.middleware
+    async def middleware(request: web.Request, handler):
+        if request.method == "OPTIONS":
+            response = web.Response(status=204)
+        else:
+            response = await handler(request)
+
+        origin = request.headers.get("Origin")
+        if origin in allowed_origins:
+            response.headers["Access-Control-Allow-Origin"] = origin
+            response.headers["Vary"] = "Origin"
+            response.headers["Access-Control-Allow-Methods"] = "GET,OPTIONS"
+            response.headers["Access-Control-Allow-Headers"] = "Content-Type"
+
+        return response
+
+    return middleware
+
+
+async def _on_startup(app: web.Application) -> None:
+    manager: MarketDataManager = app["market_data_manager"]
+    manager.connect()
+
+
+async def _on_cleanup(app: web.Application) -> None:
+    registry = app.get("market_stream_registry")
+    if registry is not None:
+        await registry.close()
+
+    manager: MarketDataManager = app["market_data_manager"]
+    manager.close()
+
+
+def create_app(manager: MarketDataManager | None = None) -> web.Application:
+    resolved_manager = manager or create_manager()
+    app = web.Application(middlewares=[_cors_middleware()])
+    register_routes(app, resolved_manager)
+    app["market_stream_registry"] = create_stream_registry(
+        resolved_manager.exchange_name
+    )
+    app.on_startup.append(_on_startup)
+    app.on_cleanup.append(_on_cleanup)
+    return app
+
+
+def main() -> None:
+    host = os.getenv("CLASSIFIED_API_HOST", "127.0.0.1")
+    port = int(os.getenv("CLASSIFIED_API_PORT", "8080"))
+    web.run_app(create_app(), host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

classifiedai-0.1.0/classified/api/models.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from datetime import timezone
+from typing import Any
+
+from classified.market_data.manager import MarketDataResult
+
+
+def candle_to_dict(candle: Any) -> dict[str, Any]:
+    """Serialize one Classified Candle for external clients."""
+    timestamp = candle.timestamp
+
+    if timestamp.tzinfo is None or timestamp.utcoffset() is None:
+        timestamp = timestamp.replace(tzinfo=timezone.utc)
+    else:
+        timestamp = timestamp.astimezone(timezone.utc)
+
+    epoch_seconds = int(timestamp.timestamp())
+
+    return {
+        "timestamp": epoch_seconds,
+        "timestampMs": epoch_seconds * 1000,
+        "open": candle.open,
+        "high": candle.high,
+        "low": candle.low,
+        "close": candle.close,
+        "volume": candle.volume,
+    }
+
+
+def market_data_result_to_dict(result: MarketDataResult) -> dict[str, Any]:
+    """Serialize a market-data result without exposing internal objects."""
+    return {
+        "symbol": result.symbol,
+        "timeframe": result.timeframe,
+        "purpose": result.request.purpose,
+        "requestedCandleCount": result.request.candle_count,
+        "candleCount": result.candle_count,
+        "fromCache": result.from_cache,
+        "refreshed": result.refreshed,
+        "candles": [candle_to_dict(candle) for candle in result.candles],
+    }

classifiedai-0.1.0/classified/api/routes.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from aiohttp import web
+
+from classified.market_data.data_requests import MarketDataRequest
+from classified.market_data.manager import (
+    MarketDataManager,
+    MarketDataUnavailableError,
+)
+
+from .models import market_data_result_to_dict
+from .stream import market_stream
+
+SUPPORTED_TIMEFRAMES: frozenset[str] = frozenset(
+    {
+        "1m", "3m", "5m", "15m", "30m", "1h", "2h", "4h",
+        "6h", "8h", "12h", "1d", "3d", "1w", "1M",
+    }
+)
+
+SUPPORTED_PURPOSES: frozenset[str] = frozenset(
+    {
+        "higher_timeframe", "structure", "setup", "execution",
+        "indicator", "liquidity", "general",
+    }
+)
+
+
+def _error(message: str, status: int) -> web.Response:
+    return web.json_response(
+        {"error": {"message": message, "status": status}},
+        status=status,
+    )
+
+
+def _positive_int(value: str | None, *, name: str, default: int) -> int:
+    if value is None or value == "":
+        return default
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise ValueError(f"{name} must be an integer.") from exc
+    if parsed < 1:
+        raise ValueError(f"{name} must be at least 1.")
+    return parsed
+
+
+def register_routes(app: web.Application, manager: MarketDataManager) -> None:
+    app["market_data_manager"] = manager
+    app.router.add_get("/health", health)
+    app.router.add_get("/api/v1/market-data/candles", candles)
+    app.router.add_get("/api/v1/market-data/stream", market_stream)
+
+
+async def health(request: web.Request) -> web.Response:
+    manager: MarketDataManager = request.app["market_data_manager"]
+    return web.json_response(
+        {
+            "status": "ok",
+            "service": "classified",
+            "exchange": manager.exchange_name,
+            "exchangeConnected": manager.is_connected(),
+            "liveMarketStream": True,
+        }
+    )
+
+
+async def candles(request: web.Request) -> web.Response:
+    manager: MarketDataManager = request.app["market_data_manager"]
+    symbol = request.query.get("symbol", "").strip()
+    timeframe = request.query.get("timeframe", "").strip()
+    purpose = request.query.get("purpose", "general").strip()
+
+    if not symbol:
+        return _error("Query parameter 'symbol' is required.", 400)
+    if not timeframe:
+        return _error("Query parameter 'timeframe' is required.", 400)
+    if timeframe not in SUPPORTED_TIMEFRAMES:
+        return _error("Unsupported timeframe.", 400)
+    if purpose not in SUPPORTED_PURPOSES:
+        return _error("Unsupported purpose.", 400)
+
+    try:
+        candle_count = _positive_int(
+            request.query.get("candle_count"),
+            name="candle_count",
+            default=150,
+        )
+    except ValueError as exc:
+        return _error(str(exc), 400)
+
+    if candle_count > 1000:
+        return _error("candle_count cannot exceed 1000.", 400)
+
+    try:
+        market_request = MarketDataRequest(
+            symbol=symbol,
+            timeframe=timeframe,  # type: ignore[arg-type]
+            candle_count=candle_count,
+            purpose=purpose,  # type: ignore[arg-type]
+        )
+        result = manager.fulfill_request(market_request)
+    except MarketDataUnavailableError as exc:
+        return _error(str(exc), 503)
+    except ValueError as exc:
+        return _error(str(exc), 400)
+    except Exception as exc:
+        return _error(f"Unexpected market-data error: {exc}", 500)
+
+    return web.json_response({"data": market_data_result_to_dict(result)})