sprints work
This commit is contained in:
master
316
docs/modules/opsmemory/chat-integration.md
Normal file
316
docs/modules/opsmemory/chat-integration.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# OpsMemory Chat Integration
|
||||
|
||||
> **Connecting Decision Memory to AI-Assisted Workflows**
|
||||
|
||||
## Overview
|
||||
|
||||
The OpsMemory Chat Integration connects organizational decision memory to AdvisoryAI Chat, enabling:
|
||||
|
||||
1. **Context Enrichment**: Past relevant decisions surface automatically in chat
|
||||
2. **Decision Recording**: New decisions from chat actions are auto-recorded
|
||||
3. **Feedback Loop**: Outcomes improve future AI suggestions
|
||||
4. **Object Linking**: Structured references to decisions, issues, and tactics
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────────┐
|
||||
│ Chat Session │
|
||||
│ ┌────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ User: "What should we do about CVE-2023-44487?" │ │
|
||||
│ └────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ OpsMemoryChatProvider.EnrichContextAsync() │ │
|
||||
│ │ → Query similar past decisions │ │
|
||||
│ │ → Include known issues and tactics │ │
|
||||
│ │ → Return top-3 with outcomes │ │
|
||||
│ └────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Prompt Assembly (via AdvisoryAiPromptContextEnricher) │ │
|
||||
│ │ System: "Previous similar situations..." │ │
|
||||
│ │ - CVE-2022-41903 (same category): Accepted, SUCCESS │ │
|
||||
│ │ - CVE-2023-1234 (similar severity): Quarantined, SUCCESS │ │
|
||||
│ │ Known Issues: [ops-mem:issue-xyz123] may apply │ │
|
||||
│ └────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Assistant Response with Object Links: │ │
|
||||
│ │ "Based on 3 similar past decisions [ops-mem:dec-abc123]..." │ │
|
||||
│ │ [Accept Risk]{action:approve,cve_id=CVE-2023-44487} │ │
|
||||
│ └────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ (if action executed) │
|
||||
│ ┌────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ OpsMemoryDecisionRecorder.RecordFromActionAsync() │ │
|
||||
│ │ → Extract situation from chat context │ │
|
||||
│ │ → Record decision with action, rationale │ │
|
||||
│ │ → Link to Run attestation │ │
|
||||
│ └────────────────────────────────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Components
|
||||
|
||||
### IOpsMemoryChatProvider
|
||||
|
||||
The main interface for chat context enrichment:
|
||||
|
||||
```csharp
|
||||
public interface IOpsMemoryChatProvider
|
||||
{
|
||||
/// <summary>
|
||||
/// Enriches chat context with relevant past decisions.
|
||||
/// </summary>
|
||||
Task<OpsMemoryChatContext> EnrichContextAsync(
|
||||
ChatEnrichmentRequest request,
|
||||
CancellationToken ct = default);
|
||||
|
||||
/// <summary>
|
||||
/// Records a decision made during a chat session.
|
||||
/// </summary>
|
||||
Task RecordDecisionAsync(
|
||||
ChatDecisionRecord record,
|
||||
CancellationToken ct = default);
|
||||
}
|
||||
```
|
||||
|
||||
**Location:** `src/AdvisoryAI/StellaOps.AdvisoryAI/Chat/Integration/IOpsMemoryChatProvider.cs`
|
||||
|
||||
### OpsMemoryChatProvider
|
||||
|
||||
Implementation that queries OpsMemory and formats results for chat:
|
||||
|
||||
- **Similarity Search**: Finds past decisions with similar CVE/severity/category
|
||||
- **Known Issues**: Includes relevant documented issues
|
||||
- **Tactics**: Surfaces applicable response tactics
|
||||
- **Fire-and-Forget Recording**: Async decision capture without blocking UX
|
||||
|
||||
**Location:** `src/AdvisoryAI/StellaOps.AdvisoryAI/Chat/Integration/OpsMemoryChatProvider.cs`
|
||||
|
||||
### AdvisoryAiPromptContextEnricher
|
||||
|
||||
Transforms OpsMemory context into AI prompt format:
|
||||
|
||||
```csharp
|
||||
public interface IAdvisoryAiPromptContextEnricher
|
||||
{
|
||||
/// <summary>
|
||||
/// Enriches AI prompt with OpsMemory context.
|
||||
/// </summary>
|
||||
Task<PromptEnrichmentResult> EnrichAsync(
|
||||
PromptEnrichmentRequest request,
|
||||
CancellationToken ct = default);
|
||||
}
|
||||
```
|
||||
|
||||
**Location:** `src/AdvisoryAI/StellaOps.AdvisoryAI/Chat/Integration/AdvisoryAiPromptContextEnricher.cs`
|
||||
|
||||
## Object Link Format
|
||||
|
||||
OpsMemory uses structured object links for cross-referencing:
|
||||
|
||||
| Type | Format | Example |
|
||||
|------|--------|---------|
|
||||
| Decision | `[ops-mem:dec-{id}]` | `[ops-mem:dec-abc12345]` |
|
||||
| Known Issue | `[ops-mem:issue-{id}]` | `[ops-mem:issue-xyz98765]` |
|
||||
| Tactic | `[ops-mem:tactic-{id}]` | `[ops-mem:tactic-respond-001]` |
|
||||
| Playbook | `[ops-mem:playbook-{id}]` | `[ops-mem:playbook-log4j-response]` |
|
||||
|
||||
### Link Resolution
|
||||
|
||||
The `OpsMemoryLinkResolver` resolves object links to display text and URLs:
|
||||
|
||||
```csharp
|
||||
public interface IObjectLinkResolver
|
||||
{
|
||||
/// <summary>
|
||||
/// Resolves an object link to display information.
|
||||
/// </summary>
|
||||
Task<ObjectLinkResolution?> ResolveAsync(
|
||||
string objectLink,
|
||||
CancellationToken ct = default);
|
||||
}
|
||||
```
|
||||
|
||||
**Example Resolution:**
|
||||
|
||||
```
|
||||
Input: [ops-mem:dec-abc12345]
|
||||
Output:
|
||||
- DisplayText: "Accept Risk decision for CVE-2022-41903"
|
||||
- Url: "/opsmemory/decisions/abc12345"
|
||||
- Metadata: { outcome: "SUCCESS", actor: "security-team" }
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
AdvisoryAI:
|
||||
Chat:
|
||||
OpsMemory:
|
||||
# Enable OpsMemory integration
|
||||
Enabled: true
|
||||
|
||||
# Maximum number of similar decisions to surface
|
||||
MaxSuggestions: 3
|
||||
|
||||
# Minimum similarity score (0.0-1.0)
|
||||
MinSimilarity: 0.5
|
||||
|
||||
# Include known issues in context
|
||||
IncludeKnownIssues: true
|
||||
|
||||
# Include response tactics
|
||||
IncludeTactics: true
|
||||
|
||||
# Automatically record decisions from actions
|
||||
RecordDecisions: true
|
||||
|
||||
OpsMemory:
|
||||
Integration:
|
||||
# Link recorded decisions to AI Run attestations
|
||||
AttestationLinking: true
|
||||
|
||||
# Don't block chat flow on recording
|
||||
FireAndForget: true
|
||||
```
|
||||
|
||||
## Known Issues and Tactics
|
||||
|
||||
### Known Issues
|
||||
|
||||
Document common false positives or expected behaviors:
|
||||
|
||||
```csharp
|
||||
public interface IKnownIssueStore
|
||||
{
|
||||
Task<KnownIssue?> GetByIdAsync(string id, CancellationToken ct);
|
||||
Task<IReadOnlyList<KnownIssue>> SearchAsync(
|
||||
KnownIssueSearchRequest request, CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
**Example Known Issue:**
|
||||
```json
|
||||
{
|
||||
"id": "issue-log4j-test-code",
|
||||
"title": "Log4j in test dependencies",
|
||||
"description": "Log4j detected in test-scope dependencies is not exploitable in production",
|
||||
"applies_to": {
|
||||
"cve_pattern": "CVE-2021-44228",
|
||||
"scope": "test"
|
||||
},
|
||||
"recommended_action": "accept_risk",
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
### Response Tactics
|
||||
|
||||
Pre-defined response strategies for common situations:
|
||||
|
||||
```csharp
|
||||
public interface ITacticStore
|
||||
{
|
||||
Task<Tactic?> GetByIdAsync(string id, CancellationToken ct);
|
||||
Task<IReadOnlyList<Tactic>> GetMatchingTacticsAsync(
|
||||
TacticMatchRequest request, CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
**Example Tactic:**
|
||||
```json
|
||||
{
|
||||
"id": "tactic-quarantine-critical",
|
||||
"name": "Quarantine Critical Vulnerabilities",
|
||||
"trigger": {
|
||||
"severity": ["CRITICAL"],
|
||||
"reachability": ["REACHABLE", "UNKNOWN"]
|
||||
},
|
||||
"steps": [
|
||||
"Block deployment to production",
|
||||
"Notify security team",
|
||||
"Schedule remediation within 24h"
|
||||
],
|
||||
"automation": {
|
||||
"action": "quarantine",
|
||||
"notify_channel": "#security-alerts"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
### AdvisoryAI Integration
|
||||
|
||||
Register OpsMemory integration during startup:
|
||||
|
||||
```csharp
|
||||
services.AddAdvisoryAIOpsMemoryIntegration(options =>
|
||||
{
|
||||
options.Enabled = true;
|
||||
options.MaxSuggestions = 3;
|
||||
options.IncludeKnownIssues = true;
|
||||
options.IncludeTactics = true;
|
||||
});
|
||||
```
|
||||
|
||||
### Chat Flow Integration
|
||||
|
||||
The integration hooks into the chat pipeline:
|
||||
|
||||
1. **Pre-Prompt**: `AdvisoryAiPromptContextEnricher` adds OpsMemory context
|
||||
2. **Response**: AI references past decisions with object links
|
||||
3. **Post-Action**: `OpsMemoryChatProvider.RecordDecisionAsync` captures the decision
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Tuning Similarity Threshold
|
||||
|
||||
- **0.3-0.5**: Broader matches, may include less relevant decisions
|
||||
- **0.5-0.7**: Balanced - recommended starting point
|
||||
- **0.7+**: Strict matching, only very similar situations
|
||||
|
||||
### Recording Quality Decisions
|
||||
|
||||
For decisions to be useful for future suggestions:
|
||||
|
||||
1. **Include Context**: CVE ID, severity, package information
|
||||
2. **Clear Rationale**: Why this action was chosen
|
||||
3. **Track Outcomes**: Update with SUCCESS/FAILURE after implementation
|
||||
|
||||
### Managing Known Issues
|
||||
|
||||
- Review quarterly for relevance
|
||||
- Archive issues for CVEs that are fully remediated
|
||||
- Keep issue descriptions actionable
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
|
||||
Located in `src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Tests/Chat/Integration/`:
|
||||
|
||||
- `OpsMemoryChatProviderTests.cs` - Provider functionality
|
||||
- `AdvisoryAiPromptContextEnricherTests.cs` - Prompt enrichment
|
||||
|
||||
### Integration Tests
|
||||
|
||||
Located in `src/OpsMemory/__Tests/StellaOps.OpsMemory.Tests/Integration/`:
|
||||
|
||||
- `OpsMemoryChatProviderIntegrationTests.cs` - Full flow with PostgreSQL
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [OpsMemory Architecture](architecture.md) - Core OpsMemory design
|
||||
- [AdvisoryAI Architecture](../advisory-ai/architecture.md) - AI assistant design
|
||||
- [Decision Recording API](../../api/opsmemory.md) - REST API reference
|
||||
|
||||
---
|
||||
|
||||
_Last updated: 10-Jan-2026_
|
||||
Reference in New Issue
Block a user