Lang2SQL

우리는 함께 코드와 아이디어를 나누며 더 나은 데이터 환경을 만들기 위한 오픈소스 여정을 떠납니다. 🌍💡

A document-learning, read-only SQL analytics agent. Feed it your company's docs → it learns your business context → it keeps a separate set of definitions per team → it answers questions over an incomplete database → it remembers every definition and conversation.

👉 프로젝트 전체 그림(단일 SSOT): docs/PROJECT.md · 컨트리뷰터 한눈 가이드: docs/ARCHITECTURE.md

This is the v4.1 rebuild (배경/설계 의도: docs/discord_first_redesign_v4_1.md). Where most text-to-SQL projects compete on "generate better SQL," Lang2SQL competes on everything around the query: business-context learning, per-team semantics, robustness to messy databases, and memory. Discord is the Phase 1 interface, not the identity — Slack/Web are adapters on the same core.

V1 ships the simplest single implementation of each extension point, but the abstraction (port) is already in place, so v1.5/v2 plug in a new implementation without touching existing code — like a standard wall outlet where you swap the appliance, not the wiring.

Four ★ extension patterns sit behind core/ports/:

Everything outside tenancy/concierge.py depends only on these Protocols, so the concrete classes (OpenAI, Postgres, SQLite) are swappable at the seams.

Requires Python ≥ 3.10 and uv.

uv sync                       # create .venv and install deps

.venv/bin/python bench/ecommerce_demo.py

Shows the federation money-shot (one term, two team definitions, no conflict) and the safety gate (DROP/INSERT blocked, SELECT passes). See bench/README.md.

.venv/bin/lang2sql "list the tables"

The CLI assembles a real HarnessContext and runs one turn through the agent loop. With OPENAI_API_KEY set it calls gpt-4.1-mini; otherwise it uses the offline FakeLLM.

export DISCORD_BOT_TOKEN=...        # required
export OPENAI_API_KEY=...           # optional; offline FakeLLM if unset
export LANG2SQL_SECRET_KEY=...      # optional; Fernet key for secret encryption
.venv/bin/lang2sql-bot

The bot exits loudly if DISCORD_BOT_TOKEN is unset. Full setup and hosting: docs/DEPLOY.md. Copy .env.example to start.

Does:

• 3-scope semantic federation (org / team / user) — 동일 용어에 여러 레이어 정의가 존재하면 현재 채널 정의를 ★ 로 표시하고 전체 주입; LLM이 컨텍스트로 판단. term_custom registers definitions per scope (KV-backed); kind(metric/table/rule/dimension) · applies_to · tags 필드 지원.
• Safety pipeline with the V1 layers (whitelist + timeout), gating every query.
• Agent loop with nine tools: run_sql, explore_schema, enrich_schema, term_custom, org_setup, ingest_doc, confirm_ingest, remember, ask_user.
• Memory service (in-memory store + inject-all recall + manual /remember).
• Discord frontend (bot, commands, session router, render).
• Encrypted-at-rest secrets (Fernet) and SQLite-backed persistence.

Does NOT yet:

• Execute against a real database. PostgresExplorer is a V1 stub with canned orders/users schema and sample rows; real psycopg execution is v1.5.
• Reason without a key. Without OPENAI_API_KEY, the FakeLLM returns deterministic canned tool cycles — useful for wiring tests, not for answers.
• AST-precise SQL validation, function blocklists, cost gating, /semantic diff / /semantic promote, keyword/vector recall, automatic fact extraction, URL/Notion ingestion — all scoped to v1.5+.
• Persist across restarts by default: the V1 SqliteStore defaults to in-memory; point it at a file for durability.

Current status: V1 complete — enrich_schema and OKF bundle export are V1.5 features already shipped; next target is AST validation, SQLite file-mode default, and keyword recall.

See docs/discord_first_redesign_v4_1.md for the full architecture write-up.

처음 보시는 분은 docs/ARCHITECTURE.md — 디렉토리·레이어 책임, 한 메시지의 lifecycle, 어디를 수정하면 좋을지 가 한곳에 정리돼 있습니다.

git clone https://github.com/CausalInferenceLab/lang2sql.git
cd lang2sql
uv sync
.venv/bin/pytest -q          # 12 safety regressions + full suite must pass

• 새 기능에는 테스트 작성 (tests/test_<layer>.py)
• PR은 master 브랜치 대상, 커밋 메시지에 feat: / fix: / docs: prefix 사용
• 버그/기능 요청은 이슈로

Lang2SQL은 가짜연구소의 인과추론팀에서 개발 중인 프로젝트입니다. Licensed under the MIT License. 커뮤니티: Discord.

Role	Name	Skills	Interests
Project Manager	이동욱		LLM, Open Source, Causal Inference
AI Engineer	문찬국		LLM, Agentic RAG, Open Source
Data Engineer	박경태		LLM-driven Data Engineering
AI Engineer	손봉균		LLM, RAG, AI Planning
Data Scientist	안재일		LLM, Data Analysis, RAG
ML Engineer	이호민		Multi-Agent Systems
AI Engineer	최세영		LLM, RAG, Multi-Agent
Full-Stack Developer	황윤진		LLM Orchestration
AI Engineer	김경서		LLM, FinNLP, FDS, RAG
Data Engineer	홍지영		LLM, Data Engineering
Data Operator	이화림		LLM, Data Engineering
AI Engineer	조태민		LLM, RAG, Multi-Agent
AI Engineer	심세원		LLM, RAG, Multi-Agent
Business Analyst	서희진		LLM, Data Analysis

가짜연구소는 머신러닝과 AI 기술 발전에 중점을 둔 비영리 조직입니다. 공유, 동기부여, 그리고 협업의 기쁨이라는 핵심 가치를 바탕으로 영향력 있는 오픈소스 프로젝트를 만들어갑니다.

전 세계 5,000명 이상의 연구자들과 함께, 우리는 AI 지식의 민주화와 열린 협업을 통한 혁신 촉진에 전념하고 있습니다.

커뮤니티: 💬 Discord