Engineering
This section contains the engineering artifacts that document TramAI's design decisions, implementation plans, and operational processes.
Sections
| Section | Description |
|---|---|
| Architecture Decision Records (ADRs) | Record of key architectural decisions. Covers annotated interfaces, proxy generation, structured output, provider routing, streaming, tool calling, orchestration, and more. |
| Specifications | Spec-driven development — each spec defines scope, requirements, and acceptance criteria for a meaningful implementation slice. |
| Roadmap | High-level implementation plan across five phases, from foundation to production hardening and beyond. |
| Releasing | Maintainer runbook for cutting TramAI releases — preconditions, workflows, secrets, local validation, and guarded provider checks. |
| Contributing | Guide for contributors — setting up the dev environment, submitting PRs, running tests, and coding conventions. |
| Release Validation | Concrete release-validation evidence — local publication, signed artifacts, native image compilation, and OTel export proof. |
ADR Index
- ADR-001: Use Annotated Interface Methods as the Primary AI Abstraction
- ADR-002: Start with Runtime Proxy Generation Using JDK Dynamic Proxy
- ADR-003: Make Structured Output the Default Non-String Contract
- ADR-004: Use Custom Jackson-Based Schema Generation
- ADR-005: Keep the Core Framework-Agnostic and Ship Adapters Separately
- ADR-006: Enable OpenTelemetry Observability Automatically When Present
- ADR-007: Resolve Providers from Model Names with Explicit Override Support
- ADR-008: Build Kotlin-Native APIs with Java-Friendly Entry Points
- ADR-009: Keep Retry Orchestration in tramai-engine and Structured Analysis in tramai-structured
- ADR-010: Use an Explicit Provider Registry Instead of Model-Prefix Routing
- ADR-011: Support Explicit Blocking Service Interfaces in v1 Instead of Auto-Generated *Blocking Counterparts
- ADR-012: Keep tramai-standalone Minimal and Make Observability an Explicit Opt-In Module
- ADR-013: Start Streaming with Raw Text and a Dedicated Streaming Contract
- ADR-014: Keep Tool Calling Engine-Owned and Provider-Portable
- ADR-015: Limit Streaming Failover to Startup Before the First Emitted Token
- ADR-016: Keep Runtime Proxies and Ship Explicit Native-Image Proxy Metadata Support
- ADR-017: Keep Orchestration Typed, Workflow-Owned, and Optional Above tramai-engine
Spec Index
- SPEC-001: Core Engine and Proxy Execution
- SPEC-002: Structured Output Pipeline
- SPEC-003: Provider Integration and Routing
- SPEC-004: Observability Integration
- SPEC-005: Standalone Runtime and Java API
- SPEC-006: Spring Boot Adapter
- SPEC-007: Testing Support
- SPEC-008: Documentation and Publishing Readiness
- SPEC-009: Streaming Responses
- SPEC-010: Tool Calling
- SPEC-011: Production Hardening
- SPEC-012: Orchestration and Coordination
- SPEC-019: RAG and Provider Expansion