escobar 0.1.90__tar.gz → 0.1.91__tar.gz

escobar-0.1.91/.vscode/launch.json

@@ -0,0 +1,54 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug JupyterLab (Grisha: Python)",
+      "type": "debugpy",
+      "request": "launch",
+      "python": "${workspaceFolder}/.venv/bin/python3",
+      "module": "jupyter",
+      "args": [
+        "lab",
+        "--no-browser",
+        "--NotebookApp.token=''",
+        "--NotebookApp.password=''"
+      ],
+      "cwd": "${workspaceFolder}",
+      "justMyCode": false,
+      "env": {
+        "PYTHONPATH": "${workspaceFolder}"
+      }
+    },
+    {
+      "name": "Debug JupyterLab Extension",
+      "type": "chrome",
+      "request": "launch",
+      "url": "http://localhost:8888/lab",
+      "webRoot": "${workspaceFolder}",
+      "sourceMapPathOverrides": {
+        "webpack://escobar/*": "${workspaceFolder}/*",
+        "webpack:///./~/*": "${workspaceFolder}/node_modules/*",
+        "webpack:///./*": "${workspaceFolder}/*",
+        "webpack:///src/*": "${workspaceFolder}/src/*",
+        "webpack:///./src/*": "${workspaceFolder}/src/*"
+      },
+      "sourceMaps": true,
+      "smartStep": true
+    },
+    {
+      "name": "Debug JupyterLab (Roma: Python)",
+      "type": "debugpy",
+      "request": "launch",
+      "python": "/Users/roman/.pyenv/shims/python3",
+      "module": "jupyter",
+      "args": [
+        "lab",
+        "--no-browser",
+        "--NotebookApp.token=''",
+        "--NotebookApp.password=''"
+      ],
+      "cwd": "/Users/roman/DEVEL/HP",
+      "justMyCode": false
+    }
+  ]
+}

escobar-0.1.91/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: escobar
+Version: 0.1.91
+Dynamic: Keywords
+Summary: AI CHAT EXTENSION
+Project-URL: Homepage, https://github.com/github_username/escobar
+Project-URL: Bug Tracker, https://github.com/github_username/escobar/issues
+Project-URL: Repository, https://github.com/github_username/escobar.git
+Author-email: Escobar <me@test.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2025, Escobar
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License-File: LICENSE
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Jupyter :: JupyterLab
+Classifier: Framework :: Jupyter :: JupyterLab :: 4
+Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
+Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: aiohttp
+Requires-Dist: jupyter-server>=2.0.0
+Requires-Dist: websockets>=11.0

escobar-0.1.91/es2/escobar-0.1.90/.clinerules

