Intelligence Module Specification¶

Purpose¶

The intelligence module implements the Intelligence Domain and is the AIOS-facing module inside the Spring Boot Modulith. It governs Digital Professional orchestration, AI agent registration, reasoning sessions, confidence scoring, explainability, AI memory records, execution requests, guardrail decisions, Event Mesh interaction, and audit logging.

Owned Domain¶

Intelligence owns intelligence orchestration and reasoning records. It may read, reference, reason over, and propose actions using source-domain context, but it does not own Organization, Compliance, Opportunity, Bid, Contract, Supplier, Marketplace, Funding, Learning, Notification, Analytics, Billing, or Administration source facts.

Owned Aggregates¶

Aggregate	Responsibility
Intelligence Director	Coordinates routing, orchestration, and assignment of intelligence work.
AI Agent Registry	Governs approved AI agents and Digital Professional runtime identities.
Reasoning Session	Bounded reasoning activity with inputs, context, outputs, confidence, and explainability.
AI Memory Record	Intelligence-domain memory entry with provenance, access scope, and retention.
Execution Request	Governed request to perform or advance executable work.
Guardrail Decision	Human approval, automation policy result, approver, and conditions.
Intelligence Audit Trail	Immutable AI activity and decision records grouped by correlation or session.

Owned Entities¶

Intelligence Director, AI Agent, Digital Professional Runtime, Reasoning Session, Reasoning Step, AI Memory Entry, Execution Request, Guardrail Decision, Explainability Record, Confidence Assessment, Audit Log Entry, and Event Subscription.

Owned Value Objects¶

IntelligenceSessionId, AgentId, DigitalProfessionalId, OrganizationContextRef, ConfidenceScore, ConfidenceBand, ReasoningObjective, ReasoningMode, EvidenceReference, ExplainabilitySummary, ApprovalRequirement, GuardrailResult, MemoryScope, and AuditCorrelationId.

Commands¶

Command	Responsibility
StartIntelligenceSession	Start bounded reasoning with objective, actor, tenant, and source references.
LoadOrganizationContext	Load organization context references for customer-bound reasoning.
RegisterAIAgent	Register governed AI agent or Digital Professional runtime identity.
SelectAgent	Route work to an approved agent or Digital Professional.
ExecuteReasoning	Run approved reasoning pattern and record output.
AssessConfidence	Score output confidence with method and threshold.
RecordExplainability	Capture evidence, assumptions, limitations, and rationale.
EvaluateGuardrail	Decide whether work is allowed, blocked, or approval-gated.
RequestExecution	Request governed workflow execution through owning-domain boundaries.
UpdateAIMemory	Store intelligence memory record with provenance and retention.
RecordIntelligenceAudit	Write append-only audit event for AI activity.

Queries¶

Query	Responsibility
GetIntelligenceSession	Return reasoning session status, context references, and outputs.
GetRegisteredAgents	Return approved AI agents and runtime statuses.
GetDigitalProfessionalRuntime	Return Digital Professional runtime mapping and capability scope.
GetConfidenceAssessment	Return score, method, threshold, and limitations.
GetExplainabilityRecord	Return explanation, evidence references, assumptions, and limitations.
GetGuardrailDecision	Return approval requirement and policy result.
GetAIMemoryRecords	Return scoped memory records where authorized.
GetExecutionRequests	Return execution request status and owning-domain response references.
GetIntelligenceAuditTrail	Return audit records by session, agent, or correlation ID.

Application Services¶

IntelligenceSessionApplicationService, AgentRegistryApplicationService, DigitalProfessionalRuntimeApplicationService, OrganizationContextApplicationService, ReasoningApplicationService, ConfidenceApplicationService, ExplainabilityApplicationService, GuardrailApplicationService, AIMemoryApplicationService, ExecutionCoordinationApplicationService, and IntelligenceAuditApplicationService.

Domain Services¶

OrganizationContextService, AgentSelectionService, ReasoningService, ConfidenceThresholdService, HumanApprovalService, ExplainabilityService, AIMemoryPolicyService, CrossDomainOwnershipService, and IntelligenceAuditService.

Policies¶

Organization Context Policy, Agent Selection Policy, Confidence Threshold Policy, Human Approval Policy, Explainability Policy, AI Memory Policy, Audit Logging Policy, and Cross-Domain Ownership Policy.

