realtimex-services-api 0.1.6__tar.gz

realtimex_services_api-0.1.6/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.3
+Name: realtimex-services-api
+Version: 0.1.6
+Summary: Add your description here
+Author: rta_phuongnguyen
+Author-email: rta_phuongnguyen <phuongnguyen@rtanalytics.vn>
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: realtimex-agent-flows-mcp-server
+Requires-Dist: dotenv
+Requires-Dist: realtimex-agent-flows-builder
+Requires-Dist: realtimex-agent-a2a-agent
+Requires-Dist: arize-phoenix-otel
+Requires-Dist: openinference-instrumentation-langchain
+Requires-Dist: openinference-instrumentation-mcp
+Requires-Dist: litellm==1.77.1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# RealTimeX Services API
+
+A production-ready FastAPI application providing commonly used services in a maintainable, modular structure. This project is built on a feature-based architecture to ensure scalability and clear separation of concerns.
+
+## Features
+
+- **Agent Flows**: A self-contained module providing testing, validation, and streaming endpoints for flow execution.
+- **Feature-Based Modular Architecture**: Code is organized by business domain (e.g., "agent flows") for high cohesion and low coupling.
+- **Production Ready**: Proper error handling, type hints, and dependency management.
+- **Health Monitoring**: Built-in health check endpoints for observability.
+- **API Versioning**: Endpoints are versioned (e.g., `/api/v1/...`) for long-term stability.
+- **OpenAPI Documentation**: Auto-generated and interactive API documentation.
+
+## Project Structure
+
+The project follows a feature-based (vertical slice) architecture. All code related to a specific business domain is co-located within a "module".
+
+```
+src/realtimex_services_api/
+├── __init__.py
+├── main.py                 # FastAPI app initialization and router inclusion
+├── cli.py                  # CLI entry point
+├── core/                   # Shared application-wide logic (config, dependencies)
+└── modules/                # Top-level directory for all feature modules
+    ├── __init__.py
+    └── agent_flows/        # A self-contained module for the "Agent Flows" feature
+        ├── __init__.py
+        ├── api.py          # FastAPI router and HTTP-related logic
+        ├── service.py      # Core business logic, decoupled from the web framework
+        ├── schemas.py      # Pydantic models and data contracts
+        └── utils/          # Utility functions specific to this module
+            ├── __init__.py
+            └── ...
+```
+
+## Installation
+
+```bash
+# Install dependencies
+uv sync
+
+# Or using pip
+pip install -e .
+```
+
+## Usage
+
+### Running the Server
+
+```bash
+# Using the CLI command
+realtimex-services-api
+
+# Or directly with Python
+python -m realtimex_services_api.cli
+
+# Or with uvicorn directly
+uvicorn realtimex_services_api.main:app --host 0.0.0.0 --port 8004
+```
+
+### API Endpoints
+
+- **GET /** - Root endpoint with service information
+- **GET /health** - Health check for monitoring
+- **GET /docs** - OpenAPI documentation (Swagger UI)
+- **GET /redoc** - Alternative API documentation
+- **POST /api/v1/agent-flows/action/test** - Execute flow in test mode
+- **POST /api/v1/agent-flows/action/validate** - Validate flow configuration
+- **POST /api/v1/agent-flows/chat/stream** - Stream chat responses
+
+## Development
+
+### Adding a New Feature Module
+
+The architecture makes adding new, independent features straightforward.
+
+1.  **Create the Module Directory**:
+    Create a new folder inside `src/realtimex_services_api/modules/`.
+    ```bash
+    mkdir src/realtimex_services_api/modules/new_feature
+    ```
+
+2.  **Create Standard Files**:
+    Inside the new directory, create the essential files: `__init__.py`, `api.py` (for the router), `service.py` (for business logic), and `schemas.py` (for Pydantic models).
+
+3.  **Implement the Logic**:
+    -   Define your FastAPI router in `api.py`.
+    -   Write your business logic in `service.py`, keeping it decoupled from FastAPI.
+    -   Define your request/response models in `schemas.py`.
+
+4.  **Include the Router in `main.py`**:
+    Import and include the new router from your module's `api.py` file.
+
+    ```python
+    # In main.py
+    from .modules.new_feature.api import router as new_feature_router
+
+    app.include_router(
+        new_feature_router,
+        prefix="/api/v1/new-feature",
+        tags=["New Feature"]
+    )
+    ```
+
+### Code Standards
+
+- **Type Hints**: All functions should include proper type annotations.
+- **Docstrings**: Public functions and modules should have clear docstrings.
+- **Error Handling**: The service layer raises domain-specific exceptions; the API layer translates them into HTTP error responses.
+- **Import Organization**: Follow PEP 8 import ordering.
+
+## Configuration
+
+The application reads configuration from `~/.realtimex.ai/Resources/server/.env.development`:
+
+- `LLM_PROVIDER`: openai, realtimexai, or ollama
+- `OPEN_AI_KEY`: OpenAI API key (when using openai provider)
+- `REALTIMEX_AI_BASE_PATH`: Base URL for RealTimeX AI
+- `REALTIMEX_AI_API_KEY`: API key for RealTimeX AI
+- `OLLAMA_BASE_PATH`: Base URL for Ollama
+
+## Architecture Decisions
+
+### Why This Structure?
+
+1.  **High Cohesion, Low Coupling**: All code for a single feature (API, logic, models) lives in one place, making it self-contained. Modules have minimal dependencies on each other.
+2.  **Scalability**: The application grows by adding new, independent modules. This prevents the complexity of the project from growing exponentially.
+3.  **Improved Developer Experience**: It's easy to find all code related to a feature. A developer can understand the scope of a feature by looking inside its module directory.
+4.  **Clear Boundaries**: The separation between the HTTP layer (`api.py`) and the business logic layer (`service.py`) is strictly enforced, improving testability and reusability.
+5.  **Easy to Refactor or Extract**: A self-contained feature module is much easier to modify, delete, or extract into its own microservice if needed.
+
+## License
+
+Internal RealTimeX project - All rights reserved.

realtimex_services_api-0.1.6/README.md

@@ -0,0 +1,134 @@
+# RealTimeX Services API
+
+A production-ready FastAPI application providing commonly used services in a maintainable, modular structure. This project is built on a feature-based architecture to ensure scalability and clear separation of concerns.
+
+## Features
+
+- **Agent Flows**: A self-contained module providing testing, validation, and streaming endpoints for flow execution.
+- **Feature-Based Modular Architecture**: Code is organized by business domain (e.g., "agent flows") for high cohesion and low coupling.
+- **Production Ready**: Proper error handling, type hints, and dependency management.
+- **Health Monitoring**: Built-in health check endpoints for observability.
+- **API Versioning**: Endpoints are versioned (e.g., `/api/v1/...`) for long-term stability.
+- **OpenAPI Documentation**: Auto-generated and interactive API documentation.
+
+## Project Structure
+
+The project follows a feature-based (vertical slice) architecture. All code related to a specific business domain is co-located within a "module".
+
+```
+src/realtimex_services_api/
+├── __init__.py
+├── main.py                 # FastAPI app initialization and router inclusion
+├── cli.py                  # CLI entry point
+├── core/                   # Shared application-wide logic (config, dependencies)
+└── modules/                # Top-level directory for all feature modules
+    ├── __init__.py
+    └── agent_flows/        # A self-contained module for the "Agent Flows" feature
+        ├── __init__.py
+        ├── api.py          # FastAPI router and HTTP-related logic
+        ├── service.py      # Core business logic, decoupled from the web framework
+        ├── schemas.py      # Pydantic models and data contracts
+        └── utils/          # Utility functions specific to this module
+            ├── __init__.py
+            └── ...
+```
+
+## Installation
+
+```bash
+# Install dependencies
+uv sync
+
+# Or using pip
+pip install -e .
+```
+
+## Usage
+
+### Running the Server
+
+```bash
+# Using the CLI command
+realtimex-services-api
+
+# Or directly with Python
+python -m realtimex_services_api.cli
+
+# Or with uvicorn directly
+uvicorn realtimex_services_api.main:app --host 0.0.0.0 --port 8004
+```
+
+### API Endpoints
+
+- **GET /** - Root endpoint with service information
+- **GET /health** - Health check for monitoring
+- **GET /docs** - OpenAPI documentation (Swagger UI)
+- **GET /redoc** - Alternative API documentation
+- **POST /api/v1/agent-flows/action/test** - Execute flow in test mode
+- **POST /api/v1/agent-flows/action/validate** - Validate flow configuration
+- **POST /api/v1/agent-flows/chat/stream** - Stream chat responses
+
+## Development
+
+### Adding a New Feature Module
+
+The architecture makes adding new, independent features straightforward.
+
+1.  **Create the Module Directory**:
+    Create a new folder inside `src/realtimex_services_api/modules/`.
+    ```bash
+    mkdir src/realtimex_services_api/modules/new_feature
+    ```
+
+2.  **Create Standard Files**:
+    Inside the new directory, create the essential files: `__init__.py`, `api.py` (for the router), `service.py` (for business logic), and `schemas.py` (for Pydantic models).
+
+3.  **Implement the Logic**:
+    -   Define your FastAPI router in `api.py`.
+    -   Write your business logic in `service.py`, keeping it decoupled from FastAPI.
+    -   Define your request/response models in `schemas.py`.
+
+4.  **Include the Router in `main.py`**:
+    Import and include the new router from your module's `api.py` file.
+
+    ```python
+    # In main.py
+    from .modules.new_feature.api import router as new_feature_router
+
+    app.include_router(
+        new_feature_router,
+        prefix="/api/v1/new-feature",
+        tags=["New Feature"]
+    )
+    ```
+
+### Code Standards
+
+- **Type Hints**: All functions should include proper type annotations.
+- **Docstrings**: Public functions and modules should have clear docstrings.
+- **Error Handling**: The service layer raises domain-specific exceptions; the API layer translates them into HTTP error responses.
+- **Import Organization**: Follow PEP 8 import ordering.
+
+## Configuration
+
+The application reads configuration from `~/.realtimex.ai/Resources/server/.env.development`:
+
+- `LLM_PROVIDER`: openai, realtimexai, or ollama
+- `OPEN_AI_KEY`: OpenAI API key (when using openai provider)
+- `REALTIMEX_AI_BASE_PATH`: Base URL for RealTimeX AI
+- `REALTIMEX_AI_API_KEY`: API key for RealTimeX AI
+- `OLLAMA_BASE_PATH`: Base URL for Ollama
+
+## Architecture Decisions
+
+### Why This Structure?
+
+1.  **High Cohesion, Low Coupling**: All code for a single feature (API, logic, models) lives in one place, making it self-contained. Modules have minimal dependencies on each other.
+2.  **Scalability**: The application grows by adding new, independent modules. This prevents the complexity of the project from growing exponentially.
+3.  **Improved Developer Experience**: It's easy to find all code related to a feature. A developer can understand the scope of a feature by looking inside its module directory.
+4.  **Clear Boundaries**: The separation between the HTTP layer (`api.py`) and the business logic layer (`service.py`) is strictly enforced, improving testability and reusability.
+5.  **Easy to Refactor or Extract**: A self-contained feature module is much easier to modify, delete, or extract into its own microservice if needed.
+
+## License
+
+Internal RealTimeX project - All rights reserved.

realtimex_services_api-0.1.6/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "realtimex-services-api"
+version = "0.1.6"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "rta_phuongnguyen", email = "phuongnguyen@rtanalytics.vn" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi",
+    "uvicorn",
+    "realtimex-agent-flows-mcp-server",
+    "dotenv",
+    "realtimex-agent-flows-builder",
+    "realtimex-agent-a2a-agent",
+    "arize-phoenix-otel",
+    "openinference-instrumentation-langchain",
+    "openinference-instrumentation-mcp",
+    "litellm==1.77.1"
+]
+
+# [tool.uv.sources]
+# agent-flows-mcp-server = { git = "https://oauth2:5yTHSE9k34jbWgzXmsxQ@rtgit.rta.vn/rtlab/rtwebteam/mcp-servers/realtimex-ai-agent-flows", branch = "main" }
+# agent-flows-builder = { git = "https://oauth2:5yTHSE9k34jbWgzXmsxQ@rtgit.rta.vn/rtlab/rtwebteam/realtimex-agent-flows-builder", branch = "main" }
+# realtimex-agent-a2a-agent = { git = "https://oauth2:5yTHSE9k34jbWgzXmsxQ@rtgit.rta.vn/rtlab/rtwebteam/realtimex-agent-a2a-agent", branch = "main" }
+# realtimex-agent-a2a-agent = { path = "/Users/phuongnguyen/Documents/projects/realtimex-agent-a2a-agent" }
+
+[project.scripts]
+realtimex-services-api = "realtimex_services_api.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8.2,<0.9.0"]
+build-backend = "uv_build"

realtimex_services_api-0.1.6/src/realtimex_services_api/__init__.py

@@ -0,0 +1,11 @@
+"""
+RealTimeX Services API
+
+Production-ready FastAPI application providing commonly used services
+in a maintainable, modular structure.
+"""
+
+from .main import app
+
+__version__ = "0.1.0"
+__all__ = ["app"]

realtimex_services_api-0.1.6/src/realtimex_services_api/cli.py

@@ -0,0 +1,15 @@
+"""
+CLI entry point for RealTimeX Services API
+
+Provides command-line interface for running the FastAPI application
+using uvicorn server with production-ready configuration.
+"""
+
+import uvicorn
+
+from .main import app
+
+
+def main() -> None:
+    """Main entry point for the CLI application."""
+    uvicorn.run(app, host="0.0.0.0", port=8004, reload=False, workers=1)

realtimex_services_api-0.1.6/src/realtimex_services_api/main.py

@@ -0,0 +1,49 @@
+"""
+RealTimeX Services API - Main FastAPI Application
+
+Production-ready FastAPI application providing commonly used services
+in a maintainable, modular structure.
+"""
+import sys
+
+from fastapi import FastAPI
+
+from .modules.a2a_agents import a2a_agents_router
+from .modules.agent_flows import agent_flows_router
+from .modules.python_interpreter import python_interpreter_router
+from .telemetry import initialize_tracing
+
+
+# Configure Phoenix tracing once for the application process
+initialize_tracing()
+
+# Initialize FastAPI application
+app = FastAPI(
+    title="RealTimeX Services API",
+    description="Production-ready API providing commonly used services",
+    version="0.1.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+# Include routers with appropriate prefixes
+app.include_router(agent_flows_router, prefix="/agent-flows")
+app.include_router(a2a_agents_router, prefix="/a2a-agents")
+app.include_router(python_interpreter_router, prefix="/python-interpreter")
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint for monitoring and load balancers."""
+    return {"status": "healthy", "service": "realtimex-services-api"}
+
+
+@app.get("/")
+async def root():
+    """Root endpoint with basic service information."""
+    return {
+        "service": "RealTimeX Services API",
+        "version": "0.1.0",
+        "docs": "/docs",
+        "health": "/health",
+    }

realtimex_services_api-0.1.6/src/realtimex_services_api/modules/__init__.py

@@ -0,0 +1,6 @@
+"""
+RealTimeX Services API Modules
+
+Domain-based modules containing API endpoints, business logic, and schemas
+organized by feature/domain for better maintainability and growth.
+"""

realtimex_services_api-0.1.6/src/realtimex_services_api/modules/a2a_agents/__init__.py

@@ -0,0 +1,10 @@
+"""
+Agent Flows Module
+
+Provides Agent Flows testing, validation, and streaming functionality.
+Contains API endpoints, business logic, schemas, and utilities for agent flows.
+"""
+
+from .api import a2a_agents_router
+
+__all__ = ["a2a_agents_router"]

realtimex_services_api-0.1.6/src/realtimex_services_api/modules/a2a_agents/api.py

@@ -0,0 +1,107 @@
+"""A2A Agents API Router."""
+
+import traceback
+from typing import Any
+
+from fastapi import APIRouter, Body, HTTPException, Request
+from fastapi.responses import JSONResponse
+from openinference.instrumentation import using_metadata
+from realtimex_agent_a2a_agent import RealTimeXAgent
+
+# Initialize router with tags for OpenAPI documentation
+a2a_agents_router = APIRouter(tags=["a2a-agents"])
+
+
+def _create_error_response(
+    status_code: int, error_code: str, message: str, details: dict = None
+) -> JSONResponse:
+    """Create standardized error response."""
+    content = {
+        "success": False,
+        "error": {
+            "code": error_code,
+            "message": message,
+        },
+    }
+    if details:
+        content["error"]["details"] = details
+
+    return JSONResponse(status_code=status_code, content=content)
+
+
+@a2a_agents_router.post("/sessions")
+async def create_a2a_session(request: Request, body: Any = Body(None)) -> JSONResponse:
+    """
+    Create A2A session
+    """
+    try:
+        payload = body["payload"]
+        a2a_port = body["a2a_port"]
+        execution_id = body["execution_id"]
+
+        system_prompt = None
+        agent_framework = None
+        agent_description = None
+        default_model = None
+        provider_name = None
+        llm_setting = None
+
+        execution_id = payload["session_id"]
+        agent_id = payload["agent_id"]
+        agent_data = payload["agent_data"]
+        user_id = payload["user_id"]
+        workspace_slug = payload["workspace_slug"]
+        thread_id = payload["thread_id"]
+        knowledges = payload["knowledges"]
+        memory_id = payload["memory_id"]
+        memory_path = payload["memory_path"]
+        message = payload["query"]
+        messages = payload["messages"]
+        aci_linked_account_owner_id = payload["aci_linked_account_owner_id"]
+        aci_agent_first_api_key = payload["aci_api_key"]
+        realtimex_access_token = payload["realtimex_access_token"]
+
+        if "agent_description" in payload:
+            agent_description = payload["agent_description"]
+        if "agent_framework" in payload:
+            agent_framework = payload["agent_framework"]
+        if "system_prompt" in payload:
+            system_prompt = payload["system_prompt"]
+        if "llm_setting" in payload:
+            llm_setting = payload["llm_setting"]
+
+        default_openai_base_url = payload["litellm_api_base"]
+        default_openai_api_key = payload["litellm_api_key"]
+
+        trace_metadata = {
+            "realtimex_user_id": user_id,
+            "workspace_slug": workspace_slug,
+            "thread_id": thread_id,
+            "session_id": execution_id,
+        }
+
+        with using_metadata(trace_metadata):
+
+            # Load MCP tools
+            
+            # Create agent
+            agent = RealTimeXAgent(current_session_id=execution_id)
+
+            await agent.load_default_agent(agent_id, agent_data, payload)
+            
+            server_url = await agent.serve_as_a2a(a2a_serving_config={"port":a2a_port,"stream_tool_usage":True})
+        
+
+        return {"server_url": server_url}
+
+    except HTTPException as e:
+        if e.status_code == 400:
+            return _create_error_response(400, "INVALID_INPUT", e.detail)
+        elif e.status_code == 404:
+            return _create_error_response(404, "USER_NOT_FOUND", e.detail)
+        else:
+            return _create_error_response(e.status_code, "REQUEST_ERROR", e.detail)
+    except Exception as e:
+        print(traceback.format_exc())
+        return _create_error_response(500, "INTERNAL_ERROR", str(e))
+

realtimex_services_api-0.1.6/src/realtimex_services_api/modules/agent_flows/__init__.py

@@ -0,0 +1,10 @@
+"""
+Agent Flows Module
+
+Provides Agent Flows testing, validation, and streaming functionality.
+Contains API endpoints, business logic, schemas, and utilities for agent flows.
+"""
+
+from .api import agent_flows_router
+
+__all__ = ["agent_flows_router"]