@@ -0,0 +1,188 @@
+# Escobar Project Intelligence
+
+## Project Overview
+
+Escobar is a JupyterLab extension providing AI chat functionality with WebSocket proxy capabilities. It's part of the Voitta AI ecosystem and communicates with the Bonnie backend server.
+
+## Critical Implementation Paths
+
+### Protocol Synchronization
+
+- TypeScript protocol definitions in `src/types/protocol.ts` MUST stay synchronized with Python protocol in `../bonnie/lib/protocol_messages.py`
+- When adding new message types, update both TypeScript interfaces and Python classes
+- Use `call_id` for request/response correlation
+- Context identification uses `username` + `chatID` pattern
+
+### JupyterLab Extension Patterns
+
+- Use Lumino widgets for UI components (not React)
+- Follow JupyterLab plugin architecture with optional service dependencies
+- Register commands in command palette and launcher
+- Use `I[Name]` naming convention for TypeScript interfaces
+
+### Build and Development Workflow
+
+- Development installation requires specific sequence:
+  ```bash
+  jupyter labextension develop --overwrite . &&
+  pip uninstall escobar -y &&
+  pip install -e . &&
+  jupyter server extension enable escobar
+  ```
+- Use `yarn watch` for development with auto-rebuild
+- Frontend and backend versions must stay synchronized
+
+## User Preferences and Workflow
+
+### Code Style Preferences
+
+- TypeScript with strict type checking
+- Single quotes preferred over double quotes
+- Arrow functions preferred over function declarations
+- Interface naming: `I[Name]` prefix (e.g., `IProtocolMessage`)
+- No semicolons (handled by Prettier)
+
+### Development Patterns
+
+- Always use virtual environment (.venv) for Python
+- Use typed Python with type hints
+- Import order: standard library, third-party, local project
+- Never store API keys or secrets in code or version control
+
+### Error Handling Patterns
+
+- Use type-safe error responses in protocol
+- Graceful degradation for optional JupyterLab services
+- WebSocket reconnection logic for connection failures
+- Proper error propagation from backend to frontend
+
+## Project-Specific Patterns
+
+### WebSocket Communication
+
+- All messages include `message_type`, `call_id`, and optional `msg_call_id`
+- Request messages include `username` and `chatID` for context
+- Use streaming responses for AI content with `is_complete` flag
+- Proxy WebSocket connections with header forwarding
+
+### JupyterLab Integration
+
+- Inject services as optional dependencies in widget constructor
+- Use notebook tracker for context awareness
+- Integrate with debugger service for debugging workflows
+- Handle settings through ISettingRegistry
+
+### File Structure Conventions
+
+- Protocol types in `src/types/protocol.ts`
+- Integration modules in `src/integrations/`
+- Utility functions in `src/utils/`
+- Icons and assets in `src/icons/`
+- Python handlers in `escobar/` directory
+
+## Known Challenges and Solutions
+
+### Protocol Synchronization Challenge
+
+- **Problem**: Manual sync between TypeScript and Python protocol definitions
+- **Current Solution**: Careful manual maintenance
+- **Future Solution**: Consider code generation from single source
+
+### Build Complexity
+
+- **Problem**: Coordinating TypeScript + Python build pipeline
+- **Solution**: Use Hatch with nodejs version integration
+- **Key Files**: `pyproject.toml`, `package.json`, `webpack.config.js`
+
+### JupyterLab Compatibility
+
+- **Problem**: Ensuring compatibility across JupyterLab versions
+- **Solution**: Use JupyterLab 4.x APIs and follow extension patterns
+- **Testing**: Manual integration testing with JupyterLab
+
+## Evolution of Project Decisions
+
+### Architecture Evolution
+
+- Started with simple chat widget
+- Added WebSocket proxy functionality
+- Integrated with multiple JupyterLab services
+- Developed comprehensive protocol system
+
+### Technology Choices
+
+- **TypeScript**: Chosen for type safety and JupyterLab compatibility
+- **Lumino Widgets**: Required for JupyterLab integration
+- **WebSocket**: Real-time bidirectional communication
+- **Hatch**: Modern Python packaging with frontend integration
+
+### Protocol Design Evolution
+
+- Initially simple request/response
+- Added streaming support for AI responses
+- Implemented context management with username/chatID
+- Added tool call support for AI interactions
+
+## Tool Usage Patterns
+
+### Development Tools
+
+- **Yarn**: Package management and build scripts
+- **TypeScript Compiler**: Strict type checking
+- **Webpack**: Extension bundling
+- **ESLint + Prettier**: Code quality and formatting
+- **Hatch**: Python packaging and version management
+
+### JupyterLab Development
+
+- Use `jupyter labextension develop` for development mode
+- Enable server extension with `jupyter server extension enable`
+- Use JupyterLab's built-in developer tools for debugging
+- Test with actual JupyterLab instance, not isolated environment
+
+### Integration Testing
+
+- Test WebSocket communication with actual backend
+- Verify all JupyterLab service integrations
+- Test extension loading and unloading
+- Validate protocol message handling
+
+## Memory Bank Maintenance
+
+### Documentation Strategy
+
+- Keep memory bank files updated with project evolution
+- Document new patterns and decisions in .clinerules
+- Update progress.md with implementation status
+- Maintain activeContext.md with current work focus
+
+### Key Documentation Files
+
+- `memory-bank/projectbrief.md` - Project foundation and requirements
+- `memory-bank/systemPatterns.md` - Architecture and design patterns
+- `memory-bank/techContext.md` - Technology stack and constraints
+- `memory-bank/progress.md` - Implementation status and milestones
+- `memory-bank/activeContext.md` - Current work and decisions
+
+## Critical Success Factors
+
+### Technical Success
+
+- Maintain protocol synchronization between frontend and backend
+- Ensure stable WebSocket communication
+- Keep JupyterLab integrations working across versions
+- Maintain type safety throughout the codebase
+
+### Development Success
+
+- Clear development workflow and documentation
+- Comprehensive memory bank for context preservation
+- Consistent code patterns and conventions
+- Effective testing and validation processes
+
+### User Success
+
+- Seamless integration with JupyterLab workflow
+- Reliable AI chat functionality
+- Persistent chat history and management
+- Intuitive user interface and experience

