jpmschweitzer/tatlock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Clean up documentation to reflect current implementation

Browse Source 
Remove confusing references to unimplemented features and clarify
what's currently working vs prepared for future integration.

README.md Changes:
- Update title to reflect mock API (not "with Ollama Backend")
- Remove architecture diagram showing Ollama/PydanticAI integration
- Clarify current status section (mock API, integration prepared)
- Fix uvicorn command: main:app → src.main:app
- Update model examples: llama2 → mistral-nemo:latest
- Mark Ollama requirements as future (not currently needed)
- Update environment variables (Ollama config commented out)
- Clarify API endpoints return mock responses
- Update CVE check date: 2025-12-05 → 2025-12-06
- Fix testing section to use requirements-dev.txt
- Remove Ollama troubleshooting (not connected yet)
- Mark production Ollama considerations as future
- Remove redundant changelog section (use CHANGELOG.md)

AGENTS.md Changes:
- Clarify project overview (mock API, not integrated)
- Add status indicators to components section
- Mark PydanticAI section as "for future implementation"
- Mark Ollama section as "ready for future integration"
- Add target model: mistral-nemo:latest
- Update OpenAI compatibility section with implemented status
- Fix Pydantic version: 2.10+ → 2.11+ (matches requirements)
- Add implementation status to development guidelines
- Mark common patterns as implemented vs future reference
- Update CVE check date: 2025-12-05 → 2025-12-06

CHANGELOG.md Changes:
- Clarify PydanticAI line: "for LLM integration" →
  "dependency (ready for future integration)"

Key Improvements:
- Clear distinction between implemented vs prepared features
- No misleading references to Ollama/PydanticAI integration
- Accurate model names (mistral-nemo:latest)
- Correct command examples (src.main:app)
- Proper date stamps (2025-12-06)
- Removed confusing troubleshooting for unconnected services

