claude-smart 0.2.46 → 0.2.48

package/plugin/vendor/reflexio/reflexio/server/README.md

@@ -6,6 +6,7 @@ Description: FastAPI backend server that processes user interactions to generate
 - [Main Entry Points](#main-entry-points)
 - [Cache](#cache)
 - [API Endpoints](#api-endpoints)
+- [Extension Registry](#extension-registry)
 - [LLM Client](#llm-client)
 - [Prompts](#prompts)
 - [Site Variables](#site-variables)
@@ -32,8 +33,10 @@ Description: FastAPI backend server that processes user interactions to generate
 
 ## Main Entry Points
 
-- **API**: `api.py` - FastAPI routes (only place to expose endpoints)
-- **Endpoint Helpers**: `api_endpoints/` - Bridge between routes and business logic
+- **API composer**: `api.py` - `create_app()` factory, middleware/capability wiring, OpenAPI auth decoration, and `core_router` aggregation
+- **Domain routes**: `routes/` - FastAPI route modules; add new public API surfaces here and include their routers in `api.py`
+- **Endpoint Helpers**: `api_endpoints/` - Shared handlers/helpers plus `RequestContext` used by route modules
+- **Extension Registry**: `extensions.py` - Capability and service registry for optional OSS/enterprise integrations
 - **Core Service**: `services/generation_service.py` - Main orchestrator
 
 ## Cache
@@ -55,7 +58,19 @@ Description: FastAPI backend server that processes user interactions to generate
 
 **Directory**: `api_endpoints/`
 
-**Detailed Documentation**: See [`api_endpoints/README.md`](api_endpoints/README.md) for the `RequestContext` contract and per-file handler map.
+**Route modules** live in `routes/` and are grouped by domain. `api.py` remains the composition root: it creates `core_router`, includes each domain router, and mounts the aggregate router into the FastAPI app. **Detailed handler documentation**: See [`api_endpoints/README.md`](api_endpoints/README.md) for the `RequestContext` contract and helper map.
+
+| Route file | Purpose |
+|------|---------|
+| `routes/system.py` | Root/health/version and operation status/cancel surfaces. |
+| `routes/interactions.py` | Publish, request/session/interaction retrieval, direct interaction writes, and clear-data operations. |
+| `routes/profiles.py` | Profile retrieval, statistics, rerun/manual generation, upgrade/downgrade, update/delete lifecycle routes. |
+| `routes/playbooks.py` | User/agent playbook retrieval, aggregation, lifecycle, status/update/delete, and application stats routes. |
+| `routes/search.py` | Unified search and entity-specific search/rerank routes. |
+| `routes/provenance.py` | Learning provenance and approval routes. |
+| `routes/evaluation.py` | Evaluation overview, regenerate jobs, grade-on-demand, shadow comparisons, pending tool calls, and stall-state routes. |
+| `routes/braintrust.py` | Braintrust connection/project/status/sync routes. |
+| `routes/config.py` | Config read/write and account identity routes. |
 
 | File | Purpose |
 |------|---------|
@@ -84,13 +99,24 @@ Description: FastAPI backend server that processes user interactions to generate
 
 **Pattern**: Core route handlers call `Reflexio` through `get_reflexio(org_id)`; endpoint helper files should not instantiate `Reflexio` directly.
 
+## Extension Registry
+
+**File**: `extensions.py`
+
+`CapabilityRegistry` lets deployments register optional routers, startup/shutdown hooks, and cross-cutting services without hardcoding enterprise-only imports into the OSS app. `create_app()` builds the active registry, stores it on `app.state.capability_registry`, installs capability routers/startup/shutdown hooks, and exposes typed service lookup through `ServiceKey`.
+
+**Pattern**: Optional integrations should register capabilities/services at app construction time and consume them through the registry; avoid importing enterprise implementations directly in OSS modules.
+
 ## LLM Client
 
 **Directory**: `llm/`
-**Entry Point**: `litellm_client.py` - `LiteLLMClient`
+**Entry Point**: `litellm_client.py` - `LiteLLMClient` facade composed from focused mixins
 
 Key files:
-- `litellm_client.py`: Unified LiteLLMClient using LiteLLM for multi-provider support
+- `litellm_client.py`: Stable import surface, client config/credential resolution, and `LiteLLMClient` facade
+- `_litellm_text_generation.py`, `_litellm_embedding.py`, `_litellm_structured_output.py`: Completion/tool-call, embedding, and structured-output mixins
+- `_litellm_json_extraction.py`, `_litellm_subprocess.py`, `_litellm_types.py`: JSON parsing, hard-timeout subprocess snapshots/workers, and shared public types/errors
+- `providers/`: Optional local/provider adapters (`claude-code/`, OpenClaw, local embedding, Nomic embedding); registration is opt-in via environment/config
 - `openai_client.py`: OpenAI implementation (legacy, do not use directly)
 - `claude_client.py`: Claude implementation (legacy, do not use directly)
 - `llm_utils.py`: Helper functions for Pydantic model conversion
@@ -188,6 +214,7 @@ python -m reflexio.server.scripts.manage_invitation_codes list --show-used
 - **Search preparation**: `pre_retrieval/` and `unified_search_service.py` handle query reformulation, document expansion, embeddings, and cross-entity search orchestration.
 - **Optimization/integrations**: `playbook_optimizer/` and `braintrust/` run candidate playbook optimization, rollout support, and Braintrust export/sync.
 - **Lineage**: `lineage/` resolves active records across superseded chains and schedules tombstone garbage collection for profile/playbook storage.
+- **Governance**: `governance/` defines subject-reference contracts and retention/barrier policy helpers used by storage and lineage paths.
 - **Persistence/config**: `storage/`, `configurator/`, and `operation_state_utils.py` provide storage abstractions, config loading, locks, bookmarks, progress, and cancellation.
 
 ### Orchestrator
@@ -219,7 +246,8 @@ Called by API endpoints via `Reflexio`
 
 ### Base Infrastructure
 
-- `base_generation_service.py`: Abstract base for all services (parallel extractor execution via ThreadPoolExecutor, `EXTRACTOR_TIMEOUT_SECONDS = 300` per-extractor safety timeout)
+- `base_generation_service.py`: Stable `BaseGenerationService` import surface plus service-specific orchestration hooks (parallel extractor execution via ThreadPoolExecutor, `EXTRACTOR_TIMEOUT_SECONDS = 300` per-extractor safety timeout)
+- `base_generation/`: Mixins for batch progress, config filtering, extraction lifecycle, should-run prechecks, status transitions, and usage billing that keep `base_generation_service.py` navigable without changing caller imports
 - `extractor_config_utils.py`: Shared utility for filtering extractor configs by source, `allow_manual_trigger`, and extractor names
 - `extractor_interaction_utils.py`: Per-extractor utilities for stride_size checking and source filtering
 - `operation_state_utils.py`: Centralized `OperationStateManager` for all `_operation_state` table interactions (progress tracking, concurrency locks, extractor/aggregator bookmarks, simple locks)
@@ -477,8 +505,9 @@ Pre-computed embeddings passed to storage methods via `query_embedding` paramete
 
 | File | Purpose |
 |------|---------|
-| `storage_base/` | BaseStorage interface split by domain (`_profiles.py`, `_playbook.py`, `_requests.py`, `_operations.py`, `_agent_run.py`, `_lineage.py`, `_shadow_verdicts.py`, `_stall_state.py`, `_share_links.py`) |
-| `sqlite_storage/` | SQLite-backed implementation split across the same domains, including lineage/tombstone support in `_lineage.py` |
+| `storage_base/` | BaseStorage interface split by domain. Legacy facades (`_profiles.py`, `_playbook.py`, `_agent_run.py`, etc.) preserve imports while subpackages (`profiles/`, `playbook/`, `agent_run/`, `governance/`) hold focused abstract store contracts. |
+| `sqlite_storage/` | SQLite-backed implementation split across matching facades and subpackages (`profiles/`, `playbook/`, `agent_run/`, `governance/`, `base/`), including governance-aware retention/barrier handling and lineage/tombstone support. |
+| `governance_validation.py` | Shared validation helpers for subject references and governance contracts before storage writes. |
 | `retention.py`, `retention_mixin.py` | Data retention and cleanup helpers |
 | `constants.py`, `error.py` | Storage constants and shared errors |
 
@@ -486,7 +515,7 @@ Pre-computed embeddings passed to storage methods via `query_embedding` paramete
 
 **Key Methods**:
 - CRUD: profiles, interactions, playbooks, results, requests, playbook aggregation change logs
-- `get_sessions(offset, top_k, session_id)` → `dict[str, list[RequestInteractionDataModel]]` (groups by session_id, supports offset/limit pagination)
+- `get_sessions(offset, top_k, session_id)` → `dict[str, list[RequestInteractionDataModel]]` (groups by session_id; paginates per-session — `top_k`/`offset` count sessions, and each returned session includes all of its requests)
 - `get_rerun_user_ids(user_id, start_time, end_time, source, agent_version)` → `list[str]` - Get distinct user IDs matching filters for rerun workflows (pushes filtering to storage layer)
 - `get_feedbacks(status_filter, feedback_status_filter)` - Filter by playbook status and approval status
 - `save_feedbacks()` → returns `list[Feedback]` with `feedback_id` populated (callers can ignore return)

package/plugin/vendor/reflexio/reflexio/server/__init__.py

@@ -230,5 +230,24 @@ if DEBUG_LOG_TO_CONSOLE:
         logging.ERROR
     )
 else:
-    # Default to WARNING level when DEBUG_LOG_TO_CONSOLE is not set or is false
-    root_logger.setLevel(logging.WARNING)
+    # Production (DEBUG_LOG_TO_CONSOLE off): emit INFO+ app logs to stdout so the
+    # container log driver (e.g. CloudWatch awslogs) captures business-logic audit
+    # lines — billing/webhook/enforcement, etc. Without an explicit handler the
+    # stdlib "handler of last resort" emits only WARNING+ to stderr, so INFO logs
+    # were silently dropped in production. Plain formatter (no colors/files/dedup)
+    # keeps this lean and log-driver friendly — none of the DEBUG-branch overhead.
+    root_logger.setLevel(logging.INFO)
+    if not any(isinstance(h, logging.StreamHandler) for h in root_logger.handlers):
+        prod_console_handler = logging.StreamHandler(sys.stdout)
+        prod_console_handler.setLevel(logging.INFO)
+        prod_console_handler.setFormatter(
+            logging.Formatter("%(asctime)s %(name)s %(levelname)s %(message)s")
+        )
+        root_logger.addHandler(prod_console_handler)
+
+    # Keep noisy loggers quiet even at INFO (mirror the debug branch's suppression).
+    for _noisy in ("litellm", "LiteLLM", "httpx", "httpcore", "openai", "urllib3"):
+        logging.getLogger(_noisy).setLevel(logging.WARNING)
+    logging.getLogger("reflexio.server.site_var.site_var_manager").setLevel(
+        logging.ERROR
+    )