数据分析平台

Deploy

Frontend: Connect the repo to Vercel, Netlify, or similar; set env vars; deploy on push.

Backend: Run the FastAPI server behind a reverse proxy (nginx, Caddy) or deploy as a Docker container. Set DATABASE_URL for PostgreSQL in production.

Quick start with Make (recommended)

make install        # Install frontend and backend dependencies
make run            # Build frontend and start the server at http://localhost:8000

Other useful commands:

make install-cli    # Install only the data-talks CLI
make build          # Build frontend for production
make dev            # Start backend + frontend dev server with hot reload
make migrate        # Run database migrations
make setup-env      # Create backend/.env from .env.example
make lint           # Run frontend linter
make test           # Run frontend tests
make help           # List all available commands

Requires: Node.js, uv, and Python 3.11+.

---

How to use

By default, the app runs in guest mode: no login required. Choose your language (PT/EN/ES) and start.

1. Workspace: From the home page, select or create a workspace. Pick a workspace type — Data Analysis (GA), CDP (Beta), or ETL (Beta).
2. Data sources: In the Sources panel, upload CSV/XLSX/JSON/Parquet/SQLite, connect BigQuery/Google Sheets/Excel Online, add SQL/MongoDB/Snowflake databases, point at S3/REST APIs, or pick a SaaS integration (Stripe, Salesforce, HubSpot, …).
3. Source onboarding: Right after a source is added — or after selecting "All active sources" in Source Settings — the wizard walks through clarifications, warm-ups, filter suggestions, KPIs, and a per-source instructions field. Skip any time; re-run later via the refresh icon next to "Available Columns".
4. Agent setup: Configure name, specific instructions, LLM config (or leave blank to use your default LlmConfig), data sources, manually-typed warm-ups. For multiple SQL sources, configure relationships (SQL Links) and optionally enable SQL mode.
5. Ask questions: In the Chat panel, ask in natural language. Click the column chips, KPI chips, or apply a filter from the popover next to the logs button to constrain the question.
6. Optional: Set up alerts, dashboards, Telegram/WhatsApp/Slack connections, Studio summaries, audio overviews, or expose the workspace via the MCP server for external tools.

When ENABLE_LOGIN=true in the backend, authentication is required before using the app and a JWT token is issued per organization.

LLM environment defaults

When you configure OPENAI_API_KEY in backend/.env, the backend uses these environment defaults unless you explicitly override them:

• Text model: gpt-4o-mini
• Audio model: gpt-4o-mini-tts

If you want different defaults, set OPENAI_MODEL and/or OPENAI_AUDIO_MODEL explicitly in backend/.env.

.venv\Scripts\activate # Windows

pip install -e . cp .env.example .env data-talks run ```

In backend/.env, if you only add OPENAI_API_KEY, the backend will automatically assume gpt-4o-mini for text and gpt-4o-mini-tts for audio as the environment fallback configuration.

• data-talks run — starts the API on 0.0.0.0:8000. Use --host and --port to override.
• data-talks migrate — runs database migrations.
• API: http://localhost:8000 · Docs: http://localhost:8000/docs

Backend only (API)

From the backend directory:

With uv:

cd backend
uv pip install -e .
cp .env.example .env
uv run data-talks run

With pip + venv: ```bash cd backend python -m venv .venv source .venv/bin/activate # Linux/macOS

GitHub-backed pipeline versioning

• Pipeline snapshots: Each pipeline edit creates an immutable version row
• GitHub OAuth integration: Versions can be pushed to a configured repo/branch as commits, giving full diff history
• Restore: Roll back any prior version

Q&A

• Conversational UI: Ask in Portuguese, English, or Spanish
• Visual answers: Auto-generated charts and tables, server-rendered as images
• Inline references: Click chips in the empty state to insert column names or KPIs into your question; pick filter values from a popover next to the logs button to constrain every follow-up
• Follow-up questions: Suggestions to dig deeper
• User feedback: Answer rating