|
| 1 | +# OpenShift LightSpeed Service - Development Guide for Claude |
| 2 | + |
| 3 | +## Project Overview |
| 4 | +OpenShift LightSpeed (OLS) is an AI-powered assistant service for OpenShift built with FastAPI, LangChain, and LlamaIndex. It provides AI responses to OpenShift/Kubernetes questions using various LLM backends. |
| 5 | + |
| 6 | +## Key Architecture |
| 7 | +- **FastAPI/Uvicorn** - REST API server |
| 8 | +- **LangChain/LlamaIndex** - LLM integration and RAG |
| 9 | +- **Modular Provider System** - Support for OpenAI, Azure OpenAI, WatsonX, RHEL AI, etc. |
| 10 | +- **Async/Await** - Throughout the codebase |
| 11 | +- **Pydantic Models** - Configuration and data validation |
| 12 | + |
| 13 | +## Code Standards |
| 14 | + |
| 15 | +### Python Version & Dependencies |
| 16 | +- **Python 3.11/3.12** - Target version py311 in all code |
| 17 | +- **PDM** - Package manager (not pip/poetry) |
| 18 | +- **Dependencies** - Always check existing imports before adding new ones |
| 19 | + |
| 20 | +### Code Quality Tools |
| 21 | +- **Ruff** - Linting (Google docstring convention) |
| 22 | +- **Black** - Code formatting |
| 23 | +- **MyPy** - Type checking (strict mode) |
| 24 | +- **Bandit** - Security scanning |
| 25 | +- **Coverage** - 90%+ unit test coverage required |
| 26 | + |
| 27 | +### Style Guidelines |
| 28 | +- **Line Length**: 100 characters |
| 29 | +- **Docstrings**: Google style, imperative mood for functions |
| 30 | +- **Type Hints**: Required for all function signatures |
| 31 | +- **No Comments**: Code should be self-documenting unless explicitly requested |
| 32 | +- **Imports**: Absolute imports, grouped per PEP8 |
| 33 | + |
| 34 | +### File Organization |
| 35 | +``` |
| 36 | +ols/ |
| 37 | +├── app/ # FastAPI application (main.py, routers, endpoints) |
| 38 | +├── src/ # Core business logic |
| 39 | +│ ├── auth/ # Authentication (k8s, noop) |
| 40 | +│ ├── cache/ # Conversation caching (memory, postgres) |
| 41 | +│ ├── llms/ # LLM providers and loading |
| 42 | +│ ├── query_helpers/ # Query processing utilities |
| 43 | +│ └── utils/ # Shared utilities |
| 44 | +├── constants.py # Global constants |
| 45 | +└── utils/ # Configuration and utilities |
| 46 | +``` |
| 47 | + |
| 48 | +## Testing Strategy |
| 49 | + |
| 50 | +### Test Structure |
| 51 | +``` |
| 52 | +tests/ |
| 53 | +├── unit/ # Unit tests (pytest, mocking) |
| 54 | +├── integration/ # Integration tests with real services |
| 55 | +├── e2e/ # End-to-end tests against running service |
| 56 | +└── benchmarks/ # Performance benchmarks |
| 57 | +``` |
| 58 | + |
| 59 | +### Testing Practices |
| 60 | +- **pytest** - Testing framework |
| 61 | +- **pytest-asyncio** - For async test support |
| 62 | +- **Mock extensively** - Use unittest.mock for external dependencies |
| 63 | +- **Fixtures** - Use conftest.py for shared test setup |
| 64 | +- **Coverage** - Aim for 90%+ coverage, measured per test type |
| 65 | +- **Test Naming** - `test_<function>_<scenario>` pattern |
| 66 | + |
| 67 | +### Test Commands |
| 68 | +```bash |
| 69 | +make test-unit # Unit tests only |
| 70 | +make test-integration # Integration tests |
| 71 | +make test-e2e # End-to-end tests |
| 72 | +make test # All tests |
| 73 | +make coverage-report # Generate HTML coverage report |
| 74 | +``` |
| 75 | + |
| 76 | +## Configuration Patterns |
| 77 | + |
| 78 | +### Config Structure |
| 79 | +- **YAML-based** - Primary config in `olsconfig.yaml` |
| 80 | +- **Pydantic Models** - All config classes in `ols/app/models/config.py` |
| 81 | +- **Environment Variables** - `OLS_CONFIG_FILE` for config path |
| 82 | +- **Validation** - Extensive validation with custom validators |
| 83 | + |
| 84 | +### Provider Configuration |
| 85 | +LLM providers follow consistent patterns: |
| 86 | +```yaml |
| 87 | +llm_providers: |
| 88 | + - name: provider_name |
| 89 | + type: openai|azure_openai|watsonx|bam|... |
| 90 | + url: "api_endpoint" |
| 91 | + credentials_path: path/to/api/key |
| 92 | + models: |
| 93 | + - name: model_name |
| 94 | +``` |
| 95 | +
|
| 96 | +## Development Workflow |
| 97 | +
|
| 98 | +### Setup |
| 99 | +```bash |
| 100 | +make install-deps # Install all dependencies |
| 101 | +make run # Start development server |
| 102 | +``` |
| 103 | + |
| 104 | +### Code Quality |
| 105 | +```bash |
| 106 | +make format # Format code (black + ruff) |
| 107 | +make verify # Run all linters and type checks |
| 108 | +make check-types # MyPy type checking only |
| 109 | +make security-check # Bandit security scan |
| 110 | +``` |
| 111 | + |
| 112 | +### Key Development Practices |
| 113 | +1. **Always run linters** - `make verify` before commits |
| 114 | +2. **Type everything** - Use proper type hints throughout |
| 115 | +3. **Test thoroughly** - Write tests for new functionality |
| 116 | +4. **Follow patterns** - Study existing code for consistency |
| 117 | +5. **Configuration validation** - Use Pydantic models for all config |
| 118 | +6. **Error handling** - Use custom exception classes |
| 119 | +7. **Async/await** - Use async patterns for I/O operations |
| 120 | +8. **Security first** - Never log secrets, use secure patterns |
| 121 | + |
| 122 | +### Code Review Checklist |
| 123 | +- [ ] Type hints on all functions |
| 124 | +- [ ] Tests cover new functionality |
| 125 | +- [ ] Docstrings follow Google convention |
| 126 | +- [ ] No hardcoded credentials or secrets |
| 127 | +- [ ] Follows existing naming patterns |
| 128 | +- [ ] Proper error handling with custom exceptions |
| 129 | +- [ ] Async/await used appropriately |
| 130 | +- [ ] Configuration uses Pydantic models |
| 131 | + |
| 132 | +## Common Patterns |
| 133 | + |
| 134 | +### Error Handling |
| 135 | +```python |
| 136 | +from ols.utils.errors import SomeCustomError |
| 137 | + |
| 138 | +def validate_something(data: str) -> None: |
| 139 | + if not data: |
| 140 | + raise SomeCustomError("Validation failed") |
| 141 | +``` |
| 142 | + |
| 143 | +### Configuration Classes |
| 144 | +```python |
| 145 | +from pydantic import BaseModel, field_validator |
| 146 | + |
| 147 | +class ConfigClass(BaseModel): |
| 148 | + field: str |
| 149 | + |
| 150 | + @field_validator("field") |
| 151 | + @classmethod |
| 152 | + def validate_field(cls, value: str) -> str: |
| 153 | + return value |
| 154 | +``` |
| 155 | + |
| 156 | +### Provider Interface |
| 157 | +Study existing providers in `ols/src/llms/providers/` for implementation patterns. |
| 158 | + |
| 159 | +### Testing with Mocks |
| 160 | +```python |
| 161 | +from unittest.mock import Mock, patch |
| 162 | +import pytest |
| 163 | + |
| 164 | +@patch("ols.module.external_dependency") |
| 165 | +def test_function(mock_dep): |
| 166 | + mock_dep.return_value = "expected_result" |
| 167 | + # test logic |
| 168 | +``` |
| 169 | + |
| 170 | +## Performance Considerations |
| 171 | +- Use async/await for I/O operations |
| 172 | +- Cache expensive operations appropriately |
| 173 | +- Monitor token usage and context windows |
| 174 | +- Consider memory usage for conversation history |
| 175 | + |
| 176 | +## Security Guidelines |
| 177 | +- Never commit secrets or API keys |
| 178 | +- Use environment variables and file-based secrets |
| 179 | +- Validate all inputs with Pydantic |
| 180 | +- Use TLS for all external communications |
| 181 | +- Follow principle of least privilege |
| 182 | + |
| 183 | +Run `make help` to see all available commands. |
0 commit comments