https://github.com/reyharighy/cba-agentic-ai
Conversational Business Analytics (CBA – Agentic) is an experimental, open-source system for building agentic, LLM-driven business analytics workflows.
https://github.com/reyharighy/cba-agentic-ai
agentic-ai-development business-analytics fastapi langchain-python langgraph-python
Last synced: about 1 month ago
JSON representation
Conversational Business Analytics (CBA – Agentic) is an experimental, open-source system for building agentic, LLM-driven business analytics workflows.
- Host: GitHub
- URL: https://github.com/reyharighy/cba-agentic-ai
- Owner: reyharighy
- Created: 2026-01-17T17:13:49.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-25T12:10:21.000Z (about 2 months ago)
- Last Synced: 2026-05-05T18:49:12.934Z (about 1 month ago)
- Topics: agentic-ai-development, business-analytics, fastapi, langchain-python, langgraph-python
- Language: Python
- Homepage:
- Size: 9.6 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# CONVERSATIONAL BUSINESS ANALYTICS
Agentic AI for Interactive Business Analytics & Reasoning
Agent Service Edition (API-first)
Built with:
---
## Overview
**Conversational Business Analytics (CBA)** is an experimental, open-source system for building **agentic, LLM-driven analytical workflows** that can reason, compute, observe results, and expose those capabilities via a **service-oriented API**.
This branch focuses on **serving the agent as a FastAPI-based backend**, intended to be consumed by one or more external user interfaces (e.g. Streamlit, web apps, notebooks).
The system enables:
- natural-language business queries,
- explicit analytical planning and execution,
- structured reasoning over relational data,
- observation-driven correction loops,
- and optional downstream visualization handled *outside* the agent service.
This project is a **research and learning platform** for agentic analytics — not a production BI tool.
---
## Project Status
⚠️ **Active Development**
This branch provides a **cleanly separated architecture**, with emphasis on:
- isolating the agent core from presentation concerns,
- serving agent capabilities via a stable HTTP API,
- improving observability and debuggability of agent workflows,
- and enabling multiple UI clients without coupling.
---
## Architecture: Binary-Responsibility Agent Graph
The system is built around a **Binary-Responsibility Agent Graph**, guided by the following principles:
### 1. Binary Branching
Each node has **at most two outgoing paths**, ensuring:
- localized decisions,
- predictable control flow,
- traceable failure modes.
### 2. Single Responsibility per Node
Each node performs **one clearly defined task**, such as:
- intent interpretation,
- context distillation,
- request classification,
- planning,
- execution,
- observation.
This limits prompt complexity and error propagation.
### 3. Explicit Planning–Execution–Observation Loops
Analytical reasoning follows a consistent loop:
- **Plan** — generate a constrained, structured plan
- **Execute** — run code or actions in a controlled environment
- **Observe** — validate semantic and functional correctness
Failures trigger targeted correction loops rather than global retries.
### 4. Visualization as a Downstream Concern
Visualization and infographic generation are treated as **post-analysis consumers** of agent output:
- analytical correctness is established first,
- visual output is optional,
- visualization failures do not invalidate analysis.
This improves system robustness.
---
## High-Level System Structure
```sh
.
├── agent/ # LangGraph-based agent and node definitions (core logic)
├── api/ # FastAPI service layer exposing the agent
├── context/ # Runtime context shared across agent nodes
├── docker_script/ # Database initialization & synthetic data seeding
├── language_model/ # LLM abstraction layer
└── memory/ # Conversational and short-term memory persistence
```
## Features
- 🧠 **Agentic Reasoning Pipeline**
Intent → classification → planning → execution → observation.
- 📊 **Business Analytics Focus**
Supports descriptive, diagnostic, predictive, and inferential analysis.
- 🧾 **Structured LLM Outputs**
Enforced via Pydantic schemas.
- 🧩 **LangGraph-based Orchestration**
Explicit state transitions and execution control.
- 🐳 **Containerized Agent Service**
FastAPI-based backend, UI-agnostic
- 🔒 **Sandboxed Code Execution**
Analytical Python code runs in isolated E2B sandbox environments, separated from the OLTP data source.
- 🗃️ **External PostgreSQL Integration**
- 🧪 **Synthetic Data Seeding for Development**
## Running the Agent Service (Development)
### Prerequisites
You will need:
- **Docker**
- **Docker Compose**
- **Git**
No local Python installation is required if using Docker.
### Environment Setup
This project uses environment variables for configuration.
1. Copy the example file:
```sh
cp .env.example .env
```
2. Fill in required values:
- API keys (Groq, E2B, optional LangSmith)
- PostgreSQL credentials (defaults work for Docker)
- `AGENT_API_PORT` (default: 8000)
### Start the Service
```sh
docker compose up --build
```
Once running, the agent API will be available to test with Swagger docs:
```sh
http://localhost:8000/docs#/
```
You can try using cURL to test the agent stream endpoint.
```sh
curl -X 'POST' \
'http://localhost:8000/agent/stream' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"input": "What is the best-selling product in March 2024?"
}'
```
Health check endpoint:
```sh
GET /health
```
## Synthetic Data & External Database
This project depends on an external PostgreSQL database to simulate business data.
- Synthetic data is stored in docker_script/synthetic_data.csv
- The script external_database_factory.py:
- creates the schema,
- populates the database,
- runs automatically on container startup if enabled.
Controlled via environment variable:
```env
ENABLE_EXTERNAL_DB_SEEDING=true
```
This allows:
- zero-setup onboarding for new users,
- reproducible analytical scenarios,
- safe experimentation without real business data.
## Notes for Contributors
- This project prioritizes clarity over cleverness
- Explicit state > implicit magic
- If something is ambiguous, it should probably be a schema
- If something is implicit, it should probably be a graph edge
- UI concerns do not belong in the agent core or service layer
---
---