🧠 NeuroCouncil

An AI-powered decision-support system that transforms e-commerce data into explainable and actionable business recommendations.

NeuroCouncil combines structured business metrics, customer reviews, market signals, and large language models through a modular multi-agent architecture. It is designed to help e-commerce teams move from fragmented data to concrete decisions in pricing, advertising, inventory, and customer experience.

Problem

E-commerce businesses often collect large volumes of sales, advertising, inventory, and review data, but these sources are usually analysed separately. This makes it difficult to answer cross-functional questions such as:

• Which products require a pricing adjustment?
• Is poor advertising performance caused by targeting, pricing, or customer sentiment?
• Which products are at risk of overstocking or running out of stock?
• What recurring complaints are affecting conversion?
• Which actions should be prioritised based on both quantitative metrics and qualitative feedback?

NeuroCouncil addresses this problem by coordinating specialised AI agents that analyse different evidence sources and produce a consolidated, traceable recommendation.

Core Capabilities

• Sales and conversion analysis: examines revenue, order volume, conversion rates, and product-level performance.
• Advertising analysis: evaluates campaign efficiency and ROAS-related signals.
• Inventory monitoring: identifies low-stock, overstock, and demand-related risks.
• Review intelligence: extracts recurring complaints, customer preferences, sentiment, and product-level themes.
• Trend and anomaly detection: detects significant changes across products and time periods.
• Decision support: converts analytical findings into prioritised business recommendations.
• Natural-language interaction: allows users to ask business questions without manually navigating multiple dashboards.

Multi-Agent Architecture

NeuroCouncil follows a modular agent-based design in which each agent is responsible for a clearly defined analytical task.

• Metrics Agent Analyses structured sales, revenue, conversion, advertising, and inventory metrics.

• Review Agent Processes unstructured customer reviews and extracts sentiment, recurring themes, complaints, and product-level observations.

• Trend Agent Detects patterns, changes, and anomalies across products and time periods.

• Suggestion Agent Converts analytical findings into practical, prioritised recommendations.

• Insight Agent Synthesises outputs from the specialised agents and produces the final decision-support response.

flowchart TD
    A[Business question] --> B[Request router]
    B --> C[Metrics Agent]
    B --> D[Review Agent]
    B --> E[Trend Agent]
    C --> F[Suggestion Agent]
    D --> F
    E --> F
    F --> G[Insight Agent]
    G --> H[Actionable recommendation]

Loading

This separation of responsibilities makes the system easier to test, extend, and debug than a single large prompt or monolithic agent.

How It Works

1. The user submits a business question.
2. The request router determines which analytical capabilities are required.
3. Relevant agents retrieve and analyse structured or unstructured data.
4. Intermediate findings are passed to the Suggestion Agent.
5. The Insight Agent combines the evidence into a final recommendation.
6. The system returns a concise response containing findings, supporting signals, and proposed actions.

The architecture is designed to separate deterministic data processing from LLM-based reasoning. Numerical calculations are performed with conventional data-processing tools, while language models are used for interpretation, synthesis, and recommendation generation.

Demonstration Dataset

The current demonstration environment represents a Trendyol-style home and lifestyle seller dataset containing:

• 142 products/SKUs
• 8,340 customer reviews
• 12 months of historical observations
• Sales, advertising, inventory, and customer-feedback signals

The dataset is used only for demonstration and development. Real customer credentials and private marketplace data are not included in this repository.

Technology Stack

AI and data

• Python
• LangChain
• OpenAI, Gemini, and Claude APIs
• Chroma vector database
• Pandas
• NumPy

Application layer

• Flask
• REST API
• Modular agent and tool architecture
• Environment-based configuration

Experimentation

• CrewAI has been explored for agent orchestration experiments.
• The current application flow uses modular Python components and LangChain-based integrations.

API Overview

The backend exposes endpoints for system access and report generation:

Method	Endpoint	Purpose
GET	/	Service status and basic information
POST	/ask	Submit a business question to the decision-support system
POST	/report	Generate a structured analytical report

