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