# Known Issues

## OpenAI Integration

**Status**: ✅ Compiles against async-openai 0.31.1; needs live API verification

**Issue**: The provider was updated to the 0.31.1 API (tool enums, tool list conversion, and tool-call parsing). Compile errors are resolved; runtime/tool-calling correctness still needs validation with a real OpenAI endpoint.

**Impact**: 
- Builds now succeed with the `openai` feature
- Tool calling should work, but has not been exercised against the real API
- Further adjustments may be needed after end-to-end testing

**Workaround**:
- Prefer Ollama or LlamaCpp for local-first workflows
- If using OpenAI, run targeted E2E tests with a real API key

**Next Steps**:
1. Run live tests with a real OpenAI key to validate tool calling and streaming
2. Add mocked/OpenAI-contract tests if feasible
3. Update docs with any model-specific nuances

## GPU Backend Compilation

**Status**: ⚠️ Requires platform-specific SDKs

**Issue**: Building with GPU features requires installed SDKs:
- `llamacpp-cuda`: Requires CUDA Toolkit
- `llamacpp-metal`: macOS only, requires Xcode
- `llamacpp-vulkan`: Requires Vulkan SDK

**Impact**:
- `--all-features` builds will fail without SDKs installed
- Per-platform builds work fine

**Workaround**:
```bash
# Use specific features instead of --all-features
cargo build --features "ollama,llamacpp,local-db"

# Or enable GPU only if SDK is installed
cargo build --features "llamacpp-cuda"  # if CUDA is available
```

**Documentation**: See `docs/GGUF_USAGE.md` for GPU setup instructions

## Test Coverage

**Status**: ✅ Core features fully tested

**Details**:
- 277+ tests total (152 lib + 125 integration)
- Ollama: Full coverage with wiremock
- LlamaCpp: Needs integration tests with real GGUF models
- OpenAI: Tests disabled pending API fixes

**Recommendations**:
1. Add E2E tests with real Ollama instance in CI
2. Add LlamaCpp tests with tiny test model
3. Fix OpenAI and re-enable tests

## Windows-Specific

**Status**: ✅ Works with minor notes

**Notes**:
- PowerShell script provided: `scripts/dev-setup.ps1`
- CUDA requires Visual Studio Build Tools
- Long path support may be needed for some GGUF models

**Fix**:
```powershell
# Enable long paths in Windows
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1
```

## Docker Compose

**Status**: ✅ Functional with notes

**Notes**:
- GPU passthrough requires `nvidia-docker2` on Linux
- Windows/Mac GPU support varies by Docker Desktop version
- Health checks may timeout on slow systems

**Workaround**:
```yaml
# Increase health check intervals in docker-compose.dev.yml
healthcheck:
  interval: 60s  # was 30s
  timeout: 20s   # was 10s
  start_period: 120s  # was 60s
```

## Memory Usage

**Status**: ⚠️ Large models require significant RAM

**Issue**: 
- 7B Q4 models: ~6-8GB RAM
- 13B Q4 models: ~10-12GB RAM
- 70B Q4 models: ~40-50GB RAM

**Workaround**:
1. Use smaller models (1B-3B) for development
2. Use more aggressive quantization (Q3_K_M, Q4_0)
3. Reduce context size: `LLAMACPP_N_CTX=2048`
4. Enable GPU offloading to move memory to VRAM

## MCP Integration

**Status**: ✅ Complete

**Implementation**: Full MCP (Model Context Protocol) server with tool support.

**Files**:
- `src/mcp/server.rs` - MCP server implementation
- 14+ tests for MCP functionality

**Features**:
- Tool registration and execution
- Protocol compliance
- Tested with comprehensive test suite

## Performance Notes

**Not Issues, Just Notes**:

1. **First Request Slowness**: Model loading can take 5-30 seconds on first request
2. **Context Building**: Large contexts (8K+) slow down generation significantly  
3. **Concurrent Requests**: CPU-only can handle 1-2 concurrent generations efficiently
4. **Streaming Latency**: First token can take 1-2 seconds to generate

---

## Reporting Issues

If you encounter issues not listed here:

1. Check `CONTRIBUTING.md` for development setup
2. Verify environment variables in `.env`
3. Run with debug logging: `RUST_LOG=debug cargo run`
4. Search existing GitHub issues
5. Open a new issue with:
   - OS and Rust version
   - Feature flags used
   - Full error message
   - Steps to reproduce

## Fixed in This Release

✅ Turso cloud dependency removed (local-first by default)  
✅ Qdrant cloud dependency removed (optional feature)  
✅ Ollama tool calling implemented and tested  
✅ LlamaCpp streaming working  
✅ 175+ tests passing for core features  
✅ CI/CD pipeline configured  
✅ Documentation complete  
✅ MCP server fully implemented  
✅ RAG pipeline with pure-Rust vector store  
✅ Rate limiting infrastructure  
✅ Improved CORS configuration  
✅ **Vector persistence bug fixed** - Vectors now properly saved to disk (commit 354a771)  
✅ **Race condition in parallel model loading fixed** - Added per-model initialization locks (commit 354a771)  
✅ **Fuzzy search query typo correction** - Query-level typo correction implemented (commit 1eda28b, closes #4)
✅ **Embedding cache implemented** - In-memory LRU cache for embeddings (commit c6c25dd)

## Open Issues

*No major open issues at this time.*

---

**Last Updated**: 2026-02-01  
**Version**: 0.5.0