@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/website/content/docs/use-cases/00-index.md

@@ -0,0 +1,395 @@
+# OSSA Use Case Gallery
+
+Production-ready examples demonstrating real-world OSSA agent implementations across enterprise, DevOps, customer experience, and research domains.
+
+## Overview
+
+Each use case provides:
+- **Problem statement** - Real-world challenge being solved
+- **Architecture diagrams** - Complete system design (Mermaid)
+- **OSSA manifests** - Production-ready YAML specifications
+- **Implementation code** - TypeScript or Python reference implementations
+- **Deployment instructions** - Kubernetes/Docker deployment guides
+- **Cost management** - Budget controls and optimization strategies
+- **Production checklist** - Security, monitoring, and operational requirements
+
+## Use Cases
+
+### 1. Enterprise Financial Compliance Agent
+
+**Domain**: Financial Services, Healthcare, Government
+**Problem**: Continuous compliance monitoring across SOC2, PCI-DSS, GDPR
+**Technology**: Kubernetes-native, cost-limited, audit-logged
+
+[View Full Use Case →](./enterprise-compliance.md)
+
+**Highlights**:
+- ✅ Automated compliance scanning with 7-year audit retention
+- ✅ Multi-framework validation (PCI-DSS, SOC2, GDPR)
+- ✅ Cost controls with $50/day budget enforcement
+- ✅ Auto-remediation with approval workflows
+- ✅ Real-time alerting for critical violations
+
+**Key Features**:
+```yaml
+Capabilities:
+  - Infrastructure scanning (Kubernetes, databases, storage)
+  - Policy validation with evidence collection
+  - Audit report generation (PDF, HTML, JSON, CSV)
+  - Auto-remediation with rollback support
+
+Policies:
+  - Cost limit: $50/day with 80% alert threshold
+  - Audit retention: 2555 days (7 years)
+  - Encryption: Required at rest and in transit
+  - Auto-remediation: Disabled by default, requires approval
+```
+
+**Use When**:
+- Financial institutions requiring continuous compliance
+- Healthcare organizations managing HIPAA/PHI data
+- Government agencies with FedRAMP requirements
+- Any organization with strict audit requirements
+
+---
+
+### 2. CI/CD Automated Code Review Agent
+
+**Domain**: Software Engineering, DevOps
+**Problem**: PR review bottlenecks, inconsistent quality, missed bugs
+**Technology**: GitHub Actions, GitLab CI, AI-powered analysis
+
+[View Full Use Case →](./cicd-code-review.md)
+
+**Highlights**:
+- ✅ Automated PR reviews in minutes (vs. hours/days)
+- ✅ Multi-language support (TypeScript, Python, Go, Rust, Java)
+- ✅ AI-powered code analysis with GPT-4
+- ✅ Security vulnerability scanning (Snyk, Trivy)
+- ✅ Auto-fix for trivial issues (formatting, imports)
+
+**Key Features**:
+```yaml
+Capabilities:
+  - Comprehensive PR review (linting + testing + security)
+  - Multi-language linters (ESLint, Pylint, golint, rustfmt)
+  - Test execution with coverage tracking
+  - Security vulnerability scanning
+  - Complexity analysis (cyclomatic, cognitive)
+  - AI code quality assessment
+
+Quality Gates:
+  - Min test coverage: 80%
+  - Max cyclomatic complexity: 10
+  - Block on: Critical security issues, failed tests
+  - Auto-approval: Disabled (requires human review)
+```
+
+**Use When**:
+- Development teams with high PR volume
+- Organizations enforcing coding standards
+- Teams needing 24/7 code review coverage
+- Projects requiring security scanning in CI/CD
+
+---
+
+### 3. Customer Support Ticket Triage Agent
+
+**Domain**: Customer Success, SaaS, E-commerce
+**Problem**: Slow response times, misrouted tickets, inconsistent prioritization
+**Technology**: Zendesk/Intercom integration, vector search, sentiment analysis
+
+[View Full Use Case →](./customer-support.md)
+
+**Highlights**:
+- ✅ Instant ticket triage (seconds vs. hours)
+- ✅ Intelligent routing to correct team/agent
+- ✅ Knowledge base search with semantic matching
+- ✅ Sentiment analysis with angry customer detection
+- ✅ Auto-reply for high-confidence cases
+
+**Key Features**:
+```yaml
+Capabilities:
+  - Ticket classification (8 categories)
+  - Priority scoring (critical, high, normal, low)
+  - Team routing (billing, engineering, sales, success)
+  - Sentiment analysis with emotion detection
+  - Knowledge base search (vector embeddings)
+  - Response generation (AI-powered)
+  - Escalation triggers (VIP, angry, complex)
+
+SLA Targets:
+  - Critical: 15 minutes
+  - High: 2 hours
+  - Normal: 24 hours
+  - Low: 48 hours
+
+Auto-Reply:
+  - Enabled: Yes (95% confidence threshold)
+  - Excluded: Enterprise tier, angry customers, complaints
+  - Human review: 10% sample rate
+```
+
+**Use When**:
+- Support teams overwhelmed with ticket volume
+- Organizations with tiered customer bases (free/pro/enterprise)
+- Companies needing 24/7 support coverage
+- Teams with extensive knowledge bases to leverage
+
+---
+
+### 4. Research Multi-Agent Debate System
+
+**Domain**: Academic Research, R&D, Scientific Publishing
+**Problem**: Single-reviewer bias, shallow analysis, scalability limits
+**Technology**: Multi-agent orchestration, adversarial collaboration, Claude/GPT-4
+
+[View Full Use Case →](./research-multi-agent.md)
+
+**Highlights**:
+- ✅ Multi-perspective analysis (5 specialist agents)
+- ✅ Structured debate across 4 rounds
+- ✅ Evidence-based argumentation
+- ✅ Literature search integration (arXiv, PubMed)
+- ✅ Reproducibility validation (code/data checks)
+
+**Key Features**:
+```yaml
+Specialist Agents:
+  - Methodology Critic: Evaluates experimental rigor
+  - Novelty Assessor: Compares against existing literature
+  - Reproducibility Checker: Validates code/data availability
+  - Impact Evaluator: Assesses potential impact
+  - Ethics Reviewer: Checks ethical considerations
+
+Debate Process:
+  - Round 1: Initial positions (independent reviews)
+  - Round 2: Rebuttals (challenge other perspectives)
+  - Round 3: Evidence gathering (support arguments)
+  - Round 4: Consensus building (final positions)
+
+Outputs:
+  - Multi-dimensional scores (methodology, novelty, reproducibility, impact, ethics)
+  - Recommendation (strong accept → strong reject)
+  - Confidence score (based on agent agreement)
+  - Debate transcript (full argumentation history)
+  - Executive summary (strengths, weaknesses, key findings)
+```
+
+**Use When**:
+- Academic conferences needing scalable peer review
+- Research teams reviewing large bodies of literature
+- Organizations conducting systematic literature reviews
+- Journals requiring multi-perspective analysis
+
+---
+
+## Architecture Patterns
+
+### Common Patterns Across Use Cases
+
+1. **Cost Management**
+   - All agents include daily/monthly budget limits
+   - Alert thresholds (typically 80-85%)
+   - Automatic throttling when approaching limits
+   - Per-operation cost tracking
+
+2. **Security Controls**
+   - Secrets managed via environment variables or Vault
+   - Mutual TLS for inter-agent communication
+   - RBAC for capability access
+   - Audit logging with encryption at rest
+
+3. **Monitoring & Observability**
+   - Prometheus metrics export
+   - Jaeger distributed tracing
+   - Structured JSON logging
+   - Health/readiness checks
+   - Custom business metrics
+
+4. **Integration Patterns**
+   - Webhook-based triggers (GitHub, GitLab, Zendesk)
+   - REST/gRPC APIs for synchronous operations
+   - Agent-to-agent communication (multi-agent systems)
+   - External service integration (AI APIs, databases, search)
+
+## Technology Stack
+
+### AI/LLM Providers
+- **OpenAI**: GPT-4 Turbo, text-embedding-ada-002
+- **Anthropic**: Claude 3.5 Sonnet
+- **Vector Databases**: Pinecone, Weaviate
+
+### Deployment Platforms
+- **Kubernetes**: Production orchestration
+- **Docker**: Containerization
+- **CI/CD**: GitHub Actions, GitLab CI
+
+### Integrations
+- **Version Control**: GitHub, GitLab
+- **Support**: Zendesk, Intercom
+- **Communication**: Slack, Email, SMS
+- **Security**: Snyk, Trivy, OWASP Dependency-Check
+- **Research**: arXiv, PubMed
+
+## Cost Comparison
+
+| Use Case | Estimated Monthly Cost | Per-Operation Cost | Optimization Strategy |
+|----------|----------------------|-------------------|----------------------|
+| **Compliance** | $500-1,500 | $0.10-0.50/scan | Scheduled scans, skip unchanged resources |
+| **Code Review** | $200-800 | $0.05-0.20/PR | Cache linter results, parallel analysis |
+| **Support Triage** | $300-1,000 | $0.02-0.10/ticket | Vector DB caching, batch processing |
+| **Research Review** | $500-2,000 | $5-10/paper | Reuse literature searches, agent pooling |
+
+## Getting Started
+
+### Prerequisites
+
+```bash
+# Install OSSA CLI
+npm install -g @bluefly/openstandardagents
+
+# Verify installation
+ossa --version
+```
+
+### Quick Start
+
+```bash
+# 1. Choose a use case
+cd website/content/docs/use-cases/
+
+# 2. Review the manifest
+cat enterprise-compliance.md  # or other use case
+
+# 3. Extract manifest to file
+# (Manifests are embedded in markdown)
+
+# 4. Validate manifest
+ossa validate my-agent.ossa.yaml
+
+# 5. Deploy to Kubernetes
+kubectl apply -f deployment.yaml
+
+# 6. Verify deployment
+kubectl get pods -n <namespace>
+kubectl logs -n <namespace> <pod-name>
+```
+
+### Customization Guide
+
+Each use case is designed to be customized:
+
+1. **Adjust cost limits** in `policies.cost_management`
+2. **Modify quality gates** in `policies.quality_gates`
+3. **Configure integrations** in `integration` section
+4. **Add custom capabilities** in `capabilities`
+5. **Update resource limits** in `runtime.resources`
+
+## Production Deployment
+
+### Security Checklist
+
+- [ ] Secrets stored in Vault or Kubernetes secrets (never in config)
+- [ ] Mutual TLS configured for all network communication
+- [ ] RBAC policies restricted to minimum required permissions
+- [ ] Network policies enforcing least-privilege access
+- [ ] Audit logging enabled with encryption at rest
+- [ ] Pod security standards enforced (restricted profile)
+- [ ] Image scanning integrated into CI/CD
+- [ ] Regular security audits scheduled
+
+### Operational Checklist
+
+- [ ] Monitoring dashboards configured (Grafana)
+- [ ] Alerting rules defined (Prometheus Alertmanager)
+- [ ] Cost tracking enabled and reviewed weekly
+- [ ] Backup/disaster recovery plan tested
+- [ ] Runbooks created for common issues
+- [ ] On-call rotation established
+- [ ] SLA targets defined and monitored
+- [ ] Performance baselines established
+
+### Compliance Checklist
+
+- [ ] Data retention policies configured
+- [ ] PII handling documented and compliant
+- [ ] Audit trails comprehensive and immutable
+- [ ] Access controls reviewed quarterly
+- [ ] Third-party vendor assessments completed
+- [ ] Incident response plan documented
+- [ ] Compliance reports generated automatically
+- [ ] Regular compliance audits scheduled
+
+## Troubleshooting
+
+### Common Issues
+
+**High Cost Overruns**
+```bash
+# Check cost metrics
+kubectl exec -it <pod> -- curl localhost:9090/metrics | grep cost
+
+# Review cost policies
+ossa validate --check-costs manifest.yaml
+
+# Adjust budget limits
+# Edit manifest: policies.cost_management.budget.daily_limit_usd
+```
+
+**Agent Communication Failures**
+```bash
+# Check agent registry
+kubectl get services -n <namespace>
+
+# Verify DNS resolution
+kubectl exec -it <pod> -- nslookup <service-name>
+
+# Check logs
+kubectl logs -n <namespace> <pod-name> --tail=100
+```
+
+**Performance Degradation**
+```bash
+# Check resource usage
+kubectl top pods -n <namespace>
+
+# Review metrics
+curl localhost:9090/metrics | grep duration_seconds
+
+# Scale replicas
+kubectl scale deployment <name> --replicas=5
+```
+
+## Contributing
+
+We welcome contributions! To add a new use case:
+
+1. Follow the template structure (see existing use cases)
+2. Include complete OSSA manifest
+3. Provide working implementation (TypeScript or Python)
+4. Add architecture diagram (Mermaid)
+5. Include deployment instructions
+6. Document cost estimates
+7. Add production checklist
+
+Submit PRs to: https://github.com/blueflyio/openstandardagents/pulls
+
+## Support & Resources
+
+- **Documentation**: https://openstandardagents.org/docs
+- **Specification**: https://github.com/blueflyio/openstandardagents/spec
+- **Examples**: https://github.com/blueflyio/openstandardagents/examples
+- **Community**: https://github.com/blueflyio/openstandardagents/discussions
+- **Issues**: https://github.com/blueflyio/openstandardagents/issues
+
+## License
+
+All use cases are provided under Apache 2.0 license. Implementation code may be used freely in commercial and open-source projects.
+
+---
+
+**Last Updated**: November 2024
+**OSSA Version**: v0.2.x
+**Status**: Production Ready