Skip to content

AGENTS.md

Latest commit

 

History

History
45 lines (37 loc) · 5.52 KB

AGENTS.md

File metadata and controls

45 lines (37 loc) · 5.52 KB
Raw

Repository Guidelines

Project Structure & Modules

  • modules/core is the spine (LLM client API, config, tool API, tracing and metrics contracts), designated stable for 1.0; no MiMa baseline is active yet. The agent runtime and guardrails are modules/agent, the built-in tools modules/agent-tools, providers their own modules (modules/openai, modules/anthropic, …), and RAG, memory, MCP, image, speech and observability likewise; build.sbt lists them all. A new module must also be added to hooks/pre-commit. Workspace support sits in modules/workspace (runner/client/shared), and runnable demos are in modules/samples. docs/ stores documentation; hooks/ provides the pre-commit installer. Sources live in src/main/scala; add version-specific sources under src/main/scala-3 when needed. See also szork - a demo game showcasing LLM4S agents.

Build, Test, and Development Commands

  • Compile: sbt compile. Run examples via sbt "samples/runMain org.llm4s.samples.basic.BasicLLMCallingExample".
  • Tests: sbt test for the full build or module-specific runs (e.g., sbt core/test).
  • Pipeline: sbt buildAll compiles and tests; slower but mirrors CI.
  • Formatting/linting: sbt scalafmtAll is required; sbt scalafixAll is available for extra hygiene.
  • Dev hook: ./hooks/install.sh installs a pre-commit that runs scalafmt, compile, and tests.

Configuration Boundary

  • Core main code must not read configuration directly. PureConfig/env/system property access lives only in org.llm4s.config; everywhere else consumes typed settings injected from the app edge.
  • Llm4sConfig is for edge use (samples, CLIs, tests). Any reference to it in core main code is a violation.
  • Scalafix enforces this across every module's src/main/scala: uses of ConfigFactory, ConfigSource.default, sys.env, or System.getenv are blocked (except inside org.llm4s.config, which opts out with a // scalafix:off marker). Tests and runnable mains are exempt.

Coding Style & Naming Conventions

  • .scalafmt.conf enforces two-space indents, aligned imports/params, and trailing commas; run scalafmt instead of hand-formatting.
  • Favor immutability, pure functions, and explicit types at module boundaries. Keep logging consistent with existing org.slf4j usage.
  • Naming: types PascalCase, members camelCase, constants SCREAMING_SNAKE_CASE. Tests end with Spec or Test to match neighboring suites.

Testing Guidelines

  • Scalatest is primary; Scalamock is available. Integration suites often mix in ScalaFutures or BeforeAndAfterAll.
  • Place tests under src/test/scala, mirroring the package of the code under test.
  • Keep version-specific tests inside the owning module only when Scala-version behavior genuinely differs.
  • Typical flow: sbt test for quick checks or sbt buildAll before PR. Coverage (when needed): sbt coverage test coverageReport.
  • Suites needing an external service live in modules/it and must declare a tier by class annotation (@Local, @Docker, @Workspace, @Ollama, @Cloud from org.llm4s.it.tags); sbt it/itTierCheck fails the build if one does not. Run a tier with sbt testIntegration / testWorkspace / testOllama / testSmoke, and gate on Tier.require rather than assume so LLM4S_IT_STRICT=true runs turn a missing service into a failure.

Issue Templates

  • We provide structured GitHub templates to streamline contributions and improve issue quality.
  • Bug Reports (bug_report.yml): Use for crashes, errors, unexpected behavior. Include environment (Scala, JDK, OS), LLM provider/model, reproduction steps, and error logs.
  • Feature Requests (feature_request.yml): Use for new functionality. Describe problem, proposed solution, alternatives considered, and willingness to implement.
  • Enhancements (enhancement.yml): Use to improve existing features. Explain current behavior, proposed improvement, benefits, and implementation approach.
  • See CONTRIBUTING.md for detailed contribution guidelines and contribution-guidelines.md for advanced patterns.

Commit & Pull Request Guidelines

  • Use short, imperative commit subjects (e.g., "Add centralized model metadata system") and include issue/PR refs when relevant.
  • Before a PR: run scalafmtAll and tests, update docs for user-facing changes, and add sample commands/output for new workflows.
  • PR text should state motivation, key changes, and validation steps. Screenshots only when altering docs/assets; otherwise keep notes concise.
  • Always use the structured templates when opening issues or PRs to ensure consistency and completeness.

Security & Configuration Tips

  • Never commit secrets. Providers are configured as named sections under llm4s.providers in HOCON; keep API keys in env vars or in the untracked application.local.conf, never in a committed file. Each provider module binds its vendor's conventional variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, ...) to the shared llm4s.credentials.<providerId>.apiKey, which a section without its own apiKey uses; a section for a second account binds its own (apiKey = ${?OPENAI_BATCH_API_KEY}), and in production every section should. llm4s reads no LLM_MODEL; see docs/getting-started/configuration.md#api-keys.
  • For workspace demos, ensure Docker is running before sbt docker:publishLocal or workspace samples, and scrub sensitive data from logs.