Repositories¶

IntelligenceSessionRepository, AIAgentRepository, DigitalProfessionalRuntimeRepository, ReasoningStepRepository, ConfidenceAssessmentRepository, ExplainabilityRecordRepository, GuardrailDecisionRepository, ExecutionRequestRepository, AIMemoryRepository, IntelligenceEventSubscriptionRepository, and IntelligenceAuditRepository.

Events Published¶

IntelligenceSessionStarted, OrganizationContextLoaded, AgentSelected, ReasoningCompleted, ConfidenceAssessed, HumanApprovalRequired, HumanApprovalGranted, HumanApprovalRejected, ExecutionRequested, ExecutionBlocked, AIMemoryUpdated, ExplainabilityRecorded, and IntelligenceAuditLogged.

Events Consumed¶

OrganizationProfileUpdated, OrganizationalMemoryUpdated, ProcurementReadinessScoreUpdated, ComplianceRiskIdentified, TenderDiscovered, TenderMatchedToOrganization, BidOutcomeCaptured, ContractLessonsLearnedCaptured, SupplierTrustUpdated, FundingNeedIdentified, LearningRecommendationCreated, NotificationAcknowledged, MetricSnapshotCreated, EntitlementsUpdated, and PolicyConfigurationChanged.

REST API Responsibility¶

The module owns API responsibilities for intelligence sessions, AI agent registry, Digital Professional runtime routing, organization context loading, reasoning, confidence, explainability, guardrail evaluation, AI memory, execution requests, and intelligence audit views. Final endpoint specs are deferred.

Database Ownership¶

Intelligence owns conceptual persistence for intelligence sessions, AI agents, Digital Professional runtimes, reasoning steps, confidence assessments, explainability records, guardrail decisions, execution requests, AI memory entries, event subscriptions, and intelligence audit logs.

Module Dependencies¶

Allowed dependencies are shared kernel identifiers, identity authorization context, source-domain read models and events, organization context APIs, notification approval requests, analytics projections, administration policy configuration events, and governed provider adapters through infrastructure boundaries.

Forbidden Dependencies¶

Intelligence must not directly mutate source-domain facts, bypass owning-domain application services, store secrets, override Identity authorization, issue Billing entitlements, send Notification deliveries directly, or become the canonical store for operational facts.

AIOS Interaction Boundary¶

This module is the AIOS boundary. AIOS interacts with Algosure through governed Intelligence application services, source-domain APIs, events, guardrails, approval workflows, and audit records. Execution requests must be routed to owning domains for final mutation decisions.

Security And Tenant Rules¶

Customer-bound reasoning requires OrganizationId, actor context, authorization, source references, and audit correlation.
AI memory must be scoped by tenant, domain, session, or approved global policy.
Guardrails must block or approval-gate high-impact actions.
Confidence and explainability are required for customer-facing recommendations.
Prompt, model, provider, input, output, and evidence handling must respect data classification and retention rules.

Test Strategy¶

Tests must cover organization context validation, agent registration, routing, confidence thresholds, explainability requirements, guardrail decisions, approval requirements, memory scope, audit logging, event publication, idempotent event consumption, tenant isolation, and Spring Modulith boundary verification.

Future Microservice Extraction Notes¶

Intelligence is a strong extraction candidate because AI orchestration, provider calls, memory, and guardrails may scale independently. Extraction requires stable source-domain contracts, event contracts, tenant-scoped memory boundaries, service authentication, audit delivery, and no direct source-domain persistence access.

Mermaid Component Diagram¶

flowchart TD
    Api[intelligence.api.rest]
    App[intelligence.application.service]
    Command[intelligence.application.command]
    Query[intelligence.application.query]
    Domain[intelligence.domain.model]
    Policy[intelligence.domain.policy]
    Repo[intelligence.infrastructure.persistence]
    Integration[intelligence.infrastructure.integration]
    Messaging[intelligence.infrastructure.messaging]
    Identity[identity authorization]
    Organization[organization context]
    Domains[source domain APIs]
    Notification[notification approvals]
    Analytics[analytics projections]

    Api --> App
    App --> Command
    App --> Query
    App --> Domain
    Domain --> Policy
    App --> Repo
    App --> Integration
    App --> Messaging
    App --> Identity
    App --> Organization
    App --> Domains
    Messaging --> Notification
    Messaging --> Analytics