git.stella-ops.org/src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/AGENTS.md

AdvisoryAI WebService Agent Charter

Mission

• Expose HTTP API endpoints for Advisory AI interactions.
• Handle request validation, rate limiting, and response formatting.
• Coordinate with consent, justification, and orchestration services.

Responsibilities

• Maintain API endpoint definitions in Program.cs (minimal APIs).
• Keep request/response contracts stable and documented.
• Enforce rate limiting, consent checks, and proper error handling.
• Wire hosting extensions and router integration.

Required Reading

• docs/README.md
• docs/07_HIGH_LEVEL_ARCHITECTURE.md
• docs/modules/platform/architecture-overview.md
• docs/modules/advisory-ai/architecture.md
• src/AdvisoryAI/AGENTS.md (parent module charter)
• docs/modules/policy/guides/assistant-parameters.md (guardrail and ops knobs)
• docs/modules/advisory-ai/deployment.md (service configuration)

Working Directory & Scope

• Primary: src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/
• Dependencies: StellaOps.AdvisoryAI, StellaOps.AdvisoryAI.Hosting
• Shared libraries: Router.AspNet for Stella Router integration

Key Components

• Program.cs ??? WebApplication setup, endpoint mapping, middleware pipeline.
• Contracts/ ??? Request/response DTOs for API endpoints:
  • AdvisoryPlanRequest/Response ??? plan generation
  • AdvisoryExecuteRequest ??? execution trigger
  • AdvisoryQueueRequest/Response ??? queue management
  • ExplainRequest/Response ??? explanation endpoints
  • ConsentContracts ??? AI consent management (VEX-AI-016)
  • JustifyContracts ??? justification generation
  • PolicyStudioContracts ??? policy studio integration
  • RemediationContracts ??? remediation plan endpoints
• Services/ ??? Service implementations:
  • IAiConsentStore / InMemoryAiConsentStore ??? consent tracking
  • IAiJustificationGenerator / DefaultAiJustificationGenerator ??? justification generation

API Endpoints

• POST /api/advisory/plan ??? Generate advisory plan
• POST /api/advisory/execute ??? Execute advisory plan
• POST /api/advisory/queue ??? Queue advisory task
• GET /api/advisory/output/{id} ??? Retrieve advisory output
• POST /api/advisory/explain ??? Generate explanation
• Consent and justification endpoints per VEX-AI-016

Testing Expectations

• Unit tests in __Tests/StellaOps.AdvisoryAI.Tests cover endpoint logic.
• Integration tests use WebApplicationFactory for full pipeline testing.
• Test rate limiting behavior, consent enforcement, and error responses.
• Verify request validation and contract serialization.

Working Agreement

• Determinism: stable response ordering, content-addressed output IDs.
• Offline-friendly: endpoints must degrade gracefully when inference is unavailable.
• Observability: structured logs with request correlation ids; expose rate limiter metrics.
• Configuration: bind from appsettings.json and environment variables (ADVISORYAI__ prefix).
• Security: validate all input, enforce consent where required, no embedding secrets.
• Update sprint status in docs/implplan/SPRINT_*.md when starting/completing work.
• Mirror decisions in sprint Decisions & Risks section.