feat(router): Implement Layer 1 Intent Router & ProjectService Integration

[APT-KK]

Proposed change

Resolves #2991

This PR implements the Layer 1 Intent Router by me and integrates it with the ProjectService (Layer 2) by @Ruddxxy to optimize query handling. The system classifies user queries as STATIC or DYNAMIC to reduce LLM load and latency for deterministic questions.

Key Implementations:

Layer 1: Intent Router

    NLP Engine: Integrated spaCy (en_core_web_sm) for fast entity detection and keyword matching.

    Smart Caching: Added Redis to cache intent results. Repeated queries return in <20ms.

    Resiliency: Implemented a Fail-Open Circuit Breaker. If Redis is unreachable, the router falls back to computing intents via spaCy without crashing.

Layer 2: Service Integration by 

    ProjectService Logic: Implemented logic to consume router intents. High-confidence intents flow to the Static Handler; ambiguous ones flow to the Vector Store.

    Ambiguity Handling: Added confidence threshold checks. Queries with score <0.65 trigger a clarification prompt or fall through to the LLM.

    Fallback Strategy: If the Router fails entirely, the system fails open to Hybrid Search to ensure the user always receives a response.

Testing

    Added a comprehensive test suite in backend/tests/ covering cache hits, circuit breaker failure modes, and the Layer 1 -> Layer 2 handshake.

Technical Decision (ADR):

Why spaCy? I chose spaCy over SetFit/Transformers for Layer 1 to keep the Docker image lightweight (~150MB vs ~2.5GB) and to minimize latency for trivial queries.

Verification: Run the new test suite:
python -m unittest backend/tests/test_router.py backend/tests/test_suite.py

Checklist
[x] Required: I read and followed the contributing guidelines
[x] Required: I ran make check-test locally and all tests passed
[x] I used AI for code, documentation, or tests in this PR

[coderabbitai]

Caution

Review failed

The pull request is closed.

Summary by CodeRabbit

• New Features

  • Introduced AI query processing with intelligent intent detection to classify queries as static or dynamic.
  • Added per-user rate limiting to control request volumes.
  • Implemented Redis-based caching for improved query performance.
  • Added fail-open circuit breaker for system resilience.

• Tests

  • Added comprehensive router and integration test coverage.

• Chores

  • Updated Docker Compose configuration.
  • Enhanced security headers.
  • Updated project dependencies.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

Implements a multi-layer Intent Router and ProjectService integration for the Nestbot AI assistant. Adds Pydantic DTOs, a Redis-backed intent router using spaCy NLP classification, rate limiting, query orchestration, supporting Redis infrastructure, and diagnostic tests. A code defect exists with self parameter in module-level function.

Changes

Cohort / File(s)	Summary
Data Transfer Objects backend/apps/ai/core/dtos.py	Introduces four Pydantic DTOs: AIQueryDTO (text, project_id), RouterIntentDTO (label, confidence), ProjectPublicDTO (name, maintainers, url, description with extra field filtering), and AIResponseDTO (answer, source, optional intent, show_manual_search_btn).
Router Infrastructure backend/apps/ai/router/client.py, backend/apps/ai/router/intent.py, backend/apps/ai/router/limiter.py	RedisRouterClient creates singleton Redis connection pool with 50ms timeout. IntentRouter classifies queries as STATIC/DYNAMIC using spaCy heuristics and Redis caching (1-hour TTL, SHA-256-based keys). RateLimiter enforces 20 requests per 60 seconds per user with fail-open fallback.
Router Package Exports backend/apps/ai/router/__init__.py	Exports public classes: IntentRouter, RateLimiter, RedisRouterClient.
Project Service Layer backend/apps/ai/core/services/project_service.py	Introduces ProjectService orchestrating query lifecycle: routes via IntentRouter, applies confidence threshold (0.65), returns static data if intent is STATIC, falls back to hybrid retrieval with circuit breaker. Contains module-level function with incorrect self parameter.
Test & Diagnostic Suites backend/tests/router_test.py, test_suite.py	router_test.py adds mocked unit tests for IntentRouter covering cache hits, circuit breaker resilience, entity extraction, dynamic fallback, and edge cases. test_suite.py provides integration diagnostics: config validation, end-to-end processing, ambiguity handling, and circuit breaker verification.
Configuration & Infrastructure .gitignore, docker-compose.yml, docs/requirements.txt	.gitignore adds .env, .venv, users.acl, dump.rdb. docker-compose.yml adds redis-stack-server service on port 6379 with ACL support. docs/requirements.txt pins documentation and AI dependencies (mkdocs, redis, spaCy 3.7.2, en_core_web_sm-3.7.1 wheel).
Security Headers proxy/headers.conf	Reorders Permissions-Policy directives; adds X-Frame-Options: DENY and X-Permitted-Cross-Domain-Policies: none.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

• backend/apps/ai/core/services/project_service.py: Contains a critical defect—module-level get_project_details() function incorrectly uses self parameter outside class scope. The orchestration logic spans async/sync boundaries and fail-open behavior requires careful validation.
• backend/apps/ai/router/intent.py: Distributed caching logic with spaCy integration, Redis error handling, and confidence thresholding needs verification of cache key derivation and pattern matching behavior.
• backend/apps/ai/router/limiter.py: Rate limit implementation relies on Redis atomicity; fail-open behavior under unavailability should be validated.
• Heterogeneous scope: Multiple new modules across DTOs, services, and infrastructure require cross-module consistency checks (e.g., DTO field usage in service, Redis timeouts in both client and limiter).

Possibly related PRs

• Nestbot MVP #2113: Implements complementary Nestbot AI assistant Slack integration that consumes the Intent Router and ProjectService components defined in this PR.

Suggested labels

backend, backend-tests, nestbot, Nestbot-ai-assistant

Suggested reviewers

• arkid15r
• kasya

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fa51648 and fd1f137.

📒 Files selected for processing (12)

• .gitignore (1 hunks)
• backend/apps/ai/core/dtos.py (1 hunks)
• backend/apps/ai/core/services/project_service.py (1 hunks)
• backend/apps/ai/router/__init__.py (1 hunks)
• backend/apps/ai/router/client.py (1 hunks)
• backend/apps/ai/router/intent.py (1 hunks)
• backend/apps/ai/router/limiter.py (1 hunks)
• backend/tests/router_test.py (1 hunks)
• docker-compose.yml (1 hunks)
• docs/requirements.txt (1 hunks)
• proxy/headers.conf (1 hunks)
• test_suite.py (1 hunks)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

The PR must be linked to an issue assigned to the PR author.

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[arkid15r]

It seems check-issue workflow needs to be updated to handle non-default branches too.