Skip to content

README.md

Latest commit

 

History

History
70 lines (53 loc) · 2.78 KB

README.md

File metadata and controls

70 lines (53 loc) · 2.78 KB
Raw

Reflex Hybrid Analytics Starter

Status: Alpha — Phase 0 complete (merged to main); Phase 1 in progress, unmerged, unverified

An aspirational production-conscious, open-source starter for building conversational analytics and hybrid relational, vector, and graph applications in Python. Eventual long term goal: Production quality (not yet ready).

Stack

  • Reflex-first modular monolith for the web application and server-side UI state, with embedded FastAPI/ASGI routes only where a normal HTTP API is genuinely needed.
  • PostgreSQL 16 as the primary database.
  • pgvector for vector similarity search.
  • Apache AGE for graph storage and Cypher queries.
  • PandasAI behind a replaceable adapter.
  • A separate worker service (ARQ) for long-running, CPU-intensive, generated-code, or retryable analytics jobs, with Redis for job delivery and PostgreSQL as the authoritative source of job state.
  • SQLAlchemy 2 + Alembic for persistence and migrations.
  • uv for Python dependency and workspace management, with apps/* and packages/* as workspace members.
  • Docker Compose for the complete local development environment.

This is not a GraphRAG framework, not a Neo4j replacement, not a low-code platform, not multi-tenant, and not a hosted SaaS.

Repository layout

apps/           Reflex web app and worker service
packages/core   Shared library code (config, db, models, services, auth, CLI)
migrations/     Alembic migrations
docker/postgres PostgreSQL 16 + AGE + pgvector image and init SQL
tests/          Pytest suite (database/integration markers)
docs/           Architecture notes and decision records
PROJECT/        Build plan and phase-by-phase project documentation (PDDA)

Getting started

Prerequisite: You must have uv installed.

uv sync --all-packages
docker compose -f compose.test.yaml up -d
uv run alembic upgrade head
uv run pytest -m "database or integration"

--all-packages is required, not optional: this is a uv workspace (apps/* + packages/*), and a plain uv sync only installs the root project — packages/core (starter_core) never gets linked in, so alembic upgrade head fails immediately with ModuleNotFoundError: No module named 'starter_core'.

For the full local stack (web + worker + Postgres + Redis):

docker compose -f compose.yaml -f compose.dev.yaml up -d
uv run alembic upgrade head

Build plan

This repo is built in phases, tracked in PROJECT/2-WORKING/PROJECT.md, starting with a PostgreSQL 16 + AGE + pgvector compatibility spike before any application code. See ROADMAP.md for current status.

License

Licensed under the Apache License 2.0. Copyright © Neochrome, Inc.