Skip to content

README.md

Latest commit

 

History

History
204 lines (158 loc) · 7.19 KB

README.md

File metadata and controls

204 lines (158 loc) · 7.19 KB
Raw

MiniVault API

A minimal, production-grade REST API for prompt generation using a local LLM (Ollama with gemma:2b). Built with Domain-Driven Design (DDD) principles, clean architecture, and robust testing.

  • Minimal, synchronous API for clarity.
  • All logic is local; no cloud LLMs are used.

⚡ Quickstart

  1. Install Go 1.24+ and Ollama
  2. Pull the model: ollama pull gemma:2b
  3. Run Ollama: ollama serve &
  4. Start API: 
    go run cmd/main.go

    ℹ️ Loads environment variables from a .env file if present (via joho/godotenv).

  5. Test: 
    curl -X POST http://localhost:8080/generate \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "What is ModelVault?"}'

✨ Features

  • 🦾 Local LLM API: Uses Ollama (default: gemma:2b) for fast, private prompt generation
  • 🏛️ Clean Architecture: DDD-inspired, testable, and maintainable
  • 🧪 Comprehensive Unit Tests: Mocks for all ports/interfaces
  • 📝 Structured Logging: JSONL logs for generations, console logs for errors/info
  • ⚙️ Configurable via .env: Easily override defaults
  • 🔒 Request Validation: Strict input checks and error handling
  • 🪝 Middleware: Request body size limit (4KB), panic recovery, and more

🏛️ Architecture

Layered, DDD-inspired structure:

flowchart TD
    Client["🌐 Client (curl, Postman, etc.)"] --> API["🔌 API Layer (api/)"]
    API --> Usecases["⚙️ Application Layer (usecases/)"]
    Usecases --> Domain["🏗️ Domain Layer (domain/)"]
    Usecases --> Infra["🔧 Infrastructure Layer (infrastructure/)"]
    API -->|HTTP| Server["🖥️ Server & Middleware (server/)"]
    Infra -->|LLM, Logging| Ollama["🤖 Ollama, Logger"]
    Server --> API
    
    style Client fill:#e1f5fe
    style API fill:#f3e5f5
    style Usecases fill:#e8f5e8
    style Domain fill:#fff3e0
    style Infra fill:#fce4ec
    style Server fill:#f1f8e9
    style Ollama fill:#e0f2f1
Loading

Layer Descriptions:

  • 🌐 Client: Sends HTTP requests to the API.
  • 🔌 API Layer (api/): Parses requests, validates input, delegates to usecases, formats responses.
  • 🖥️ Server & Middleware (server/): Sets up HTTP server, routes, body size limit (4KB), panic recovery, etc.
  • ⚙️ Application Layer (usecases/): Orchestrates business logic, implements domain interfaces, calls infrastructure.
  • 🏗️ Domain Layer (domain/): Core business entities, validation, and interfaces (ports).
  • 🔧 Infrastructure Layer (infrastructure/): Adapters for logging and LLM (Ollama), handles external communication.
  • ⚙️ Config (config/): Centralized configuration management, loads env vars.
  • 🧪 Mocks (mocks/): Test doubles for all ports/interfaces.

Request Flow:

🌐 Client → 🔌 API Handler → ⚙️ Usecase (Application) → 🏗️ Domain Validation → 🔧 Infrastructure (Ollama, Logger) → Response

📂 Code Structure

minivault/
├── api/                # HTTP handlers
├── cmd/                # Entry point (main.go)
├── config/             # Centralized configuration management
├── domain/             # Entities, validation, ports (interfaces)
├── infrastructure/     # Adapters: logging, LLM (Ollama)
├── mocks/              # Generated/test mocks
├── server/             # Server and middleware
├── usecases/           # Application/business logic
├── logs/               # Interaction logs (created at runtime)
├── go.mod, go.sum      # Go dependencies
└── README.md           # This file

🚀 API Documentation

POST /generate

Generate a response for a given prompt using the local LLM.

  • URL: /generate
  • Method: POST
  • Content-Type: application/json
  • Body Size Limit: 4KB (4096 bytes)

Request Body

{
  "prompt": "What is ModelVault?"
}

Response

{
  "response": "..."
}

Error Responses

Code Description Example message
400 Invalid JSON / Validation "Invalid JSON" / "Validation error"
405 Method not allowed "Method not allowed"
500 Internal error "Failed to generate response"
  • All responses include an X-Request-ID header for tracing.

Example Usage

curl -X POST http://localhost:8080/generate \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "What is ModelVault?"}'

⚙️ Configuration

MiniVault uses environment variables (optionally loaded from a .env file) for configuration. The following settings are available:

Variable Default Description
MINIVAULT_PORT :8080 The port/address the API server listens on
OLLAMA_URL http://localhost:11434/api/chat The URL for the Ollama chat API
OLLAMA_MODEL gemma:2b The Ollama model to use for generation (must be installed)

Tip: Create a .env file in the project root to override these defaults. Example:

MINIVAULT_PORT=:8080
OLLAMA_URL=http://localhost:11434/api/chat
OLLAMA_MODEL=gemma:2b

Note: The value of OLLAMA_MODEL must match a model that is installed in your local Ollama instance. For example, if you set OLLAMA_MODEL=llama2:7b, you must have run ollama pull llama2:7b beforehand.

🧪 Testing

  • All business logic, HTTP handlers, and infrastructure are covered by unit tests.
  • Mocks for all ports/interfaces (mocks/ directory)
  • Run all tests: 
    go test ./...
  • Key tests:
    • Success and error cases for /generate
    • Input validation, HTTP codes, and edge cases
    • Logging and infrastructure behavior

📜 Logging

  • Generation interactions: Structured JSONL format, saved to logs/log.jsonl
  • Errors, warnings, info: Console (with timestamps)
  • Uses zerolog for structured logging

🛠️ Troubleshooting

  • Ollama not running? Ensure you have started Ollama with ollama serve & and pulled the required model.
  • Port already in use? Change MINIVAULT_PORT in your .env file.
  • No logs? The logs/ directory is created automatically. Check permissions if missing.
  • Prompt too large? Requests over 4KB will be rejected.
  • Model not found? Make sure the model in OLLAMA_MODEL is installed in your Ollama instance.

🛠️ Improvements & TODOs

  • Streaming responses (token-by-token)
  • [*] Make model/endpoint configurable via env vars
  • Add CLI or Postman collection for easier testing
  • Add more endpoints (health, status, etc.)
  • [*] Expand test coverage (integration, infra)
  • Enhance error handling and observability

Made for the ModelVault take-home project.