escobar-0.1.91/es2/escobar-0.1.90/.env.example

@@ -0,0 +1,4 @@
+# PyPI token for publishing packages
+# Get your token from https://pypi.org/manage/account/token/
+# Replace this with your actual token
+PYPI_TOKEN=pypi-AgEIcHlwaS5vcmcCJGV4YW1wbGUtdG9rZW4tMTIzNDU2Nzg5MDEK

escobar-0.1.91/es2/escobar-0.1.90/.gitignore

@@ -0,0 +1,133 @@
+*.bundle.*
+lib/
+node_modules/
+*.log
+.eslintcache
+.stylelintcache
+*.egg-info/
+.ipynb_checkpoints
+*.ipynb
+
+*.tsbuildinfo
+escobar/labextension
+# Version file is handled by hatchling
+escobar/_version.py
+
+# Created by https://www.gitignore.io/api/python
+# Edit at https://www.gitignore.io/?templates=python
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage/
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# End of https://www.gitignore.io/api/python
+
+# OSX files
+.DS_Store
+
+# Yarn cache
+.yarn/
+
+# Environment variables
+.env
+.venv
+
+sandbox
+
+*~
+\#*
+.#*

escobar-0.1.91/es2/escobar-0.1.90/.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+**/node_modules
+**/lib
+**/package.json
+!/package.json
+escobar

escobar-0.1.91/es2/escobar-0.1.90/.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "editor.formatOnSave": true,
+  "python.linting.enabled": true,
+  "python.linting.pylintEnabled": true,
+  "python.debugging.debugJustMyCode": false,
+  "js-debug.sourceMaps": true,
+  "js-debug.sourceMapRenames": true,
+  "js-debug.usePreviewDebugger": true,
+  "jupyter.debugJustMyCode": false,
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python3",
+  "python.pythonPath": "${workspaceFolder}/.venv/bin/python3"
+}

escobar-0.1.91/es2/escobar-0.1.90/.vscode/tasks.json

@@ -0,0 +1,57 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "typescript",
+      "tsconfig": "tsconfig.json",
+      "problemMatcher": [
+        "$tsc"
+      ],
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "label": "tsc: build - tsconfig.json"
+    },
+    {
+      "type": "npm",
+      "script": "watch",
+      "problemMatcher": "$tsc-watch",
+      "isBackground": true,
+      "presentation": {
+        "reveal": "always",
+        "panel": "dedicated"
+      },
+      "group": {
+        "kind": "build",
+        "isDefault": false
+      },
+      "label": "npm: watch"
+    },
+    {
+      "type": "shell",
+      "command": "${workspaceFolder}/.venv/bin/jupyter lab --watch",
+      "problemMatcher": [],
+      "isBackground": true,
+      "presentation": {
+        "reveal": "always",
+        "panel": "dedicated"
+      },
+      "label": "jupyter: lab watch",
+      "options": {
+        "env": {
+          "PYTHONPATH": "${workspaceFolder}"
+        }
+      }
+    },
+    {
+      "label": "Start Development Environment",
+      "dependsOrder": "parallel",
+      "dependsOn": [
+        "npm: watch",
+        "jupyter: lab watch"
+      ],
+      "problemMatcher": []
+    }
+  ]
+}

escobar-0.1.91/es2/escobar-0.1.90/.yarnrc.yml

@@ -0,0 +1,3 @@
+enableImmutableInstalls: false
+
+nodeLinker: node-modules

escobar-0.1.91/es2/escobar-0.1.90/AUTHENTICATION_BEHAVIOR.md

