Ontology RL Commerce Agent

Ontology RL Commerce Agent provides an RL-powered open loop that combines ontology reasoning, ecommerce business logic, memory, and a Gradio UI to deliver an end-to-end shopping assistant experience. It leverages a Model Context Protocol (MCP) to orchestrate tools, context, and user conversations, enabling safer tool chaining and continuous improvement through reinforcement learning.

How to use

You run the MCP server locally and connect your client to the MCP endpoints to start a shopping session. Use the MCP server as the central brain for planning, tool invocation, memory recall, and execution of ecommerce actions. The Agent UI lets you see the reasoning plan, tool calls, memory, analytics, and execution logs in one place. Start sessions, ask for product recommendations, check stock, add items to cart, create orders, and track shipments through the same interface.

How to install

Prerequisites:

• Python 3.10+ installed on your system
• Docker and Docker Compose if you prefer containerized deployment
• 8 GB+ RAM for inference and demos (32 GB+ for RL training)

Option: Run the MCP server directly (stdio) using a local Python environment: uvicorn ontology_mcp_server.server:app --host 0.0.0.0 --port 8000This starts the MCP Server listening on port 8000. You may need to set the data directory for your runtime:export ONTOLOGY_DATA_DIR="$(pwd)/data"Option: Run via Docker Compose (recommended for a quick start):docker-compose up -d After startup, MCP Server will be available at http://localhost:8000 and the UI will be accessible via the Gradio frontend at http://localhost:7860 and the training dashboard at http://localhost:7861.

Configuration and runtime environment

The setup uses several environment variables to configure storage, UI, and LLM access. The following variables are commonly used during runtime:

• ONTOLOGY_DATA_DIR: Path to persistent data storage (e.g., data/)
• APP_HOST, APP_PORT: Web server host and port for the MCP frontend
• MCP_BASE_URL: Base URL for the MCP server if you run components separately
• OPENAI_API_URL, OPENAI_API_KEY, OPENAI_MODEL: LLM provider credentials (if you use OpenAI-compatible APIs)
• LLM_PROVIDER: Local/remote LLM provider name (e.g., deepseek, ollama)
• GRADIO_SERVER_NAME, GRADIO_SERVER_PORT: Gradio UI host/port
• AGENT_HOST, AGENT_PORT: Agent UI binding
• TRAINING_DASHBOARD_HOST, TRAINING_DASHBOARD_PORT: RL training dashboard binding
• LOG_DIR, TB_LOG_DIR: Log and tensorboard directories
• MEMORY_ENABLED, MEMORY_BACKEND, CHROMA_PERSIST_DIR, MEMORY_RETRIEVAL_MODE, MEMORY_MAX_TURNS: Memory configuration for ChromaDB and retrieval settings If you run in Docker, these values are typically configured in the .env file or docker-compose environment blocks.

mcpServers configuration

The MCP server can be run as a local stdio process. The following configuration invokes the MCP server directly using uvicorn and exposes the server on port 8000. This captures the argument structure exactly as shown.

{
  "mcpServers": {
    "ontology_mcp": {
      "type": "stdio",
      "name": "ontology_mcp",
      "command": "uvicorn",
      "args": ["ontology_mcp_server.server:app", "--host", "0.0.0.0", "--port", "8000"],
      "env": [
        {"name": "ONTOLOGY_DATA_DIR", "value": "${PWD}/data"}
      ]
    }
  }
}

Available tools

ontology.explain_discount

Explain discount context using ontology reasoning to justify pricing and promotions.

ontology.normalize_product

Normalize product data fields to a consistent schema for retrieval and display.

ontology.validate_order

Validate an order against SHACL rules before processing payment.

commerce.search_products

Search the product catalog and return relevant items with filters.

commerce.get_product_detail

Return detailed product information including specs and pricing.

commerce.check_stock

Check current stock status for a given product.

commerce.get_product_recommendations

Provide personalized product recommendations based on history and membership tier.

commerce.get_product_reviews

Fetch user reviews and ratings for a product.

commerce.add_to_cart

Add a selected product to the user's shopping cart.

commerce.view_cart

Display current cart contents and totals.

commerce.remove_from_cart

Remove items from the cart.

commerce.create_order

Create a new order from the cart contents after validation.

commerce.get_order_detail

Retrieve detailed information about a specific order.

commerce.cancel_order

Cancel an existing order under allowed conditions.

commerce.get_user_orders

List all orders associated with a user.

commerce.process_payment

Handle payment processing for an order.

commerce.track_shipment

Track shipment status for an order.

commerce.get_shipment_status

Get real-time status of current shipment.

commerce.create_support_ticket

Open a customer support ticket for an order or product issue.

commerce.process_return

Process a return or exchange request.

commerce.get_user_profile

Fetch user profile and preferences.