ask_data

# NDEA NDEA (`Nexus Data Expert Agent`) is currently a campus query system that only provides **MCP services**. Current production form: - Only external entrance: `MCP` - Main query tool: `mcp_query_v2` - Main workflow: `QueryGraphV2` - Learning library: `ndea_learning` - Vector library: `Milvus` Removed: - Independent HTTP query interface - Portal query service - Portal-specific MCP packaging layer - Old planner/workflow/sql_generation/sql_rag/vector_locator chain ## Technology Stack - `FastMCP` - `LangGraph` - `MySQL` - `Milvus` - `SQLGlot` - Optional `LlamaIndex` - Optional `Langfuse` ## Operating Environment - Python `3.11` to `3.13` - Not recommended to use Python `3.14` ## Installation ```powershell py -3.13 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -U pip python -m pip install -e .[dev] ``` If optional capabilities are needed: ```powershell python -m pip install -e .[dev,nl2sql,observability] ``` ## Environment Variables Example see [.env.example](.env.example). Key configurations: - `NDEA_MYSQL_HOST` - `NDEA_MYSQL_PORT` - `NDEA_MYSQL_USER` - `NDEA_MYSQL_PASSWORD` - `NDEA_MYSQL_DATABASE` - `NDEA_LEARNING_MYSQL_DATABASE` - `NDEA_MILVUS_URI` - `NDEA_MILVUS_COLLECTION` - `NDEA_MILVUS_COLLECTION_SQL_CASES` - `NDEA_MILVUS_COLLECTION_QUERY_MEMORY` - `NDEA_EMBEDDING_BASE_URL` - `NDEA_EMBEDDING_MODEL` - `NDEA_NL2SQL_ENGINE` - `NDEA_LLAMAINDEX_ENGINE_FACTORY` - `NDEA_LANGFUSE_PUBLIC_KEY` - `NDEA_LANGFUSE_SECRET_KEY` - `NDEA_LANGFUSE_HOST` - `NDEA_ENABLE_QUERY_EXECUTION` - `NDEA_ENABLE_SEMANTIC_RETRIEVAL` ## Startup Method Start MCP service with foreground real-time logs: ```powershell .\start.cmd ``` Default MCP address: ```text http://127.0.0.1:8001/mcp/ ``` Hot reload: ```powershell .\start.ps1 -Reload ``` Custom listening address and port: ```powershell .\start.ps1 -ListenHost 0.0.0.0 -Port 8001 ``` Equivalent native command: ```powershell .\.venv\Scripts\fastmcp.exe run src\ndea\main.py:app --transport http --host 127.0.0.1 --port 8001 ``` If `stdio` transport method is needed: ```powershell .\.venv\Scripts\fastmcp.exe run src\ndea\main.py:app ``` ## MCP Tools Default registered tools: - `mcp_query_v2` - `execute_guarded_query` - `inspect_table_schema` - `system_status` ## Current Query Process Main workflow nodes are as follows: 1. `interaction` 2. `intent_parse` 3. `semantic_resolve` 4. `schema_resolve` 5. `build_plan_candidates` 6. `generate_sql_candidates` 7. `verify_candidates` 8. `rank_candidates` 9. `confidence_gate` 10. `execute` 11. `respond` 12. `learn` Meaning can be summarized as: - Context rewriting first - Then intent and campus semantic parsing - Then schema bottoming - Generate multiple SQL candidates - Verification, sorting, execution - Finally, write to the learning library ## Learning Loop Learning data will not be written back to the business library, but to an independent `ndea_learning`. Main tables: - `query_session` - `interaction_turn` - `ir_snapshot` - `plan_candidate` - `sql_candidate` - `execution_result` - `feedback_event` - `promotion_queue` - `alias_memory` - `value_synonym_memory` - `clarification_memory` - `sql_case_memory` ## Directory Description Currently retained main directories: - `src/ndea/services` - `src/ndea/orchestration` - `src/ndea/interaction` - `src/ndea/understanding` - `src/ndea/semantic` - `src/ndea/resolution` - `src/ndea/generation` - `src/ndea/verification` - `src/ndea/ranking` - `src/ndea/execution` - `src/ndea/learning` - `src/ndea/query_v2` - `src/ndea/tools` - `src/ndea/vector` - `src/ndea/security` - `src/ndea/metadata` Removed bypass modules: - `src/ndea/http` - `src/ndea/portal` - Old query planning and old SQL generation chain ## Test Run full test: ```powershell .\.venv\Scripts\python.exe -m pytest -q ``` Current result: - `70 passed` - `1 skipped` Test focus: - MCP tools - v2 components - v2 integration link - Milvus/MySQL basic capabilities - Runtime and health check ## Current Status Current repository is: - MCP-only - v2-only - Milvus-only That is, the old HTTP/Portal/legacy planner production bypass is no longer retained. The only main path of the project is `mcp_query_v2 -> QueryServiceV2 -> QueryGraphV2`.