@@ -0,0 +1,142 @@
+# Authentication Behavior in Escobar Extension
+
+This document explains how authentication and username handling works in the Escobar extension.
+
+## 🎯 **Normal Operation (Default)**
+
+By default, the Escobar extension does **NOT** implement any authentication system. It simply uses usernames for chat identification.
+
+### **Non-Hub Environment (Standalone Jupyter)**
+- ✅ **Username source**: Connection settings page (user can edit)
+- ✅ **No authentication prompts**: Extension works without any login
+- ✅ **User control**: Username can be changed in settings anytime
+
+### **JupyterHub Environment**
+- ✅ **Username source**: Extracted from URL automatically
+- ✅ **No authentication prompts**: Uses existing JupyterHub authentication
+- ✅ **Read-only username**: Settings page disables username editing
+- ✅ **Automatic detection**: Extension detects JupyterHub environment
+
+## 🔧 **Username Detection Logic**
+
+### **JupyterHub Detection**
+The extension automatically detects JupyterHub by checking:
+1. URL pattern: `/user/{username}/lab/...`
+2. JupyterHub config data in page
+3. Document baseURI patterns
+4. JupyterHub-related cookies
+
+### **Username Extraction**
+- **JupyterHub**: Extracted from URL path `/user/{username}/`
+- **Standalone**: User enters in connection settings
+
+### **Settings Page Behavior**
+- **JupyterHub**: Username field is disabled and read-only
+- **Standalone**: Username field is editable
+
+## 🧪 **Demo Mode (Optional)**
+
+For demonstration purposes, the extension can optionally enable a demo authentication system.
+
+### **Enabling Demo Mode**
+Set the environment variable:
+```bash
+export ESCOBAR_DEMO_MODE=true
+```
+
+Or in Docker:
+```dockerfile
+ENV ESCOBAR_DEMO_MODE=true
+```
+
+### **Demo Mode Behavior**
+When demo mode is enabled:
+- ❗ **Root URL hijacking**: `/` redirects to demo user selection
+- ❗ **Demo user selection**: Shows page with predefined demo users
+- ❗ **Demo authentication**: Users must select a demo user to proceed
+
+### **Demo Users Configuration**
+Demo users are configured via environment variable:
+```bash
+export DEMO_USERS="alice,bob,charlie"
+```
+
+If not set, defaults to a single demo user: `demo`
+
+## 🚫 **What Was Fixed**
+
+### **Problem (Before Fix)**
+- Demo authentication was **always enabled**
+- Root URL was **always hijacked**
+- Users were **forced through demo user selection**
+- Extension appeared to require authentication in all environments
+
+### **Solution (After Fix)**
+- Demo authentication is **only enabled when explicitly requested**
+- Normal operation has **no authentication prompts**
+- Extension works seamlessly in both JupyterHub and standalone environments
+- Username handling is **passive and environment-appropriate**
+
+## 📋 **Installation Behavior**
+
+### **Default Installation**
+```bash
+pip install escobar
+jupyter server extension enable escobar
+```
+**Result**: Extension works normally without any authentication prompts
+
+### **Demo Installation**
+```bash
+pip install escobar
+export ESCOBAR_DEMO_MODE=true
+export DEMO_USERS="alice,bob,charlie"
+jupyter server extension enable escobar
+```
+**Result**: Extension shows demo user selection page
+
+## 🔍 **Troubleshooting**
+
+### **If You See Authentication Prompts**
+1. **Check environment variables**:
+   ```bash
+   echo $ESCOBAR_DEMO_MODE
+   ```
+   
+2. **Disable demo mode**:
+   ```bash
+   unset ESCOBAR_DEMO_MODE
+   # or
+   export ESCOBAR_DEMO_MODE=false
+   ```
+
+3. **Restart Jupyter**:
+   ```bash
+   jupyter lab --stop
+   jupyter lab
+   ```
+
+### **If Username is Not Working**
+1. **Check environment detection**:
+   - Open browser console in JupyterLab
+   - Look for "Running in JupyterHub Mode" or "Running in Plugin Mode"
+
+2. **Manually set username**:
+   - Click the connection settings button in the chat widget
+   - Enter your desired username
+
+3. **Check URL pattern**:
+   - JupyterHub URLs should contain `/user/{username}/`
+   - If not detected, username will be editable in settings
+
+## ✅ **Expected Behavior Summary**
+
+| Environment | Username Source | Authentication | Settings Editable |
+|-------------|----------------|----------------|-------------------|
+| **Standalone Jupyter** | Settings page | None | ✅ Yes |
+| **JupyterHub** | URL extraction | JupyterHub's | ❌ No (read-only) |
+| **Demo Mode** | Demo selection | Demo system | Varies |
+
+## 🎉 **Result**
+
+The extension now works seamlessly without unwanted authentication prompts while maintaining proper username handling for both JupyterHub and standalone environments.