{"id":49639829,"url":"https://github.com/reyharighy/cba-agentic-ai","last_synced_at":"2026-05-05T18:49:28.963Z","repository":{"id":333168936,"uuid":"1136428494","full_name":"reyharighy/cba-agentic-ai","owner":"reyharighy","description":"Conversational Business Analytics (CBA – Agentic) is an experimental, open-source system for building agentic, LLM-driven business analytics workflows.","archived":false,"fork":false,"pushed_at":"2026-04-25T12:10:21.000Z","size":10063,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-05T18:49:12.934Z","etag":null,"topics":["agentic-ai-development","business-analytics","fastapi","langchain-python","langgraph-python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reyharighy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-17T17:13:49.000Z","updated_at":"2026-04-25T12:07:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"57412f55-18b5-4fe2-bce7-ac7eea15e092","html_url":"https://github.com/reyharighy/cba-agentic-ai","commit_stats":null,"previous_names":["reyharighy/cba-agentic-ai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/reyharighy/cba-agentic-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reyharighy%2Fcba-agentic-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reyharighy%2Fcba-agentic-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reyharighy%2Fcba-agentic-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reyharighy%2Fcba-agentic-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reyharighy","download_url":"https://codeload.github.com/reyharighy/cba-agentic-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reyharighy%2Fcba-agentic-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32663438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai-development","business-analytics","fastapi","langchain-python","langgraph-python"],"created_at":"2026-05-05T18:49:28.036Z","updated_at":"2026-05-05T18:49:28.957Z","avatar_url":"https://github.com/reyharighy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv id=\"top\"\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n# CONVERSATIONAL BUSINESS ANALYTICS\n\n\u003cem\u003eAgentic AI for Interactive Business Analytics \u0026 Reasoning\u003c/em\u003e\n\n\u003cem\u003eAgent Service Edition (API-first)\u003c/em\u003e\n\n\u003cem\u003eBuilt with:\u003c/em\u003e\n\n\u003cimg src=\"https://img.shields.io/badge/Python-3776AB.svg?style=flat\u0026logo=Python\u0026logoColor=white\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/LangGraph-4B5563.svg?style=flat\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/FastAPI-009688.svg?style=flat\u0026logo=FastAPI\u0026logoColor=white\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Groq-F55036.svg?style=flat\u0026logo=Groq\u0026logoColor=white\"\u003e\n\n\u003cbr\u003e\n\n\u003cimg src=\"https://img.shields.io/badge/Docker-2496ED.svg?style=flat\u0026logo=Docker\u0026logoColor=white\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/PostgreSQL-4169E1.svg?style=flat\u0026logo=PostgreSQL\u0026logoColor=white\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/SQLAlchemy-D71F00.svg?style=flat\u0026logo=SQLAlchemy\u0026logoColor=white\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/E2B-000000.svg?style=flat\u0026logo=E2B\u0026logoColor=white\"\u003e\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\n**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**.\n\nThis 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).\n\nThe system enables:\n\n- natural-language business queries,\n- explicit analytical planning and execution,\n- structured reasoning over relational data,\n- observation-driven correction loops,\n- and optional downstream visualization handled *outside* the agent service.\n\nThis project is a **research and learning platform** for agentic analytics — not a production BI tool.\n\n---\n\n## Project Status\n\n⚠️ **Active Development**\n\nThis branch provides a **cleanly separated architecture**, with emphasis on:\n\n- isolating the agent core from presentation concerns,\n- serving agent capabilities via a stable HTTP API,\n- improving observability and debuggability of agent workflows,\n- and enabling multiple UI clients without coupling.\n\n---\n\n## Architecture: Binary-Responsibility Agent Graph\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"Binary-Responsibility Agent Graph.png\" width=\"75%\" /\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\nThe system is built around a **Binary-Responsibility Agent Graph**, guided by the following principles:\n\n### 1. Binary Branching\n\nEach node has **at most two outgoing paths**, ensuring:\n- localized decisions,\n- predictable control flow,\n- traceable failure modes.\n\n### 2. Single Responsibility per Node\n\nEach node performs **one clearly defined task**, such as:\n- intent interpretation,\n- context distillation,\n- request classification,\n- planning,\n- execution,\n- observation.\n\nThis limits prompt complexity and error propagation.\n\n### 3. Explicit Planning–Execution–Observation Loops\n\nAnalytical reasoning follows a consistent loop:\n\n- **Plan** — generate a constrained, structured plan  \n- **Execute** — run code or actions in a controlled environment  \n- **Observe** — validate semantic and functional correctness  \n\nFailures trigger targeted correction loops rather than global retries.\n\n### 4. Visualization as a Downstream Concern\n\nVisualization and infographic generation are treated as **post-analysis consumers** of agent output:\n- analytical correctness is established first,\n- visual output is optional,\n- visualization failures do not invalidate analysis.\n\nThis improves system robustness.\n\n---\n\n## High-Level System Structure\n\n```sh\n.\n├── agent/              # LangGraph-based agent and node definitions (core logic)\n├── api/                # FastAPI service layer exposing the agent\n├── context/            # Runtime context shared across agent nodes\n├── docker_script/      # Database initialization \u0026 synthetic data seeding\n├── language_model/     # LLM abstraction layer\n└── memory/             # Conversational and short-term memory persistence\n```\n\n## Features\n\n- 🧠 **Agentic Reasoning Pipeline**\n\n  Intent → classification → planning → execution → observation.\n\n- 📊 **Business Analytics Focus**  \n\n  Supports descriptive, diagnostic, predictive, and inferential analysis.\n\n- 🧾 **Structured LLM Outputs**\n\n  Enforced via Pydantic schemas.\n\n- 🧩 **LangGraph-based Orchestration**\n\n  Explicit state transitions and execution control.\n\n- 🐳 **Containerized Agent Service**\n\n  FastAPI-based backend, UI-agnostic\n\n- 🔒 **Sandboxed Code Execution**\n\n  Analytical Python code runs in isolated E2B sandbox environments, separated from the OLTP data source.\n\n- 🗃️ **External PostgreSQL Integration**\n- 🧪 **Synthetic Data Seeding for Development**\n\n## Running the Agent Service (Development)\n\n### Prerequisites\n\nYou will need:\n\n- **Docker**\n- **Docker Compose**\n- **Git**\n\nNo local Python installation is required if using Docker.\n\n### Environment Setup\n\nThis project uses environment variables for configuration.\n\n1. Copy the example file:\n\n    ```sh\n    cp .env.example .env\n    ```\n\n2. Fill in required values:\n\n- API keys (Groq, E2B, optional LangSmith)\n- PostgreSQL credentials (defaults work for Docker)\n- `AGENT_API_PORT` (default: 8000)\n\n### Start the Service\n\n```sh\ndocker compose up --build\n```\n\nOnce running, the agent API will be available to test with Swagger docs:\n\n```sh\nhttp://localhost:8000/docs#/\n```\n\nYou can try using cURL to test the agent stream endpoint.\n\n```sh\ncurl -X 'POST' \\\n  'http://localhost:8000/agent/stream' \\\n  -H 'accept: application/json' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n  \"input\": \"What is the best-selling product in March 2024?\"\n}'\n```\n\nHealth check endpoint:\n\n```sh\nGET /health\n```\n\n## Synthetic Data \u0026 External Database\n\nThis project depends on an external PostgreSQL database to simulate business data.\n\n- Synthetic data is stored in docker_script/synthetic_data.csv\n- The script external_database_factory.py:\n  - creates the schema,\n  - populates the database,\n  - runs automatically on container startup if enabled.\n\nControlled via environment variable:\n\n```env\nENABLE_EXTERNAL_DB_SEEDING=true\n```\n\nThis allows:\n\n- zero-setup onboarding for new users,\n- reproducible analytical scenarios,\n- safe experimentation without real business data.\n\n## Notes for Contributors\n\n- This project prioritizes clarity over cleverness\n- Explicit state \u003e implicit magic\n- If something is ambiguous, it should probably be a schema\n- If something is implicit, it should probably be a graph edge\n- UI concerns do not belong in the agent core or service layer\n\n\u003cbr\u003e\n\n---\n\n\u003cdiv align=\"left\"\u003e\u003ca href=\"#top\"\u003e⬆ Return\u003c/a\u003e\u003c/div\u003e\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freyharighy%2Fcba-agentic-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freyharighy%2Fcba-agentic-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freyharighy%2Fcba-agentic-ai/lists"}