CONTRIBUTING.md

# Contributing to OnDeviceAgent

Thanks for your interest in contributing. This document covers how to work on the
`com.sky.ondeviceagent` package and the conventions to follow.

## Prerequisites

- **Unity 6000.4.8f1** (Unity 6.x). Other versions are untested.
- An [Ollama](https://ollama.com) server for the desktop/Editor LLM path.
- Network access on first use: the on-device model weights are **not** vendored — the `com.sky.sentis.*`
  dependency packages provision their weights from Hugging Face on demand, and the Android LLM streams
  from Hugging Face on first launch. See [docs/getting-started.md](docs/getting-started.md).

## Working on the package

The package is consumed by a Unity project that references it (embedded under `Packages/`, or via a
git/local reference in `Packages/manifest.json`). To develop against it:

1. Open a Unity project that embeds this package. Unity restores dependencies from `package.json`.
2. For a runnable scene that wires the full pipeline, use the
   [ondeviceagent-sample](https://github.com/skykim/ondeviceagent-sample) project, then press Play.

For the Android on-device LLM path see [docs/android-llm.md](docs/android-llm.md); the Kotlin/JNI
bridge source ships in this package under `AndroidBridge~/` (rebuild with JDK 17 via
`./gradlew assembleRelease`).

## Package layout

- `Runtime/` — the framework source, split into assemblies:
  - `OnDeviceAgent.AgentCore` (`Runtime/AgentCore`) — agent runtime, tools, memory, RAG, presentation.
  - `OnDeviceAgent.Inference` (`Runtime/Inference`) — camera, vision, audio, STT, TTS.
  - `OnDeviceAgent.VoiceManager` (`Runtime/VoiceManager`) — voice-pipeline orchestration.
  - `OnDeviceAgent.RagLlm` (`Runtime/AgentCore/Rag/Llm`) — isolated chat-LLM clients for RAG.
  - `OnDeviceAgent.AgentCore.Editor` (`Runtime/AgentCore/Editor`) — Editor-only tooling (custom
    drawers, menus, build preprocessors).
- `Runtime/Plugins/` — bundled third-party managed DLLs (LightRAG.NET, Microsoft Agent Framework) and
  the Android bridge (`Plugins/Android/llm-release.aar` + EDM4U deps). See
  [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
- `AndroidBridge~/` — Kotlin/JNI bridge source for the LiteRT-LM AAR (hidden from the importer by `~`).
- `docs/` — architecture and usage documentation.
- The Voice Assistant sample lives in the
  [ondeviceagent-sample](https://github.com/skykim/ondeviceagent-sample) repository.

## Conventions

- **Assembly layering is strict and acyclic.** Do not introduce cycles. Editor code stays in the
  `*.Editor` assembly (platform-gated to Editor) and must never be referenced by runtime assemblies.
  See [docs/architecture.md](docs/architecture.md).
- **Namespaces** match the owning assembly (`OnDeviceAgent.AgentCore`, `OnDeviceAgent.Inference`, …).
- **No runtime `Instantiate`/`AddComponent` for framework wiring** — components are pre-placed in the
  scene and wired via `SerializeField`.
- Keep tooltips and comments sparse and purposeful.
- Documentation and user-facing strings default to English.

## Before opening a PR

- Make sure the project compiles in Unity with no new warnings in the framework assemblies.
- Run the Voice Assistant sample to confirm the voice pipeline still works end to end.
- If you add a third-party dependency or model, update [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## License

By contributing, you agree that your contributions are licensed under the project's
[Apache License 2.0](LICENSE.md).