Exact request and response schemas may evolve as the project is developed.

Project Structure

.
├── tools/              # Deterministic tools used by the agents
├── data/               # Local datasets; excluded from version control
├── outputs/            # Generated analyses and reports; excluded from version control
├── app.py              # Flask application and API entry point
├── agents.py           # Agent definitions and responsibilities
├── router.py           # Request routing and agent selection
├── requirements.txt    # Python dependencies
└── README.md

The exact file structure may vary as components are refactored.

Local Setup

1. Clone the repository

git clone https://github.com/003733m/NeuroCouncil.git
cd NeuroCouncil

2. Create a virtual environment

python -m venv .venv

Activate it:

# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment variables

Create a local .env file and add only the providers you intend to use:

OPENAI_API_KEY=your_key_here
GEMINI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here

Do not commit .env files or real API credentials.

5. Run the application

python app.py

The local API will normally be available at:

http://127.0.0.1:5000

Design Decisions

Specialised agents instead of a single prompt

Separating metrics, reviews, trends, and recommendations reduces prompt complexity and makes individual components easier to evaluate.

Deterministic calculations before LLM reasoning

Revenue, conversion, inventory, and advertising calculations should not depend on free-form model generation. These values are computed with Python and passed to the language model as structured evidence.

Retrieval for relevant context

Vector search is used to retrieve relevant review content instead of placing the entire review dataset into the model context. This improves relevance and reduces unnecessary token usage.

Provider-independent model access

The system is designed to work with multiple LLM providers, allowing experiments with cost, latency, and response quality without coupling the application to a single model.

Explainable recommendations

The intended output is not merely a recommendation. Each proposed action should be connected to supporting metrics, trends, or customer-feedback evidence.

Security and Data Isolation

The repository does not contain production credentials or private customer datasets.

The architecture is being developed with the following principles:

• Environment variables for secret management
• Separation of customer data from application code
• Dataset and output directories excluded from version control
• Tenant-aware storage and retrieval as a requirement for production deployment
• Validation of model inputs and outputs
• Restricted tool access for agent workflows
• No direct execution of model-generated code

Before production use, the system would require stronger authentication, authorisation, audit logging, tenant isolation, rate limiting, monitoring, and secret-management infrastructure.

Current Limitations

• Recommendations depend on the quality and completeness of the input data.
• LLM-generated interpretations may require human validation.
• The demonstration dataset does not represent every e-commerce category or marketplace.
• Marketplace integrations and credential management are not included in the public version.
• The project is a decision-support system and does not automatically execute pricing, advertising, or inventory changes.
• Production-grade evaluation, monitoring, and access control remain areas for further development.

Roadmap

• Add formal agent-level and end-to-end evaluation
• Introduce structured output validation with Pydantic
• Add automated tests for analytical tools and API endpoints
• Implement tenant-aware retrieval and storage
• Add marketplace connectors through secure APIs
• Introduce recommendation confidence and supporting-evidence fields
• Add observability for latency, token usage, failures, and model quality
• Containerise the application with Docker
• Add CI/CD checks for testing and code quality
• Build a human-in-the-loop approval workflow
• Add an interactive demonstration interface

What This Project Demonstrates

NeuroCouncil demonstrates practical experience in:

• Designing modular AI-assisted systems
• Building multi-agent and tool-using workflows
• Developing retrieval-augmented applications
• Combining structured and unstructured data
• Designing REST-based AI services
• Applying LLMs to real business problems
• Separating deterministic analytics from generative reasoning
• Considering explainability, privacy, and production constraints

Author

Mehmet Ali Toy Computer Engineering graduate, Hacettepe University AI engineering interests: LLM applications, RAG, multi-agent systems, NLP, machine learning, and scientific foundation models.

• GitHub: 003733m
• LinkedIn: Mehmet Ali Toy

---

NeuroCouncil is an independently developed portfolio project intended to demonstrate applied AI engineering and decision-support system design.