# 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.