REST API Deployment

Kafal can be deployed as an HTTP service to evaluate untrusted scripts and return JSON charting payloads to web, desktop, or mobile client applications.

API Server Pattern

Because Kafal has zero required external service dependencies, it can be embedded into standard Python web frameworks (FastAPI, Flask, Django, or standard http.server).

import json
import logging
from http.server import BaseHTTPRequestHandler, HTTPServer
import pandas as pd
from kafal.core.interpreter import KafalInterpreter
from kafal.utils.serializer import KafalSerializer

# Load market data into memory
OHLCV_DATA = pd.read_csv("market_data.csv", parse_dates=True, index_col=0)

class KafalAPIHandler(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/execute":
            self.send_response(404)
            self.end_headers()
            return

        content_length = int(self.headers.get("Content-Length", 0))
        post_data = self.rfile.read(content_length).decode("utf-8")

        try:
            request_json = json.loads(post_data)
            script = request_json.get("script", "")
            mode = request_json.get("mode", "strategy")

            # 1. Initialize engine
            intr = KafalInterpreter(
                initial_equity=100_000.0,
                commission_perc=0.0005,
                execution_mode="realistic"
            )

            # 2. Run script
            raw_result = intr.run(script, OHLCV_DATA, mode=mode)

            # 3. Serialize UI contract
            payload = KafalSerializer.serialize_payload(raw_result)

            # 4. Return JSON
            self.send_response(200)
            self.send_header("Content-Type", "application/json")
            self.end_headers()
            self.wfile.write(json.dumps({"success": True, "payload": payload}).encode("utf-8"))

        except Exception as e:
            self.send_response(400)
            self.send_header("Content-Type", "application/json")
            self.end_headers()
            self.wfile.write(json.dumps({"success": False, "error": str(e)}).encode("utf-8"))

if __name__ == "__main__":
    server = HTTPServer(("", 8080), KafalAPIHandler)
    print("Kafal API running on http://localhost:8080")
    server.serve_forever()

Request Schema

Clients submit script text and operational mode via JSON POST requests:

# Example HTTP POST request body
{
  "script": "fast = ta.sma(close, 10)\nslow = ta.sma(close, 30)\nplot(fast) - color=\"blue\"",
  "mode": "chart"
}