Status: Documentation now accurately reflects v0.1.0 mock API

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2025-12-06 11:07:19 +01:00
co-authored by Claude
parent 0e810244bb
commit 62edb111bd
3 changed files with 131 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+74 -45
View File
@@ -4,12 +4,18 @@ This document contains instructions and documentation references for AI assistan
## Project Overview
This project implements an OpenAI-compatible API endpoint using FastAPI, with streaming support for LLM responses. The architecture consists of:
This project implements an OpenAI-compatible API endpoint using FastAPI, with streaming support. Currently returns mock responses - infrastructure prepared for future Ollama/PydanticAI integration.
**Current State**: Production-ready mock API with OpenAI-compatible format
**Future Integration**: Ollama and PydanticAI (client code ready, not connected)
### Components
- **FastAPI**: Web framework for the API layer
- **PydanticAI**: Agent framework for LLM integration
- **Ollama**: LLM backend running on a networked container
- **Stream Coordinator**: Manages streaming responses in OpenAI-compatible format
- **SSE-Starlette**: Server-Sent Events for streaming responses
- **Pydantic**: Request/response validation
- **PydanticAI**: Dependency installed, ready for future LLM integration
- **Ollama**: Async client implemented, ready for future connection
## Documentation References
@@ -40,7 +46,8 @@ This project implements an OpenAI-compatible API endpoint using FastAPI, with st
#### PydanticAI
- **Official Documentation**: https://ai.pydantic.dev/
- **Version**: 1.27.0 (Dec 2025)
- **Key Topics**:
- **Status**: Dependency installed, ready for future integration
- **Key Topics** (for future implementation):
- Agent creation and configuration
- LLM provider integration (Ollama support)
- Structured outputs with Pydantic
@@ -53,7 +60,7 @@ This project implements an OpenAI-compatible API endpoint using FastAPI, with st
#### Pydantic
- **Official Documentation**: https://docs.pydantic.dev/latest/
- **Version**: 2.10+ (Required for PydanticAI)
- **Version**: 2.11+ (Required for PydanticAI, currently using >=2.11,<2.13)
- **Key Topics**:
- Data validation and serialization
- Field types and validators
@@ -83,25 +90,31 @@ This project implements an OpenAI-compatible API endpoint using FastAPI, with st
#### Ollama API
- **Official Documentation**: https://github.com/ollama/ollama/blob/main/docs/api.md
- **Key Topics**:
- **Status**: Async client implemented in `src/ollama/client.py`, ready for future integration
- **Key Topics** (for future implementation):
- REST API endpoints
- Streaming responses
- Model management
- Generate and chat endpoints
- Model configuration
- **Current Model Target**: mistral-nemo:latest
### OpenAI API Compatibility
#### OpenAI API Reference
- **Official Documentation**: https://platform.openai.com/docs/api-reference
- **Key Endpoints to Implement**:
- `/v1/chat/completions` - Chat completion with streaming
- `/v1/models` - List available models
- `/v1/completions` - Text completion (legacy)
- **Key Features**:
- Streaming with Server-Sent Events
- Message format compatibility
- Response structure compatibility
- **Implemented Endpoints**:
- ✅ `/v1/chat/completions` - Chat completion with streaming (mock responses)
- ✅ `/v1/models` - List available models (mock listing)
- **Future Endpoints**:
- 🚧 `/v1/completions` - Text completion (legacy)
- 🚧 `/v1/embeddings` - Text embeddings
- **Implemented Features**:
- ✅ Streaming with Server-Sent Events
- ✅ Message format compatibility
- ✅ Response structure compatibility
- ✅ OpenAI error format
- ✅ Request validation with Pydantic
## FastAPI Best Practices
@@ -270,55 +283,68 @@ app = create_application()
## Development Guidelines
### Code Structure
- Use async/await for ALL I/O operations (database, HTTP, file access)
- Use sync (def) for blocking SDKs or CPU-intensive work
- Implement proper error handling and logging
- Follow dependency injection for validation and shared resources
- Use Pydantic models for ALL request/response validation
- Keep business logic in service modules, not routers
### Code Structure (Current Implementation)
- ✅ Use async/await for ALL I/O operations (database, HTTP, file access)
- ✅ Use sync (def) for blocking SDKs or CPU-intensive work
- ✅ Implement proper error handling and logging
- ✅ Follow dependency injection for validation and shared resources
- ✅ Use Pydantic models for ALL request/response validation
- ✅ Keep business logic in service modules, not routers
- ✅ Domain-based project structure (not file-type based)
### Security Considerations
- Validate all inputs using Pydantic models
- Implement rate limiting for API endpoints
- Use environment variables for sensitive configuration
- Keep dependencies updated (check for CVEs regularly)
- ✅ Validate all inputs using Pydantic models
- ✅ Use environment variables for sensitive configuration
- ✅ Keep dependencies updated (all CVE-checked as of 2025-12-06)
- ✅ Minor version locking for supply chain protection
- 🚧 Implement rate limiting for API endpoints (future)
- 🚧 Add authentication/API keys (future)
### Testing
- Write integration tests for API endpoints
- Test streaming functionality thoroughly
- Mock Ollama responses for unit tests
- Validate OpenAI API compatibility
### Testing (Current Coverage: 62%)
- ✅ Integration tests for API endpoints
- ✅ Streaming functionality with 20s timeout protection
- ✅ Async test support with pytest-asyncio
- ✅ Validate OpenAI API compatibility
- ✅ Mock responses for all endpoints
- 🚧 Future: Mock Ollama responses when integrated
### Configuration
- Use `.env` files for local development
- Document all environment variables in README
- Provide sensible defaults where possible
- Support container-based configuration
- ✅ Use `.env` files for local development
- ✅ Document all environment variables in README
- ✅ Provide sensible defaults where possible
- ✅ BaseSettings from pydantic-settings
- 🚧 Support container-based configuration (future)
## Common Patterns
### Streaming Response Pattern
### Streaming Response Pattern (✅ Implemented)
See `src/chat/router.py` for the current implementation:
```python
from sse_starlette.sse import EventSourceResponse
from fastapi import FastAPI
async def event_generator():
# Stream events from Ollama/PydanticAI
yield {"data": "chunk1"}
yield {"data": "chunk2"}
# Currently yields mock lorem ipsum chunks
# Future: Stream from Ollama/PydanticAI
yield {"data": chunk.model_dump_json()}
yield {"data": "[DONE]"}
@app.get("/stream")
@app.post("/stream")
async def stream():
return EventSourceResponse(event_generator())
```
### PydanticAI Agent Pattern
### PydanticAI Agent Pattern (🚧 Future Reference)
For future integration when connecting to Ollama:
```python
from pydantic_ai import Agent
agent = Agent(
'ollama:llama2', # Or other Ollama model
'ollama:mistral-nemo', # Target model
# Configuration here
)
@@ -326,13 +352,16 @@ agent = Agent(
result = await agent.run('Your prompt')
```
### OpenAI-Compatible Response Format
### OpenAI-Compatible Response Format (✅ Implemented)
Current implementation in `src/chat/schemas.py`:
```python
{
"id": "chatcmpl-123",
"object": "chat.completion.chunk",
"created": 1234567890,
"model": "model-name",
"model": "mistral-nemo:latest",
"choices": [{
"index": 0,
"delta": {"content": "response"},
@@ -349,4 +378,4 @@ This document should be updated when:
- Breaking API changes occur
- Security vulnerabilities are discovered
Last updated: 2025-12-05
Last updated: 2025-12-06