# Mokksy and AI-Mocks Project Guidelines

## Project Overview

Mokksy and AI-Mocks are a suite of tools designed for mocking HTTP and LLM (Large Language Model) APIs for testing and
development purposes.

### Components

1. **Mokksy**

- A mock HTTP server built with Kotlin and Ktor
- Supports true Server-Side Events (SSE) and streaming responses
- Designed to overcome limitations in existing tools like WireMock
- Provides a flexible, fluent Kotlin DSL API

2. **AI-Mocks**

- Specialized mock server implementations built on top of Mokksy
- Currently supports:
  - OpenAI API (`ai-mocks-openai`)
  - Anthropic API (`ai-mocks-anthropic`)
  - Google Gemini (`ai-mocks-gemini`)
- Allows developers to mock LLM API responses for testing and development

### Key Features

- **Streaming Support**: True support for streaming responses and Server-Side Events (SSE)
- **Response Control**: Flexibility to control server responses directly
- **Delay Simulation**: Support for simulating response delays and delays between chunks
- **Modern API**: Fluent Kotlin DSL API with Kotest Assertions
- **Error Simulation**: Ability to mock negative scenarios and error responses

### Project Structure

- `ai-mocks-a2a-client`: Agent2Agent (A2A) client. Used for testing
- `ai-mocks-a2a`: Agent2Agent (A2A) protocol mocks
- `ai-mocks-a2a-models`: Agent2Agent (A2A) protocol models. Copy
  of [A2A specification](ai-mocks-a2a-models/a2a-specification-0.3.0.md)
- `ai-mocks-core`: Core functionality shared across AI-Mocks implementations
- `ai-mocks-openai`: OpenAI API mock implementation
- `ai-mocks-anthropic`: Anthropic API mock implementation
- `ai-mocks-gemini`: Google Gemini/GenAI API mock implementation
- `ai-mocks-ollama`: Ollama API mock implementation
- `mokksy`: The underlying mock HTTP server

## Development Guidelines

- Use `git mv` command when renaming files to preserve git history, if possible
- Never commit or push changes to git automatically. Always confirm.
- Ensure new code follows existing code style and design patterns.
- Use MCP servers, if available, to edit code and run tests. Run terminal commands directly.

### Code Style

#### Kotlin

- Follow Kotlin coding conventions
- Use the provided `.editorconfig` for consistent formatting
- Use Kotlin typesafe DSL builders where possible and prioritize fluent builders style over standard builder methods.
  If DSL builders produce less readable code, use standard setter methods.
- Prefer DSL builder style (method with lambda blocks) over constructors, if possible.
- Use Kotlin's `val` for immutable properties and `var` for mutable properties
- Use fully qualified imports instead of star imports
- Ensure to preserve backward compatibility when making changes

#### Java

- Use the provided `.editorconfig` for consistent formatting
- For Java code, prefer fluent DSL style over standard bean getters and setter methods

### Testing

