AI-Cognitive-Leap/agnes-the-ai-analyst
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agnes-the-ai-analyst/docs/QUICKSTART.md
ZdenekSrotyr 8233c3e3f9 chore(docs): replace stale da verbs and vendor-specific install paths 
Sweep operator runbooks (docs/QUICKSTART, docs/HEADLESS_USAGE,
docs/architecture, docs/sample-data, docs/agent-workspace-prompt,
docs/metrics/metrics.yml, dev_docs/server, dev_docs/disaster-recovery),
the corporate-memory service README, the jira connector README + backfill
scripts, the deploy skill, and test docstrings. Replaces `da sync` →
`agnes pull`, `da analyst setup` → `agnes init`, `da metrics ...` →
`agnes catalog --metrics` / `agnes admin metrics ...`, `da fetch` →
`agnes snapshot create`, plus the matching docker-compose admin
invocations.

Vendor-specific `/opt/data-analyst/` install paths in jira backfill /
consistency scripts and operator docs are replaced with the
placeholder `<install-dir>` and a new `AGNES_ENV_FILE` env-var override
that lets a deployment inject its actual install path without a code
change. Aligns with the OSS vendor-agnostic policy in CLAUDE.md.

CHANGELOG `### Internal` entry summarizes the audit and reaffirms the
intentional stale-marker tuples (`_LEGACY_STRINGS`, `_OUR_COMMAND_MARKERS`)
that must keep referencing `da sync` / `da fetch` / etc. for hook upgrade
and override-detection logic.
2026-05-04 21:22:19 +02:00

2.3 KiB
Raw Blame History

Quick Start Guide

Prerequisites

  • Python 3.10+
  • Docker + Docker Compose (for production deployment)
  • Data source credentials (Keboola token, BigQuery project, etc.)

Local Development Setup

  1. Clone the repository:

    git clone <repo-url>
cd ai-data-analyst

  2. Create virtual environment and install dependencies:

    python3 -m venv .venv && source .venv/bin/activate
uv pip install ".[dev]"

  3. Configure your instance:

    cp config/instance.yaml.example config/instance.yaml
# Edit config/instance.yaml with your settings

  4. Set up environment variables:

    cp config/.env.template .env
# Edit .env with your data source credentials

  5. Register your tables via the admin API or CLI:

    # Via CLI
agnes admin register-table --source-type keboola --bucket "in.c-crm" --table "company" --query-mode local

# Or start the server and use the web UI at /admin/tables

  6. Start the FastAPI server:

    uvicorn app.main:app --reload

  7. Trigger a data sync:

    curl -X POST http://localhost:8000/api/sync/trigger

Docker Deployment

# Start app + scheduler
docker compose up

# Include telegram bot
docker compose --profile full up

# HTTPS mode — Caddy + corporate-CA certs
docker compose -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.tls.yml \
    --profile tls up -d

See DEPLOYMENT.md for full server setup instructions.

Using with Claude Code

Open the project in Claude Code. The CLAUDE.md file will guide the AI assistant through setup and analysis workflows.

Analyst Setup

  1. Visit your instance URL (e.g., https://data.yourcompany.com)
  2. Sign in with your company email
  3. Access data through the API or download parquets for local analysis

Analysis Workflow

  1. Sync latest data: curl -X POST https://data.yourcompany.com/api/sync/trigger
  2. Open Claude Code in your project directory
  3. Ask Claude to analyze your data using DuckDB

Hackathon

See HACKATHON.md for the deploy-and-develop playbook. Per-developer dev VMs are the supported pattern — point your VM at your branch image with gcloud compute ssh <vm> --command "sudo sed -i 's/^AGNES_TAG=.*/AGNES_TAG=dev-<slug>/' /opt/agnes/.env && sudo /usr/local/bin/agnes-auto-upgrade.sh".