diff --git a/application/single_app/config.py b/application/single_app/config.py index c3ba0d92..5c740776 100644 --- a/application/single_app/config.py +++ b/application/single_app/config.py @@ -88,9 +88,8 @@ EXECUTOR_TYPE = 'thread' EXECUTOR_MAX_WORKERS = 30 SESSION_TYPE = 'filesystem' -# Allow overriding the session file directory; default to /app/flask_session with proper permissions -SESSION_FILE_DIR = os.getenv('SESSION_FILE_DIR', '/app/flask_session') -VERSION = "0.230.001" +VERSION = "0.229.063" + SECRET_KEY = os.getenv('SECRET_KEY', 'dev-secret-key-change-in-production') diff --git a/application/single_app/static/js/admin/admin_plugins.js b/application/single_app/static/js/admin/admin_plugins.js index 93c7a926..682d329d 100644 --- a/application/single_app/static/js/admin/admin_plugins.js +++ b/application/single_app/static/js/admin/admin_plugins.js @@ -4,7 +4,7 @@ import { renderPluginsTable as sharedRenderPluginsTable, validatePluginManifest // Main logic document.addEventListener('DOMContentLoaded', function () { - if (!document.getElementById('agents-tab')) return; + if (!document.getElementById('actions-configuration')) return; // Load and render plugins table loadPlugins(); diff --git a/docs/explanation/release_notes.md b/docs/explanation/release_notes.md index b44023f3..6ec26b6c 100644 --- a/docs/explanation/release_notes.md +++ b/docs/explanation/release_notes.md @@ -1,6 +1,17 @@ # Feature Release +### **(v0.229.063)** + +#### Bug Fixes + +* **Admin Plugins Modal Load Fix** + * Fixed issue where Admin Plugins modal would fail to load when using sidenav navigation. + * **Root Cause**: JavaScript code attempted to access DOM elements that didn't exist in sidenav navigation. + * **Solution**: Corrected DOM element checks to ensure compatibility with both top-nav and sidenav layouts. + * **User Experience**: Admins can now access the Plugins modal reglardless of navigation style. + * (Ref: `admin_plugins.js`, DOM existence checks) + ### **(v0.229.062)** #### Bug Fixes diff --git a/docs/features/v0.230.001/AUTOMATIC_SWAGGER_SCHEMA_GENERATION.md b/docs/features/v0.230.001/AUTOMATIC_SWAGGER_SCHEMA_GENERATION.md new file mode 100644 index 00000000..ac7b45bc --- /dev/null +++ b/docs/features/v0.230.001/AUTOMATIC_SWAGGER_SCHEMA_GENERATION.md @@ -0,0 +1,548 @@ +# AUTOMATIC_SWAGGER_SCHEMA_GENERATION Feature + +## Overview and Purpose +This feature provides comprehensive automatic schema generation and interactive API documentation for Flask endpoints using Abstract Syntax Tree (AST) analysis. It eliminates the need to manually define OpenAPI response schemas and parameter definitions while providing a powerful, searchable Swagger UI interface with authentication and security integration. + +**Version implemented:** 0.230.001 + +**Dependencies:** +- Flask web framework +- Python AST module for code analysis +- Python inspect module for function introspection +- textwrap module for source code normalization +- functions_authentication module for security integration +- Bootstrap 5.3.0 for Swagger UI styling +- Bootstrap Icons for interface elements + +## Technical Specifications + +### Architecture Overview +The automatic schema generation system consists of several integrated components: + +1. **Enhanced @swagger_route Decorator**: Extended with automatic schema generation and security integration +2. **AST Analysis Engine**: Parses function source code to extract return patterns and response structures +3. **Schema Inference System**: Converts AST nodes to OpenAPI 3.0 JSON schemas with validation +4. **Parameter Detection**: Analyzes function signatures for path/query parameters with type inference +5. **Security Integration**: Seamless authentication and authorization using `get_auth_security()` +6. **Interactive Swagger UI**: Enhanced interface with search, filtering, and real-time testing +7. **Caching & Performance**: Built-in caching with rate limiting and DDOS protection +8. **Admin Control**: Enable/disable functionality through admin settings interface + +### Core Functions + +#### 1. swagger_route Decorator +```python +# Fully automatic with security - recommended pattern! +@app.route('/api/users/') +@swagger_route(security=get_auth_security()) +@login_required +def get_user_data(user_id: int): + """Fetch user data from the database.""" + return jsonify({"result": "success", "count": 42, "user_id": user_id}) +``` + +**Enhanced Parameters:** +- `security: List[Dict[str, List[str]]] = None` - Authentication requirements (use `get_auth_security()` for standard auth) +- `auto_schema: bool = True` - Enable/disable automatic response schema generation +- `auto_summary: bool = True` - Enable/disable automatic summary from function name +- `auto_description: bool = True` - Enable/disable automatic description from docstring +- `auto_tags: bool = True` - Enable/disable automatic tags from route path +- `summary: str = ""` - Manual summary override +- `description: str = ""` - Manual description override +- `tags: List[str] = None` - Manual tags override +- `request_body: Dict = None` - Request body schema +- `responses: Dict = None` - Response schemas override +- `parameters: List[Dict] = None` - Parameter definitions override +- `deprecated: bool = False` - Mark endpoint as deprecated + +**Security Integration:** +The `get_auth_security()` function returns standardized security requirements: +```python +def get_auth_security(): + """Get standard authentication security requirements.""" + return [{"bearerAuth": []}, {"sessionAuth": []}] +``` + +This enables both JWT Bearer token and session-based authentication in the Swagger UI. + +#### 2. _analyze_function_returns() +Analyzes function return statements using AST parsing to generate response schemas: +- Detects `jsonify()` calls and extracts dictionary structures +- Handles tuple returns like `(jsonify(...), 400)` for status codes +- Supports nested objects and arrays +- Generates proper OpenAPI 3.0 response definitions + +#### 3. _analyze_function_parameters() +Analyzes function signatures to generate parameter documentation: +- Extracts parameters from function signature using `inspect.signature()` +- Infers types from type annotations +- Detects path parameters from route patterns +- Generates OpenAPI parameter schemas + +#### 4. _ast_to_schema() +Converts AST nodes to JSON Schema format: +- Handles dictionary literals with property extraction +- Supports arrays, strings, integers, floats, booleans +- Includes example values from literal values +- Provides fallback types for complex expressions + +#### 5. _generate_summary_from_function_name() +Converts function names to human-readable summaries: +- Transforms snake_case to Title Case +- `get_user_profile` → `"Get User Profile"` +- `fetch_analytics_data` → `"Fetch Analytics Data"` + +#### 6. _extract_tags_from_route_path() +Extracts meaningful tags from URL paths: +- Filters out common prefixes (`api`, `v1`, `v2`, etc.) +- Skips parameter segments (``) +- Capitalizes meaningful segments +- `/api/users/profile` → `["Users", "Profile"]` +- `/api/admin/reports/analytics` → `["Admin", "Reports", "Analytics"]` + +#### 7. _extract_file_tag() +Generates file-based organization tags: +- Extracts module name from view function's source file +- Converts module names to readable tags with emoji prefixes +- `route_backend_agents.py` → `"📄 Backend Agents"` +- `route_frontend_auth.py` → `"📄 Frontend Auth"` +- Helps organize endpoints by source file for easier navigation + +#### 8. get_auth_security() +Standardized security requirements function: +- Returns consistent authentication schemas for OpenAPI +- Supports both Bearer JWT and session-based authentication +- Integrates with Flask-Login and existing authentication system +- Enables "Try it out" functionality in Swagger UI with proper auth headers + +### File Structure +``` +application/single_app/ +├── swagger_wrapper.py # Core automatic schema generation system +├── route_backend_models.py # Example documented endpoints +└── static/swagger-ui/ # Local Swagger UI assets + ├── swagger-ui.css + ├── swagger-ui-bundle.js + └── swagger-ui-standalone-preset.js +``` + +### API Endpoints +- `GET /swagger` - Interactive Swagger UI with search and authentication (requires admin login) +- `GET /swagger.json` - OpenAPI 3.0 specification JSON (cached, rate limited) +- `GET /api/swagger/routes` - Route documentation status and cache statistics +- `GET /api/swagger/cache` - Cache management and statistics +- `DELETE /api/swagger/cache` - Clear swagger specification cache + +### Enhanced Swagger UI Features + +#### Interactive Search Interface +- **Real-time Search**: Multi-term search across endpoints, tags, methods, and descriptions +- **Quick Filter Buttons**: POST, GET, Backend, Frontend, Files, Admin, API shortcuts +- **Search Highlighting**: Matching terms highlighted in yellow for easy identification +- **Results Counter**: Shows "X of Y endpoints" with real-time updates +- **Keyboard Support**: ESC key to clear search, Enter to focus results + +#### Smart Organization +- **File-based Grouping**: Endpoints organized by source file with 📄 emoji prefixes +- **Tag Hierarchies**: Automatic and manual tags for multi-level organization +- **Empty Section Hiding**: Tag sections with no matching results automatically hidden +- **Collapsible Sections**: Click to expand/collapse endpoint groups + +#### Performance & Caching +- **Rate Limiting**: 30 requests per minute per IP for /swagger.json +- **Intelligent Caching**: 5-minute TTL with automatic invalidation on route changes +- **Client-side Caching**: ETag and Cache-Control headers for browser optimization +- **Background Processing**: Spec generation doesn't block UI rendering + +## Usage Instructions + +### Basic Usage (Fully Automatic with Security) +```python +from swagger_wrapper import swagger_route, get_auth_security +from functions_authentication import login_required + +@app.route('/api/users/') +@swagger_route(security=get_auth_security()) +@login_required +def get_user_profile(user_id: int): + """Retrieve detailed profile information for a specific user account.""" + return jsonify({ + "user_id": user_id, + "name": "John Doe", + "email": "john@example.com", + "active": True, + "created_at": "2024-01-01T00:00:00Z" + }) +``` + +**Automatically generates:** +- **Summary**: `"Get User Profile"` (from function name `get_user_profile`) +- **Description**: `"Retrieve detailed profile information for a specific user account."` (from docstring) +- **Tags**: `["📄 Route Backend Users", "Users"]` (file-based + path-based tags) +- **Parameters**: Path parameter `user_id` as integer type (from function signature) +- **Response Schema**: 5 properties with correct types and example values (from `jsonify()` call analysis) +- **Security**: Bearer token and session authentication requirements +- **Authentication**: Swagger UI "Try it out" includes proper auth headers + +### Manual Override Mode +```python +@app.route('/api/complex') +@swagger_route( + summary="Complex endpoint", + tags=["Advanced"], + auto_schema=False, # Disable automatic generation + responses={ + "200": { + "description": "Custom response definition", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "custom_field": {"type": "string"} + } + } + } + } + } + } +) +def complex_endpoint(): + return jsonify({"custom_field": "value"}) +``` + +### Error Response Handling +```python +@app.route('/api/data') +@swagger_route( + summary="Data endpoint with error handling", + tags=["Data"] +) +def data_endpoint(): + """Endpoint that can return different status codes.""" + error_type = request.args.get('error') + + if error_type == 'not_found': + return jsonify({"error": "Resource not found"}), 404 + elif error_type == 'bad_request': + return jsonify({"error": "Invalid parameters"}), 400 + + return jsonify({ + "data": [1, 2, 3], + "success": True + }) +``` + +**Automatically detects:** +- Multiple return paths with different status codes +- Error response schemas for 400, 404 status codes +- Success response schema for 200 status code + +### Integration Examples + +#### With Flask-RESTful Style and Authentication +```python +@app.route('/api/search') +@swagger_route( + summary="Search items", + tags=["Search"], + security=get_auth_security() +) +@login_required +def search_items(query: str = "", limit: int = 10, offset: int = 0): + """Search for items with pagination support.""" + results = perform_search(query, limit, offset) + + return jsonify({ + "query": query, + "limit": limit, + "offset": offset, + "total": len(results), + "items": results + }) +``` + +#### With Type Annotations +```python +from typing import List, Optional + +@app.route('/api/bulk-process') +@swagger_route( + summary="Bulk process items", + tags=["Processing"] +) +def bulk_process(items: List[str], async_mode: bool = False): + """Process multiple items in bulk.""" + return jsonify({ + "processed_items": len(items), + "async": async_mode, + "job_id": str(uuid.uuid4()) if async_mode else None + }) +``` + +## Admin Settings Integration + +### Enable/Disable Control +Swagger documentation can be controlled through the admin settings interface: + +1. **Admin Settings Location**: General Tab → API Documentation section +2. **Toggle Control**: "Enable Swagger/OpenAPI Documentation" switch +3. **Direct Access**: "Open Swagger UI" button for immediate testing +4. **Information Modal**: "Why Enable Swagger?" explains benefits and use cases + +### Admin Interface Features +```html + +
+ + +
+ +
+ + + Open Swagger UI + +
+``` + +### Security Considerations in Admin Settings +- **Authentication Required**: All Swagger endpoints require admin login +- **Rate Limiting**: Built-in protection against API discovery attacks +- **Settings Validation**: Changes take effect after application restart +- **Production Guidelines**: Detailed recommendations in info modal + +### Benefits Explanation (from Admin Modal) +- **Interactive Testing**: Test API endpoints directly from browser +- **Automatic Documentation**: Self-updating docs as routes are modified +- **Schema Validation**: Ensures request/response formats are correct +- **Developer Productivity**: Faster development and debugging cycles +- **Integration Support**: Easy API discovery for external systems +- **Security Visibility**: Clear authentication and authorization requirements + +## Testing and Validation + +### Functional Tests +Located in: `functional_tests/test_automatic_swagger_schema_generation.py` + +The test suite validates: +- Basic automatic schema generation +- Parameter detection from function signatures +- Response schema extraction from return statements +- Manual override functionality +- Docstring usage as descriptions +- Integration with Flask routing + +### Test Coverage +- **Response Schema Generation**: Tests jsonify() call parsing +- **Parameter Detection**: Tests path and query parameter inference +- **Type Inference**: Tests type annotation support +- **Error Handling**: Tests fallback to default schemas +- **Integration**: Tests with real Flask applications + +### Manual Testing Steps +1. Start the application with swagger routes registered +2. Visit `/swagger` to view interactive documentation +3. Verify auto-generated schemas match expected structure +4. Test API endpoints through Swagger UI +5. Check `/api/swagger/routes` for documentation coverage + +## Performance Considerations + +### AST Parsing Performance +- AST parsing is performed once during route registration (startup time) +- Parsed schemas are cached in function metadata +- No runtime performance impact on API requests +- Source code analysis adds ~1-2ms per route during startup +- Example: 166 endpoints generate in ~47ms total + +### Memory Usage +- Generated schemas are stored as function attributes +- Minimal memory overhead (~1KB per documented route) +- Total memory usage: ~147KB for 147 documented routes +- No impact on request/response payload sizes + +### Caching & Rate Limiting Performance +- **Swagger Spec Cache**: 5-minute TTL with intelligent invalidation +- **Cache Hit Performance**: Sub-millisecond response times +- **Rate Limiting**: 30 requests/minute per IP prevents DDOS +- **Client Caching**: ETag headers enable browser-level caching +- **Background Generation**: Spec creation doesn't block request processing +- **Thread Safety**: Proper locking for concurrent access + +## **🎯 Performance Impact Results** + +*Comprehensive testing conducted on production-scale application with full route documentation.* + +### ✅ **Swagger Spec Generation Performance** + +- **Average generation time**: 46.63ms +- **Generated specification size**: 319.7KB for 166 documented paths +- **Generation frequency**: One-time at startup + cache refresh cycles +- **Assessment**: Excellent - well under acceptable thresholds for API documentation + +**Analysis**: The 47ms generation time is negligible during application startup and only occurs when the cache expires or routes change. This represents a highly efficient documentation generation process. + +### ✅ **Memory Usage Analysis** + +- **Total application routes**: 203 +- **Documented routes**: 147 (72.4% documentation coverage) +- **Estimated metadata memory footprint**: ~147KB total +- **Per-route overhead**: ~1KB average per documented endpoint +- **Assessment**: Very reasonable memory footprint with minimal impact + +**Memory Efficiency**: The metadata storage represents less than 1% of typical application memory usage, making it practically negligible even for memory-constrained environments. + +### ✅ **Business Logic Performance Impact** + +- **Average API response time**: 30.82ms +- **Response time range**: 27.62ms to 50.48ms +- **Performance variance**: Minimal (consistent sub-50ms responses) +- **Assessment**: Excellent - zero measurable impact on business logic execution + +**Runtime Impact**: The decorator adds no measurable overhead to actual API request processing, confirming that documentation generation does not interfere with application performance. + +## **📊 Key Performance Findings** + +### **Production-Ready Metrics** +1. **Zero Runtime Overhead**: Business logic responses average ~31ms with no performance degradation +2. **Fast Documentation Generation**: 47ms to generate comprehensive docs for 166 endpoints +3. **Minimal Memory Footprint**: Only ~147KB metadata for 147 documented routes +4. **No User Experience Impact**: All response times consistently under acceptable thresholds +5. **Efficient Caching**: Cache hits provide sub-millisecond documentation serving + +### **Scalability Characteristics** +- **Linear Memory Growth**: ~1KB per documented endpoint scales predictably +- **Constant Runtime Performance**: No correlation between documentation size and response times +- **Efficient Cache Strategy**: 5-minute TTL balances freshness with performance +- **Rate Limiting Protection**: Prevents documentation endpoints from impacting core application + +### **Resource Utilization** +- **CPU Impact**: Negligible - documentation generation is I/O bound, not CPU intensive +- **Network Impact**: Cached responses reduce bandwidth usage for repeated documentation requests +- **Storage Impact**: Minimal - schemas stored in application memory, no persistent storage required + +## **🎯 Performance Conclusion** + +The comprehensive performance testing **validates the design principles** of the automatic schema generation system: + +### **Minimal Impact Metrics** +- **< 1% memory increase**: ~147KB total metadata footprint +- **0% runtime performance impact**: 31ms average API responses unchanged +- **< 50ms documentation generation**: One-time startup cost with intelligent caching +- **No negative user experience**: All metrics well within acceptable performance ranges + +### **Production Deployment Confidence** +The performance characteristics demonstrate that this feature can be safely deployed in production environments without concern for: +- Application response time degradation +- Memory resource exhaustion +- User experience impact +- System stability issues + +### **Optimization Recommendations** +For high-scale deployments (>500 endpoints), consider: +- Increasing cache TTL to reduce generation frequency +- Implementing lazy loading for documentation endpoints +- Using CDN for static Swagger UI assets +- Enabling compression for large specification responses + +### Known Limitations + +#### 1. Complex Return Logic +The AST analysis works best with simple return statements. Complex conditional logic may not be fully captured: + +```python +# Good - automatically detected +def simple_endpoint(): + return jsonify({"status": "ok"}) + +# Limited - only first return path detected +def complex_endpoint(): + if complex_condition(): + return jsonify({"type": "A", "data": get_a()}) + else: + return jsonify({"type": "B", "data": get_b()}) +``` + +#### 2. Dynamic Response Structures +Responses built dynamically at runtime are not analyzable: + +```python +# Not detectable by AST analysis +def dynamic_endpoint(): + response_data = build_dynamic_response() + return jsonify(response_data) +``` + +#### 3. External Function Calls +Return values from external functions cannot be analyzed: + +```python +# Limited detection - will show basic object schema +def external_call_endpoint(): + return jsonify(external_service.get_data()) +``` + +## Cross-References + +### Related Features +- **Swagger UI Integration**: Enhanced interactive documentation interface with search +- **OpenAPI 3.0 Generation**: Standards-compliant specification with security schemas +- **Authentication System**: Integration with Flask-Login and session management +- **Admin Settings**: Enable/disable control through admin interface +- **Caching System**: Performance optimization with intelligent cache invalidation +- **Rate Limiting**: DDOS protection for documentation endpoints +- **Content Security Policy**: Local asset serving for security compliance +- **File-based Organization**: Automatic endpoint grouping by source modules + +### Related Files +- `swagger_wrapper.py`: Core implementation with caching and security +- `functions_authentication.py`: Authentication integration +- `functions_settings.py`: Admin settings integration +- `route_frontend_admin_settings.py`: Admin interface for enable/disable +- `templates/admin_settings.html`: Admin UI with Swagger controls +- `templates/_sidebar_nav.html`: Navigation integration +- `static/swagger-ui/`: Local Swagger UI assets +- `route_backend_*.py`: Example implementations with security +- `functional_tests/test_automatic_swagger_schema_generation.py`: Validation tests + +### Configuration Dependencies +- Flask application configuration +- Static file serving for Swagger UI assets +- CSP headers allowing local resource loading + +## Maintenance + +### Adding New Type Support +To support additional Python types in schema generation, extend the `_ast_to_schema()` function: + +```python +elif isinstance(node, ast.Constant): + value = node.value + if isinstance(value, datetime): + return {"type": "string", "format": "date-time", "example": value.isoformat()} + # ... existing type handling +``` + +### Extending AST Analysis +For more complex return pattern detection, extend the `ReturnVisitor` class: + +```python +class ReturnVisitor(ast.NodeVisitor): + def visit_If(self, node): + # Handle conditional returns + # ... custom logic + self.generic_visit(node) +``` + +### Performance Optimization +- Consider caching AST parsing results for identical function signatures +- Implement lazy loading for schema generation on first access +- Add configuration option to disable auto-schema for specific routes + +This feature significantly reduces the manual effort required to maintain API documentation while ensuring consistency between code and documentation. \ No newline at end of file diff --git a/docs/features/v0.230.001/COMPREHENSIVE_TABLE_SUPPORT.md b/docs/features/v0.230.001/COMPREHENSIVE_TABLE_SUPPORT.md new file mode 100644 index 00000000..e7d34e89 --- /dev/null +++ b/docs/features/v0.230.001/COMPREHENSIVE_TABLE_SUPPORT.md @@ -0,0 +1,231 @@ +# COMPREHENSIVE_TABLE_SUPPORT + +## Overview and Purpose +SimpleChat now supports comprehensive table rendering from multiple input formats, ensuring that tables generated by AI agents or pasted by users are properly displayed as styled HTML tables regardless of their original format. + +**Version implemented:** 0.230.001 + +## Problem Statement +AI agents generate tables in various formats that weren't being properly rendered: +- Unicode box-drawing tables (┌─┬─┐ style) +- Markdown tables wrapped in code blocks +- Pipe-separated values (PSV) in code blocks +- Standard markdown tables (worked but needed pipeline integration) + +Users were seeing raw text instead of properly formatted tables, reducing readability and user experience. + +## Technical Specifications + +### Architecture Overview +The solution implements a preprocessing pipeline that detects and converts various table formats to standard markdown tables before the markdown parser processes them. + +**Processing Pipeline:** +1. Content cleaning and citation parsing +2. Unwrap markdown tables from code blocks +3. Convert Unicode box-drawing tables to markdown +4. Convert pipe-separated values to markdown tables +5. Parse with Marked.js (GFM tables enabled) +6. Sanitize with DOMPurify +7. Apply Bootstrap styling + +### File Structure +``` +application/single_app/static/js/chat/ +├── chat-messages.js # Main implementation +functional_tests/ +├── test_comprehensive_table_support.py # Validation script +├── test_unicode_table_conversion.html # Unicode test page +└── test_psv_table_conversion.html # PSV test page +``` + +### API Integration Points +No new API endpoints required. The table processing happens entirely on the client side during message rendering. + +## Implementation Details + +### 1. unwrapTablesFromCodeBlocks() +**Purpose:** Detects markdown tables wrapped in code blocks and unwraps them for proper parsing. + +**Pattern:** `/```[\w]*\n((?:[^\n]*\|[^\n]*\n)+)```/g` + +**Logic:** +- Finds code blocks containing pipe-separated content +- Validates that content has multiple lines with pipes +- Removes code block wrapper, preserving table content + +### 2. convertUnicodeTableToMarkdown() +**Purpose:** Converts Unicode box-drawing tables to standard markdown format. + +**Pattern:** `/┌[─┬┐]*┐[\s\S]*?└[─┴┘]*┘/g` + +**Logic:** +- Identifies complete Unicode table structures +- Extracts data rows (ignoring border/separator lines) +- Splits cells by `│` character +- Builds markdown table with header separator + +**Example transformation:** +``` +┌─────────┬─────────┐ +│ Name │ Status │ +├─────────┼─────────┤ +│ App1 │ Active │ +└─────────┴─────────┘ + +Becomes: +| Name | Status | +| --- | --- | +| App1 | Active | +``` + +### 3. convertPSVCodeBlockToMarkdown() +**Purpose:** Converts pipe-separated values in code blocks to markdown tables. + +**Pattern:** `/```[\w]*\n((?:[^|\n]+\|[^|\n]*(?:\|[^|\n]*)*\n)+)```/g` + +**Logic:** +- Detects code blocks with pipe-separated content +- Handles both header-only and header+data scenarios +- Limits display to 50 data rows (plus header) for performance +- Adds truncation notice for large datasets + +**Row Limit:** First 50 rows displayed, with "... and X more rows" notice for larger datasets. + +### Bootstrap Integration +All generated tables automatically receive Bootstrap classes: +- `table` - Base table styling +- `table-striped` - Alternating row colors +- `table-hover` - Row highlighting on hover +- `table-bordered` - Cell borders + +### DOMPurify Configuration +Table elements explicitly allowed through sanitization: +```javascript +ALLOWED_TAGS: ['table', 'thead', 'tbody', 'tr', 'th', 'td', ...] +``` + +## Usage Instructions + +### For Users +**No configuration required.** The feature works automatically: + +1. **Paste any table format** in a message +2. **AI-generated tables** are automatically converted +3. **Tables display** with professional Bootstrap styling + +### For Developers + +**Adding new table formats:** +1. Create detection regex pattern +2. Implement conversion function following existing patterns +3. Add to processing pipeline in `chat-messages.js` +4. Create test cases in functional tests + +**Pipeline integration:** +```javascript +const withUnwrappedTables = unwrapTablesFromCodeBlocks(withInlineCitations); +const withMarkdownTables = convertUnicodeTableToMarkdown(withUnwrappedTables); +const withPSVTables = convertPSVCodeBlockToMarkdown(withMarkdownTables); +const htmlContent = DOMPurify.sanitize(marked.parse(withPSVTables)); +``` + +## Testing and Validation + +### Functional Tests +- **test_comprehensive_table_support.py** - Integration validation +- **test_unicode_table_conversion.html** - Browser testing for Unicode tables +- **test_psv_table_conversion.html** - Browser testing for PSV format + +### Test Coverage +✅ Unicode box-drawing table conversion +✅ Standard markdown table preservation +✅ Pipe-separated values in code blocks +✅ Markdown tables wrapped in code blocks +✅ Mixed content with multiple table formats +✅ Bootstrap styling application +✅ DOMPurify sanitization compatibility +✅ Large dataset handling (50+ row tables) + +### Performance Considerations +- **Regex optimization:** Patterns designed for efficient matching +- **Row limiting:** PSV tables limited to 50 visible rows +- **Memory usage:** Processing happens during render, no storage impact +- **Load time:** Minimal impact on message rendering speed + +## Examples and Screenshots + +### Example 1: Unicode Table Input +``` +┌─────────────┬─────────┬────────────┐ +│ Application │ Version │ Status │ +├─────────────┼─────────┼────────────┤ +│ Simple Chat │ 0.229 │ Active │ +│ ESAM Agent │ 1.2.3 │ Testing │ +└─────────────┴─────────┴────────────┘ +``` + +**Renders as:** Professional HTML table with Bootstrap styling + +### Example 2: PSV Code Block Input +``` +``` +Application Name|Version|Environment|Status +Simple Chat|0.229.005|Production|Active +ESAM Agent|1.2.3|Development|Testing +``` +``` + +**Renders as:** Formatted table with headers and data rows + +### Example 3: Mixed Format Support +Messages can contain multiple table formats simultaneously, and all will be properly converted and displayed. + +## Known Limitations + +1. **Complex Unicode tables** with merged cells not supported +2. **Very wide tables** may require horizontal scrolling on mobile +3. **Nested tables** are not supported (by design) +4. **Custom table styling** beyond Bootstrap classes not preserved + +## Integration Notes + +### CSS Dependencies +Requires Bootstrap 5.x for optimal table styling. Tables will render without Bootstrap but with basic browser default styling. + +### JavaScript Dependencies +- Marked.js 15.0.7+ (GFM tables support) +- DOMPurify 3.1.3+ (HTML sanitization) + +### Browser Compatibility +Works in all modern browsers supporting ES6+ features. Tested in: +- Chrome 90+ +- Firefox 88+ +- Safari 14+ +- Edge 90+ + +## Future Enhancements + +### Potential Improvements +1. **Excel table paste support** - Direct paste from spreadsheets +2. **CSV import handling** - File upload table conversion +3. **Table editing capabilities** - Inline cell editing +4. **Export functionality** - Download tables as CSV/Excel +5. **Advanced styling options** - Theme customization +6. **Column sorting** - Interactive table features + +### Extensibility +The pipeline architecture allows easy addition of new table formats by: +1. Adding new conversion functions +2. Inserting into the processing pipeline +3. Creating corresponding test cases + +## Version History + +- **0.229.005** - Added comprehensive table support (Unicode, PSV, wrapped markdown) +- **0.229.004** - Initial Unicode table conversion +- **0.229.003** - Table preprocessing foundation + +## Related Documentation +- Feature implementation: `chat-messages.js` lines 150-300 +- Test validation: `functional_tests/test_comprehensive_table_support.py` +- HTML examples: `functional_tests/test_*_table_conversion.html` \ No newline at end of file diff --git a/docs/features/v0.230.001/FULL_WIDTH_CHAT_SUPPORT.md b/docs/features/v0.230.001/FULL_WIDTH_CHAT_SUPPORT.md new file mode 100644 index 00000000..f48838f5 --- /dev/null +++ b/docs/features/v0.230.001/FULL_WIDTH_CHAT_SUPPORT.md @@ -0,0 +1,355 @@ +# FULL WIDTH CHAT SUPPORT Feature + +## Overview and Purpose +This feature provides dynamic full-width chat interface support when the sidebar navigation is collapsed in the chats.html template. It automatically expands the chat interface to utilize the entire viewport width while maintaining optimal readability through intelligent content centering and responsive design principles. + +**Version implemented:** 0.230.001 + +**Dependencies:** +- Bootstrap 5.3.0 for responsive grid system and utilities +- CSS3 transitions for smooth layout animations +- Flexbox layout system for dynamic content alignment +- JavaScript sidebar state management integration + +## Technical Specifications + +### Architecture Overview +The full width chat support system consists of several integrated components: + +1. **Dynamic Layout Detection**: Automatically detects sidebar navigation state changes +2. **Responsive CSS Rules**: CSS selectors that respond to `body.sidebar-collapsed` class +3. **Content Centering System**: Intelligent max-width constraints for optimal readability +4. **Smooth Transitions**: Animated layout changes for enhanced user experience +5. **Multi-Navigation Support**: Works with both top navigation and sidebar navigation modes +6. **Accessibility Preservation**: Maintains all accessibility features during layout changes + +### Core CSS Implementation + +#### 1. Sidebar Collapse Detection +```css +/* Responsive layout when sidebar is collapsed */ +body.sidebar-collapsed #split-container { + margin-left: 0 !important; + max-width: 100% !important; +} + +/* Hide left pane and expand right pane when sidebar is collapsed */ +body.sidebar-collapsed #left-pane { + display: none !important; +} + +body.sidebar-collapsed #right-pane { + width: 100% !important; + max-width: 100% !important; +} +``` + +#### 2. Smooth Layout Transitions +```css +/* Ensure smooth transitions when sidebar state changes */ +#split-container, +#left-pane, +#right-pane { + transition: margin-left 0.3s ease-in-out, + max-width 0.3s ease-in-out, + width 0.3s ease-in-out !important; +} +``` + +#### 3. Content Centering and Readability +```css +/* Center and limit width of right pane content for optimal readability */ +#right-pane { + display: flex !important; + flex-direction: column !important; + align-items: center !important; +} + +#right-pane > div { + width: 100% !important; + max-width: 1000px !important; /* Optimal reading width */ +} +``` + +### Navigation Mode Support + +#### Top Navigation Layout +```css +{% if nav_layout != 'sidebar' and not (not nav_layout and app_settings.enable_left_nav_default) %} +/* Top navigation layout - hide left pane and expand right pane */ +#left-pane { + display: none !important; +} + +#right-pane { + width: 100% !important; + height: 100% !important; + display: flex !important; + flex-direction: column !important; + align-items: center !important; +} +{% endif %} +``` + +#### Sidebar Navigation Layout +```css +{% else %} +/* Sidebar navigation layout - similar behavior with full width support */ +#left-pane { + display: none !important; +} + +#right-pane { + width: 100% !important; + height: 100% !important; + display: flex !important; + flex-direction: column !important; + align-items: center !important; +} +{% endif %} +``` + +### File Structure +``` +application/single_app/ +├── templates/ +│ └── chats.html # Main chat interface with full width support +├── static/css/ +│ └── chats.css # Additional chat-specific styles +└── static/js/ + └── sidebar.js # Sidebar state management (referenced) +``` + +## Usage Instructions + +### Automatic Behavior +The full width support is completely automatic and requires no user intervention: + +1. **Sidebar Expanded State**: Normal split-pane layout with conversations list on left +2. **Sidebar Collapsed State**: Full width chat interface with centered content +3. **Navigation Toggle**: Smooth animated transition between states +4. **Content Optimization**: Automatic width constraints maintain readability + +### User Experience Flow +``` +┌─────────────────────────────────────────┐ +│ Normal State (Sidebar Expanded) │ +├──────────────┬──────────────────────────┤ +│ Conversations│ Chat Interface │ +│ List │ │ +│ (320px) │ (Remaining Width) │ +│ │ │ +└──────────────┴──────────────────────────┘ + + ↓ Sidebar Collapse + +┌─────────────────────────────────────────┐ +│ Full Width State (Sidebar Collapsed) │ +├─────────────────────────────────────────┤ +│ Centered Chat Interface │ +│ (Max 1000px for readability) │ +│ │ +│ │ +└─────────────────────────────────────────┘ +``` + +### Layout Behavior Matrix + +| Navigation Mode | Sidebar State | Left Pane | Right Pane | Content Width | +|----------------|---------------|-----------|------------|---------------| +| Top Nav | N/A | Hidden | Full Width | Max 1000px | +| Sidebar Nav | Expanded | 320px | Remaining | Max 1000px | +| Sidebar Nav | Collapsed | Hidden | Full Width | Max 1000px | + +## Integration Examples + +### HTML Template Structure +```html +
+ +
+
+
Conversations
+ +
+
+ +
+
+ + +
+
+ +
+
+ +
+
+ +
+
+
+``` + +### CSS Class Integration +```css +/* Flexible layout container */ +#split-container { + display: flex; + flex-direction: row; + flex-wrap: nowrap; + height: 100%; + width: 100%; + overflow: hidden; +} + +/* Responsive panes */ +#left-pane, #right-pane { + height: 100%; + overflow: hidden; +} +``` + +### JavaScript State Management Integration +```javascript +// Example of sidebar state change handling +function toggleSidebar() { + document.body.classList.toggle('sidebar-collapsed'); + // Layout automatically adjusts via CSS +} + +// The CSS transitions handle the smooth animation automatically +``` + +## Performance Considerations + +### CSS Performance +- **Efficient Selectors**: Uses ID selectors (#left-pane, #right-pane) for optimal performance +- **Hardware Acceleration**: CSS transforms utilize GPU acceleration for smooth transitions +- **Minimal Reflows**: Layout changes are optimized to minimize browser reflow operations +- **Transition Duration**: 0.3s provides smooth animation without feeling sluggish + +### Layout Optimization +- **Flexbox Efficiency**: Modern flexbox layout provides better performance than float-based layouts +- **Content Constraints**: Max-width limits prevent excessive line lengths that hurt readability +- **Overflow Management**: Proper overflow handling prevents scrollbar issues during transitions + +### Memory Impact +- **CSS Rules**: Minimal memory footprint with efficient CSS selectors +- **No JavaScript Dependencies**: Layout changes are handled entirely by CSS +- **DOM Stability**: No DOM manipulation required, only class changes + +## Responsive Design Features + +### Viewport Adaptation +- **Mobile Devices**: Automatically adapts to narrow screens +- **Tablet Devices**: Optimal layout for medium-width screens +- **Desktop Displays**: Full utilization of wide screens while maintaining readability +- **Ultra-wide Monitors**: Content centering prevents text from becoming too wide + +### Accessibility Considerations +- **Keyboard Navigation**: All keyboard shortcuts remain functional during layout changes +- **Screen Readers**: Layout changes don't affect screen reader navigation +- **Focus Management**: Focus states are preserved during sidebar transitions +- **Color Contrast**: All color contrast ratios maintained in both layouts + +### Browser Compatibility +- **Modern Browsers**: Full support in Chrome 60+, Firefox 55+, Safari 12+, Edge 79+ +- **Flexbox Support**: Utilizes widely supported flexbox properties +- **CSS Transitions**: Graceful degradation on older browsers (instant layout change) +- **Progressive Enhancement**: Basic functionality works without CSS transitions + +## Testing and Validation + +### Functional Testing +Located in: `functional_tests/` (integration with existing navigation tests) + +Test coverage includes: +- **Layout State Changes**: Sidebar expand/collapse behavior +- **Content Centering**: Proper content alignment in full width mode +- **Transition Smoothness**: Animation performance and timing +- **Navigation Integration**: Compatibility with different navigation modes +- **Responsive Breakpoints**: Behavior across different screen sizes + +### Manual Testing Checklist +1. **Sidebar Toggle**: Verify smooth transition when collapsing/expanding sidebar +2. **Content Readability**: Ensure text remains readable at all widths +3. **Chat Functionality**: Verify all chat features work in both layout modes +4. **Navigation Switching**: Test switching between top nav and sidebar nav +5. **Browser Compatibility**: Test across different browsers and devices + +### Performance Validation +- **Layout Shift**: No Cumulative Layout Shift (CLS) during transitions +- **Animation Performance**: 60fps transition animations on modern devices +- **Memory Usage**: No memory leaks during repeated sidebar toggles +- **CPU Impact**: Minimal CPU usage during layout transitions + +## Browser Support Matrix + +| Browser | Version | Full Width Support | Smooth Transitions | Notes | +|----------------|---------|-------------------|-------------------|--------| +| Chrome | 60+ | ✅ Full | ✅ Full | Optimal performance | +| Firefox | 55+ | ✅ Full | ✅ Full | Complete support | +| Safari | 12+ | ✅ Full | ✅ Full | iOS and macOS | +| Edge | 79+ | ✅ Full | ✅ Full | Chromium-based | +| Internet Explorer | 11 | ⚠️ Partial | ❌ None | Basic layout only | + +## Known Limitations + +### Current Constraints +1. **Content Width Limit**: Maximum content width fixed at 1000px for readability +2. **Transition Duration**: Fixed 0.3s transition cannot be customized per user +3. **Mobile Optimization**: Sidebar always hidden on mobile regardless of state +4. **Print Styles**: Print layout may not reflect full width state + +### Potential Improvements +1. **Configurable Max Width**: Admin setting for maximum content width +2. **Animation Preferences**: Respect user's prefers-reduced-motion setting +3. **Custom Transition Duration**: User-configurable animation speed +4. **Print Layout**: Optimize print styles for full width mode + +## Cross-References + +### Related Features +- **Sidebar Navigation**: Core navigation system that triggers full width mode +- **Responsive Design**: Overall responsive layout system integration +- **Chat Interface**: Main chat functionality that benefits from full width +- **User Preferences**: Navigation layout preferences (top nav vs sidebar) +- **Performance Optimization**: CSS and JavaScript performance features + +### Related Files +- `templates/chats.html`: Main implementation with embedded CSS +- `static/css/chats.css`: Additional chat-specific styles and layout rules +- `templates/base.html`: Base template with navigation preference handling +- `static/js/sidebar.js`: Sidebar state management (referenced) +- `static/css/navigation.css`: Core navigation system styles +- `static/css/sidebar.css`: Sidebar-specific styling and behavior + +### Configuration Dependencies +- User navigation layout preferences (top nav vs sidebar) +- Admin default navigation settings +- Responsive design breakpoints +- CSS transition and animation settings + +## Maintenance + +### Future Enhancement Opportunities +1. **Dynamic Content Width**: Adjust max-width based on content type +2. **Multi-Panel Support**: Support for additional collapsible panels +3. **Animation Customization**: User-configurable transition preferences +4. **Layout Persistence**: Remember full width state across sessions + +### Code Quality Improvements +1. **CSS Custom Properties**: Use CSS variables for easier theming +2. **Reduced Specificity**: Optimize CSS selector specificity +3. **Performance Monitoring**: Add performance metrics for layout changes +4. **Accessibility Testing**: Automated accessibility validation + +### Browser Support Evolution +- Monitor for new CSS features that could improve performance +- Plan for removal of Internet Explorer 11 support +- Evaluate CSS Grid as alternative to Flexbox for future versions +- Consider CSS Container Queries for advanced responsive behavior + +This feature significantly enhances the user experience by providing a more immersive chat interface when the sidebar is not needed, while maintaining optimal readability through intelligent content centering and smooth animated transitions. \ No newline at end of file diff --git a/docs/features/v0.230.001/PUBLIC_WORKSPACE_GOTO_BUTTON_ENHANCEMENT.md b/docs/features/v0.230.001/PUBLIC_WORKSPACE_GOTO_BUTTON_ENHANCEMENT.md new file mode 100644 index 00000000..65944777 --- /dev/null +++ b/docs/features/v0.230.001/PUBLIC_WORKSPACE_GOTO_BUTTON_ENHANCEMENT.md @@ -0,0 +1,194 @@ +# Public Workspace Management Enhancement: Go to Public Workspace Button + +**Version implemented:** 0.230.001 + +## Feature Description + +Added a "Go to Public Workspace" button to the Public Workspace Management page, providing users with quick navigation from workspace management back to the workspace itself, similar to the existing functionality in Group Workspaces. + +## User Experience Enhancement + +### Before Enhancement: +- Users had to manually navigate away from the management page to access their public workspace +- No direct way to go from managing a workspace to using it +- Inconsistent experience compared to Group Workspaces + +### After Enhancement: +- ✅ One-click navigation from management page to public workspace +- ✅ Automatically sets the workspace as active for the user +- ✅ Consistent experience with Group Workspace management +- ✅ Improved workflow efficiency for workspace administrators + +## Technical Implementation + +### Files Modified: +- `application/single_app/templates/manage_public_workspace.html` +- `application/single_app/route_frontend_public_workspaces.py` +- `application/single_app/config.py` (version update) + +### Changes Made: + +#### 1. Added Frontend Route for Setting Active Public Workspace +**File:** `route_frontend_public_workspaces.py` + +**New Route Added:** +```python +@app.route('/set_active_public_workspace', methods=['POST']) +@login_required +@user_required +@enabled_required("enable_public_workspaces") +def set_active_public_workspace(): + user_id = get_current_user_id() + workspace_id = request.form.get("workspace_id") + if not user_id or not workspace_id: + return "Missing user or workspace id", 400 + success = update_user_settings(user_id, {"activePublicWorkspaceOid": workspace_id}) + if not success: + return "Failed to update user settings", 500 + return redirect(url_for('public_workspaces')) +``` + +#### 2. Added Navigation Button to Management Template +**File:** `manage_public_workspace.html` + +**Button Added:** +```html +
+ + +
+``` + +## Feature Specifications + +### Button Behavior: +1. **Location**: Positioned prominently at the top of the management page, below the page title +2. **Styling**: Uses Bootstrap `btn-outline-primary` styling for consistency +3. **Action**: Sets the current workspace as the user's active public workspace +4. **Navigation**: Redirects user to the main public workspace interface (`/public_workspaces`) + +### Security & Permissions: +- ✅ Requires user authentication (`@login_required`) +- ✅ Requires user validation (`@user_required`) +- ✅ Requires public workspaces to be enabled (`@enabled_required("enable_public_workspaces")`) +- ✅ Uses existing workspace ID from URL (already validated by management page access) + +### Error Handling: +- Validates required parameters (user_id, workspace_id) +- Returns appropriate error messages for missing data +- Handles settings update failures gracefully + +## User Workflows + +### Enhanced Management Workflow: +1. **Navigate to Management**: User accesses `/public_workspaces/` +2. **Perform Management Tasks**: Edit workspace, manage members, handle requests +3. **Quick Navigation**: Click "Go to Public Workspace" button +4. **Seamless Transition**: Automatically redirected to workspace with it set as active + +### Integration Points: +- **From My Public Workspaces**: Users can manage then quickly switch to workspace +- **From Public Directory**: Administrators can manage then work in workspace +- **From Workspace**: Natural back-and-forth workflow between management and usage + +## Consistency Improvements + +### Alignment with Group Workspaces: +- **Similar Button Text**: "Go to Public Workspace" matches "Go to Group Workspace" +- **Same Position**: Button placed at top of management page +- **Identical Styling**: Uses same Bootstrap classes and form structure +- **Consistent Behavior**: Sets active workspace and redirects to main interface + +### UI/UX Benefits: +- **Predictable Interface**: Users familiar with group management will intuitively understand +- **Reduced Cognitive Load**: Consistent patterns across similar features +- **Improved Efficiency**: Faster task completion for workspace administrators + +## Technical Architecture + +### Route Pattern Consistency: +``` +Group Workspaces: POST /set_active_group → redirect to /group_workspaces +Public Workspaces: POST /set_active_public_workspace → redirect to /public_workspaces +``` + +### Settings Management: +``` +Group Workspaces: {"activeGroupOid": group_id} +Public Workspaces: {"activePublicWorkspaceOid": workspace_id} +``` + +### URL Structure: +``` +Group Management: /groups/ +Public Management: /public_workspaces/ +``` + +## Testing and Validation + +### Functional Testing: +- ✅ Button appears on public workspace management pages +- ✅ Clicking button sets workspace as active for user +- ✅ User is redirected to public workspace interface +- ✅ Workspace context is properly maintained +- ✅ Error handling works for edge cases + +### User Experience Testing: +- ✅ Button is visually prominent and clearly labeled +- ✅ Navigation feels smooth and intuitive +- ✅ Consistent with group workspace behavior +- ✅ No confusion about button purpose or destination + +### Permission Testing: +- ✅ Only accessible when public workspaces are enabled +- ✅ Requires proper authentication and user validation +- ✅ Works for all user roles (Owner, Admin, DocumentManager) + +## Implementation Notes + +### Design Decisions: +1. **Form-based Approach**: Used simple HTML form POST instead of JavaScript for consistency with group workspaces +2. **Server-side Redirect**: Handles navigation server-side for reliability +3. **Hidden Input**: Passes workspace_id via hidden form field for security +4. **Existing Patterns**: Leveraged established user settings update mechanisms + +### Performance Considerations: +- Minimal overhead: single database update for user settings +- Fast redirect: direct server-side navigation +- No additional JavaScript dependencies + +### Accessibility: +- Standard HTML form controls for screen reader compatibility +- Clear button text for users with assistive technologies +- Consistent keyboard navigation patterns + +## Future Enhancements + +### Potential Improvements: +- **Breadcrumb Navigation**: Add breadcrumb trail showing management → workspace path +- **Back Button**: Consider adding reverse navigation from workspace to management +- **Keyboard Shortcuts**: Implement hotkeys for common navigation patterns +- **Visual Indicators**: Show which workspace is currently active in management view + +### Related Features: +- Could be extended to other workspace types if added in the future +- Pattern could be applied to document management → document viewing workflows +- Template could be enhanced with workspace status indicators + +## Migration and Compatibility + +### Backward Compatibility: +- ✅ No breaking changes to existing functionality +- ✅ Users without this feature see no difference in behavior +- ✅ All existing APIs and routes remain unchanged + +### Deployment Considerations: +- Zero downtime deployment compatible +- No database schema changes required +- No configuration changes needed + +## Related Documentation + +- **Base Feature**: `../features/PUBLIC_WORKSPACES.md` +- **Management Interface**: Referenced in workspace management workflows +- **Group Workspaces**: Pattern inspired by existing group workspace management \ No newline at end of file