- Write comprehensive tests for new features
- Prioritize test readability
- Use function `Names with backticks` for test methods in Kotlin, e.g. "fun `should return 200 OK`()"
- Avoid writing KDocs for tests, keep code self-documenting
- Write Kotlin tests with [kotlin-test](https://github.com/JetBrains/kotlin/tree/master/libraries/kotlin.test),
  [mockk](https://mockk.io/) and [Kotest-assertions](https://kotest.io/docs/assertions/assertions.html)
  with infix form assertions `shouldBe` instead of `assertEquals`.
- Use Kotest's `withClue("<failure reason>")` to describe failure reasons, but only when the assertion is NOT obvious.
  Remove obvious cases for simplicity.
- If multiple assertions exist against nullable field, first check for null, e.g.:
  `params shouldNotBeNull { params.id shouldBe 1 }`
- For testing json serialization use [Kotest-assertions-json](https://kotest.io/docs/assertions/json/json-overview.html)
  assertions, e.g. `shouldEqualJson` and never compare substrings.
- Prefer `assertSoftly(subject) { }` over `assertSoftly { }`. Use the no-subject form only when asserting 
  the same invariant across multiple related objects, or when the assertions are tightly coupled.
- When asked to write tests in Java: use JUnit6, Mockito, AssertJ core

#### Parallel Test Execution and Shared Mock Servers

- Apply the `integration-testing` skill when writing or modifying integration tests.
- Tests **must** be safe to run in parallel. Do not disable parallel execution as a workaround for test failures.
- All tests within a module share a single top-level mock server instance. Do not create per-test or per-class isolated mock instances unless specifically testing negative scenarios.
- Mock stubs are **immutable** once registered.
- Use randomized but distinct values for `model`, `seed`, `temperature`, `topK`, `topP`, `maxOutputTokens`, etc. in `@BeforeEach` to ensure parallel safety.
- For each LLM use their native SDK as primary test client. Add smoke-level tests using LangChain4j and SpringAI.

### Documentation

- Update README files when adding new features
- Document API changes in the appropriate module's documentation
- Write tutorials in Hugo markdown /docs/content/docs
- Make sure that in production code interfaces and abstract classes are properly documented. Avoid adding KDocs to
  override functions to avoid verbosity.
- Update KDocs when api is changed.
- When referring classes in KDoc, use references: `[SendMessageRequest]` instead of `SendMessageRequest`.
- Add brief code examples to KDoc
- Add links to specifications, if known. Double-check that the link actual and pointing exactly to the specification.
  Never add broken or not accurate links.

### Project Documentation

The project uses two main tools for documentation:

1. **Dokka** - For API documentation generation from code
2. **Hugo** - For building the documentation website

#### Local Documentation Generation

To generate documentation locally:

1. Generate API documentation with Dokka:
   ```shell
   ./gradlew :docs:dokkaGenerate
   ```
   This will generate API documentation in `docs/public/apidocs/`.

2. Build the Hugo site:
   ```shell
   cd docs
   hugo
   ```
   This will generate the complete site in `docs/public/`.

3. Preview the documentation site locally:
   ```shell
   cd docs
   hugo server
   ```
   This will start a local server (typically at http://localhost:1313/) where you can preview the documentation.

#### Documentation Structure

- API reference documentation is generated from code using Dokka
- User guides and tutorials are written in Markdown in the `docs/content/docs` directory
- Each AI-Mocks module should have its own documentation page

#### Publishing Documentation

Documentation is automatically published to [mokksy.dev](https://mokksy.dev/) when:

- A new release is created
- Changes are pushed to the main branch
- The documentation workflow is manually triggered

The publishing process is handled by the GitHub Actions workflow in `.github/workflows/docs.yaml`.

#### Documentation Content Guidelines

When creating or updating documentation, focus on the following aspects:

1. **API Documentation**:

- Ensure all public APIs have proper KDoc/Javadoc comments
  - Include examples of how to use the API
  - Document parameters, return values, and exceptions
  - Explain the purpose and behavior of each class and method

2. **User Guides and Tutorials**:

- Start with a clear introduction explaining what the module does
- Include step-by-step instructions with code examples
- Provide complete working examples that users can copy and adapt.
- Explain common use cases and best practices
- Include troubleshooting information for common issues
- **Double-check that documentation matches the existing code and tests. Never make up anything not implemented as
  code!**

3. **Documentation for AI-Mocks Modules**:
   Each AI-Mocks module should have documentation that includes:

- Installation instructions
- Basic usage examples
- Configuration options (preferably in table format)
- Advanced usage examples
- Integration with relevant SDKs and frameworks
- Examples of mocking both successful and error responses
- Examples of streaming responses if applicable

4. **Contributions**

- Follow the guidelines in CONTRIBUTING.md
- Create pull requests for new features or bug fixes
- Ensure all tests pass before submitting
- Never commit and push automatically

### Getting Started

For detailed usage instructions and examples, refer to:

- Main README.md for project overview
- Module-specific README files for detailed API documentation
- Sample code in each module's samples directory

### Building the Project

```shell
gradle build
```

or using Make:

```shell
make
```
