groundswell 0.0.2 → 0.0.3

package/plan/001_d3bb02af4886/docs/research/P1P2/LRU_CACHE_RESEARCH_INDEX.md

@@ -1,424 +0,0 @@
-# LRU Cache Research for LLM Response Caching - Complete Index
-
-**Research Period:** 2025-12-08
-**Scope:** Best practices for implementing LRU caching in TypeScript/Node.js for LLM response caching
-**Target:** Production-grade implementation with lru-cache v10+, deterministic key generation, and semantic caching
-
----
-
-## Research Documents
-
-### 1. **LRU_CACHE_BEST_PRACTICES.md** (49 KB)
-**Comprehensive reference guide with in-depth technical details**
-
-- Executive summary of LRU caching for LLMs
-- lru-cache v10+ package deep dive:
-  - Core concepts and configuration options (max, maxSize, TTL)
-  - The `fetch()` method (recommended pattern)
-  - Size calculation best practices
-  - Production configuration recommendations
-- Deterministic JSON stringification:
-  - The problem and 3+ solutions
-  - `safe-stable-stringify` (recommended)
-  - `fast-json-stable-stringify` (performance alternative)
-  - `json-stringify-deterministic`
-  - Comparison table
-- SHA-256 hashing in Node.js:
-  - Built-in crypto module usage
-  - Performance characteristics (~20 MB/s)
-  - Stream-based hashing for large data
-  - HMAC patterns for cache validation
-- Zod schema hashing patterns:
-  - Schema fingerprinting techniques
-  - Deep traversal for nested schemas
-  - Versioning approach (recommended)
-  - Zod v4 improvements
-- LLM response caching architecture:
-  - Exact vs. semantic caching
-  - Hybrid approach (recommended)
-  - Multi-layer cache architecture
-  - Cache hit rate monitoring
-- Common pitfalls and solutions (8 detailed patterns)
-- Performance benchmarks with data
-- Complete production-ready implementation example
-- LangChain integration patterns
-- Version recommendations and compatibility
-
-**Use This For:** Understanding the full technical landscape, making architectural decisions, detailed implementation guidance.
-
----
-
-### 2. **LRU_CACHE_CODE_PATTERNS.md** (19 KB)
-**Quick reference with copy-paste ready code examples**
-
-- Installation guide
-- Quick start minimal example
-- Cache key generation patterns:
-  - Simple string hashing
-  - Object hashing (most common)
-  - Composite keys with prefix
-  - Semantic cache keys
-  - Versioned keys (auto-invalidate)
-- Configuration patterns:
-  - Development cache
-  - Production cache
-  - Memory-constrained cache
-  - High-throughput cache
-  - Persistent + in-memory hybrid
-- Usage patterns:
-  - Basic fetch (recommended)
-  - Conditional fetch
-  - Batch operations
-  - Stale-while-revalidate
-  - Cache warming
-- Testing patterns:
-  - Cache hit/miss testing
-  - Key generation testing
-  - Performance testing
-- Monitoring patterns:
-  - Basic metrics collection
-  - Periodic logging
-  - Alert on low hit rate
-  - Export metrics to JSON
-- Edge case handling:
-  - Large prompts
-  - Special characters
-  - Null/undefined values
-- Complete integration example with service class
-- All patterns include working TypeScript/JavaScript code
-
-**Use This For:** Copy-paste implementation, solving specific problems, quick integration.
-
----
-
-### 3. **LRU_CACHE_INTEGRATION_GUIDE.md** (18 KB)
-**Practical integration strategies and decision matrix**
-
-- Quick decision matrix:
-  - Exact vs. semantic vs. hybrid caching
-  - Deployment environment recommendations
-  - Package selection guide
-- Integration strategies:
-  - Strategy 1: Minimal Integration (MVP/simple cases)
-  - Strategy 2: Service-Based Integration (recommended for production)
-  - Strategy 3: Multi-Layer Caching (multi-node deployment)
-  - Each with pros/cons and implementation examples
-- Framework-specific integration:
-  - Groundswell workflow engine integration
-  - Plugin-based approach
-  - Decorator-based caching
-  - OpenAI integration example
-- Migration path (4-phase rollout):
-  - Phase 1: Evaluation (Week 1)
-  - Phase 2: Pilot (Week 2-3)
-  - Phase 3: Rollout (Week 4-8)
-  - Phase 4: Optimization (Week 8+)
-- Troubleshooting guide (6 common issues):
-  - Low cache hit rate diagnosis and solutions
-  - High memory usage fixes
-  - Stale data handling
-  - Test cache issues
-  - Race conditions
-  - Key length optimization
-- Performance tuning checklist (10 items)
-- Decision flowchart
-
-**Use This For:** Choosing integration strategy, planning rollout, troubleshooting issues, framework integration.
-
----
-
-## Key Findings Summary
-
-### Most Important Takeaways
-
-1. **Always use `safe-stable-stringify`** instead of native `JSON.stringify()`
-   - Native JSON.stringify has no key ordering guarantee
-   - Causes cache misses for identical logical inputs with different key order
-   - `safe-stable-stringify` is fastest deterministic option
-
-2. **Use the `fetch()` method** instead of manual get/set
-   - Automatically deduplicates concurrent requests
-   - Prevents race conditions
-   - Recommended pattern for all use cases
-
-3. **Configure at least one limit** (max, maxSize, or TTL)
-   - Prevents unbounded memory growth
-   - `max: 5000` for typical LLM cache
-   - `maxSize: 500MB` for production
-
-4. **Semantic caching achieves 60-70% hit rates**
-   - Exact caching: 30-40% hit rate
-   - Semantic caching: 60-70% hit rate
-   - Requires embedding model (~10-50ms latency)
-   - Consider hybrid approach for production
-
-5. **SHA-256 hashing via Node.js crypto is excellent**
-   - ~20 MB/s throughput (OpenSSL-backed)
-   - <0.05ms for typical LLM prompt
-   - Use for prompts > 100 characters
-
-6. **Cache key generation must be deterministic**
-   - Object key order matters
-   - Circular references must be handled
-   - Include version numbers for auto-invalidation
-
-7. **Zod schema hashing should use versioning** rather than dynamic hashing
-   - `_def` introspection is fragile (private API)
-   - Explicit version numbers are more stable
-   - Increment version = automatic cache invalidation
-
-8. **Hit rate > 30% is good baseline**
-   - 30-40% for exact caching (typical)
-   - Monitor and alert below threshold
-   - Use metrics to guide optimization
-
-### Performance Expectations
-
-| Metric | Value | Notes |
-|--------|-------|-------|
-| Cache hit lookup | <0.1ms | Negligible |
-| Deterministic stringify | <1ms | For typical prompt |
-| SHA-256 hashing | <0.05ms | Built-in crypto |
-| fetch() deduplication | ~0.0001ms | Minimal overhead |
-| Hit rate (exact) | 30-40% | Expected baseline |
-| Hit rate (semantic) | 60-70% | With embedding model |
-| Memory per 100 responses | 1-5 MB | Depends on response size |
-
-### Architecture Recommendation
-
-```
-Development:
-  LRUCache (max: 100, ttl: 1hr)
-
-Production (Single Node):
-  L1: LRUCache (max: 5000, maxSize: 500MB, ttl: 24hrs)
-
-Production (Multi-Node):
-  L1: LRUCache (max: 1000, maxSize: 100MB, ttl: 24hrs)
-  L2: Redis (shared across nodes)
-```
-
----
-
-## Quick Decision Guide
-
-### Q: Which package should I use?
-**A:** `safe-stable-stringify` (v2.4.0+) for deterministic key generation
-
-### Q: Exact or semantic caching?
-**A:** Start with exact caching (30-40% hit rate), add semantic if needed (60-70%)
-
-### Q: How should I generate cache keys?
-**A:** Use `safeStringify() + createHash('sha256') + digest('hex')`
-
-### Q: What cache size should I use?
-**A:** Start with `max: 5000` + `maxSize: 500MB` for production
-
-### Q: How long should I cache responses?
-**A:** 24 hours TTL with `updateAgeOnGet: true` for hot items
-
-### Q: Should I cache to Redis?
-**A:** Only if multi-node deployment; L1 in-memory is usually sufficient
-
-### Q: How do I monitor cache performance?
-**A:** Track hits/misses, hit rate, latency, memory usage
-
-### Q: What's the expected hit rate?
-**A:** 30-40% for exact caching, 60-70% for semantic
-
----
-
-## Implementation Checklist
-
-### Before Starting
-- [ ] Node.js 18+ installed
-- [ ] TypeScript configured (if using TS)
-- [ ] npm/yarn ready
-
-### Setup Phase
-- [ ] Install `lru-cache` v10+
-- [ ] Install `safe-stable-stringify`
-- [ ] Install `zod` (for validation)
-- [ ] Review architecture decision (Strategy 1/2/3)
-
-### Implementation Phase
-- [ ] Create cache service class
-- [ ] Implement deterministic key generation
-- [ ] Add to main LLM workflow
-- [ ] Implement metrics collection
-- [ ] Write tests (hit/miss scenarios)
-
-### Validation Phase
-- [ ] Test cache hit scenarios
-- [ ] Test cache miss scenarios
-- [ ] Monitor hit rate (target: >30%)
-- [ ] Check memory usage
-- [ ] Load test with concurrent requests
-- [ ] Verify no race conditions
-
-### Production Phase
-- [ ] Add monitoring/alerting
-- [ ] Set up metrics export
-- [ ] Document cache behavior
-- [ ] Create cache invalidation procedure
-- [ ] Plan upgrade path for schema changes
-
----
-
-## Document Map by Use Case
-
-### "I just need to get started quickly"
-1. Read: LRU_CACHE_CODE_PATTERNS.md → Quick Start section
-2. Copy: The minimal example
-3. Integrate: Into your LLM service
-4. Done
-
-### "I need to understand everything"
-1. Read: LRU_CACHE_BEST_PRACTICES.md (complete)
-2. Deep dive: Sections matching your questions
-3. Reference: Code patterns as needed
-4. Decide: Integration strategy from guide
-
-### "I need to plan integration"
-1. Read: LRU_CACHE_INTEGRATION_GUIDE.md → Decision Matrix
-2. Choose: One of 3 strategies
-3. Plan: Your rollout phases
-4. Execute: Using code patterns
-
-### "I'm having problems"
-1. Go to: LRU_CACHE_INTEGRATION_GUIDE.md → Troubleshooting
-2. Match: Your issue to diagnosis
-3. Apply: Recommended solution
-4. Test: Changes to verify fix
-
-### "I need production monitoring"
-1. Read: LRU_CACHE_CODE_PATTERNS.md → Monitoring Patterns
-2. Implement: Metrics collection
-3. Setup: Periodic logging
-4. Configure: Alerts for low hit rate
-
----
-
-## Version Recommendations
-
-### Minimum Versions (Works, Not Recommended)
-- lru-cache: v7+ (rewritten in TS)
-- safe-stable-stringify: v2.0+
-- Node.js: 14+
-
-### Recommended Versions (Best Balance)
-- lru-cache: v10.0.0+
-- safe-stable-stringify: v2.4.0+
-- zod: v3.20+
-- Node.js: 18 LTS
-
-### Cutting Edge (Latest Features)
-- lru-cache: v11.2.2+
-- safe-stable-stringify: v2.4.3+
-- zod: v3.22+
-- Node.js: 20+ LTS or 22+ current
-
----
-
-## Research Sources
-
-### Primary Sources
-- lru-cache npm: https://www.npmjs.com/package/lru-cache
-- Node.js Crypto API: https://nodejs.org/api/crypto.html
-- safe-stable-stringify: https://github.com/davidmarkclements/fast-safe-stringify
-- fast-json-stable-stringify: https://github.com/epoberezkin/fast-json-stable-stringify
-- Zod Documentation: https://zod.dev/
-
-### LLM Caching References
-- Helicone LLM Caching Guide: https://www.helicone.ai/blog/effective-llm-caching
-- IBM Prompt Caching: https://www.ibm.com/think/topics/prompt-caching
-- GPTCache Library: https://github.com/zilliztech/GPTCache
-- LangChain Caching: https://docs.langchain.com/modules/memory/
-
-### Performance Research
-- JavaScript Hashing Speed: https://lemire.me/blog/2025/01/11/javascript-hashing-speed-comparison-md5-versus-sha-256/
-- Node.js Performance: https://github.com/nodejs/performance/issues/136
-
----
-
-## Next Steps for Your Project
-
-1. **Short Term (This Week)**
-   - [ ] Review LRU_CACHE_BEST_PRACTICES.md
-   - [ ] Copy minimal example from CODE_PATTERNS
-   - [ ] Integrate into dev environment
-   - [ ] Measure baseline metrics
-
-2. **Medium Term (Next 2-4 Weeks)**
-   - [ ] Implement service-based caching (Strategy 2)
-   - [ ] Add monitoring and metrics
-   - [ ] Pilot in staging environment
-   - [ ] Tune configuration
-
-3. **Long Term (Month 2+)**
-   - [ ] Add semantic caching if needed
-   - [ ] Multi-layer caching if multi-node
-   - [ ] Comprehensive monitoring dashboard
-   - [ ] Auto-scaling policies
-
----
-
-## Questions? Common Issues?
-
-**Q: My cache keys don't match even for identical inputs**
-A: Use `safe-stable-stringify`, not `JSON.stringify`
-
-**Q: Cache hit rate is too low (< 20%)**
-A: Check for non-deterministic key generation or slight prompt variations
-
-**Q: Memory usage is growing unbounded**
-A: Ensure you configured `max` or `maxSize` limit
-
-**Q: Concurrent requests calling LLM multiple times**
-A: Use `cache.fetch()` method, not manual get/set
-
-**Q: Schema changes aren't invalidating cache**
-A: Use versioning in your cache key generation
-
-**Q: How do I test cache behavior?**
-A: See testing patterns in CODE_PATTERNS.md
-
----
-
-## Document Statistics
-
-| Document | Size | Sections | Code Examples | Tables |
-|----------|------|----------|---|--------|
-| Best Practices | 49 KB | 10 | 50+ | 8 |
-| Code Patterns | 19 KB | 7 | 30+ | 2 |
-| Integration Guide | 18 KB | 5 | 15+ | 3 |
-| **Total** | **86 KB** | **22** | **95+** | **13** |
-
----
-
-## Research Completion Summary
-
-This comprehensive research provides:
-
-✅ Complete API reference for lru-cache v10+
-✅ 3 deterministic stringification solutions with comparison
-✅ SHA-256 hashing best practices with performance data
-✅ Zod schema hashing patterns and anti-patterns
-✅ 8+ common pitfalls with solutions
-✅ 3 integration strategies with decision matrix
-✅ 95+ copy-paste ready code examples
-✅ Testing patterns for cache behavior
-✅ Monitoring and metrics patterns
-✅ Troubleshooting guide with 6 common issues
-✅ 4-phase migration/rollout plan
-✅ Performance benchmarks and expectations
-✅ Production recommendations
-✅ Complete working implementation examples
-
-**Ready for implementation!**
-
----
-
-**Index Version:** 1.0
-**Created:** 2025-12-08
-**Status:** Complete and Ready for Use

package/plan/001_d3bb02af4886/docs/research/P1P2/REFLECTION_INDEX.md

@@ -1,291 +0,0 @@
-# AI Reflection and Self-Correction: Complete Research Index
-
-## Overview
-
-This research package contains a comprehensive analysis of AI reflection and self-correction patterns in agent orchestration systems, based on 2024-2025 research and industry best practices.
-
-**Key Finding**: Reflection with external feedback (evidence-grounded) significantly improves LLM agent performance, with even minimal "try again" signals yielding 60%+ improvement rates.
-
----
-
-## Documents in This Package
-
-### 1. REFLECTION_RESEARCH_REPORT.md
-**Comprehensive research report covering all aspects of reflection patterns**
-
-- **Sections**:
-  - Core reflection concepts and types
-  - Research-backed approaches (Reflexion, LATS, SPOC)
-  - Prompt templates for different scenarios
-  - Retry limits and backoff strategies
-  - Introspection tools and security
-  - Best practices from LangChain, CrewAI, AutoGPT
-  - Common pitfalls (infinite loops, context bloat)
-  - Security considerations and patterns
-  - Monitoring and observability
-
-- **Use when**: You need detailed understanding of reflection theory and implementation
-
-- **Key sections for reference**:
-  - Section 1: Reflection patterns overview
-  - Section 2: Implementation patterns with code examples
-  - Section 3: Introspection tools specifications
-  - Section 5: Best practices from frameworks
-  - Section 10: Key recommendations
-
----
-
-### 2. reflection-implementation-guide.md
-**Practical code examples in TypeScript and Python**
-
-- **Contains**:
-  - Basic reflection loop (TypeScript)
-  - Reflexion pattern implementation (Python)
-  - Loop detection system (TypeScript)
-  - Context window management (Python)
-  - Security validation (TypeScript)
-  - Multi-level hierarchical reflection (Python)
-  - Metrics collection (TypeScript)
-  - Orchestration integration example
-
-- **Use when**: Building actual reflection systems; copy-paste ready code
-
-- **How to use**:
-  1. Select the language (Python or TypeScript)
-  2. Find the pattern matching your needs
-  3. Adapt the code to your LLM client
-  4. Integrate with your orchestration layer
-
-- **Code quality**: Production-ready with error handling and type safety
-
----
-
-### 3. reflection-quick-reference.md
-**Quick lookup guide for decision-making and configuration**
-
-- **Contains**:
-  - Decision tree for when to use reflection
-  - Approach selection matrix (by task type)
-  - Prompt templates (4 levels of complexity)
-  - Configuration profiles (Speed, Quality, Balanced, Safety-Critical)
-  - Stopping conditions checklist
-  - Common mistakes and fixes
-  - Performance benchmarks
-  - Token budget calculator
-  - Security checklist
-  - Integration checklist
-  - Troubleshooting guide
-
-- **Use when**: Making decisions about reflection implementation, configuring systems
-
-- **Most useful sections**:
-  - Decision tree at top (start here)
-  - Configuration profiles section
-  - Stopping conditions checklist
-  - Troubleshooting guide
-
----
-
-## Quick Navigation by Use Case
-
-### I'm Building a New Agent Orchestration System
-
-1. Read Decision Tree in `reflection-quick-reference.md`
-2. Read Approach Selection Matrix in `reflection-quick-reference.md`
-3. Read Section 1 (Concepts) in `REFLECTION_RESEARCH_REPORT.md`
-4. Review Configuration Profiles in `reflection-quick-reference.md`
-5. Read Sections 2-3 in `REFLECTION_RESEARCH_REPORT.md`
-6. Copy code from `reflection-implementation-guide.md`
-
----
-
-### I'm Implementing Reflection for a Specific Task Type
-
-**For Code Generation**: Use Reflexion approach with test feedback, max_attempts=2-3
-
-**For Writing/Content**: Use Self-Critique or Multi-Agent, max_attempts=2-3
-
-**For Analysis/Research**: Use Reflexion with evidence and fact-checking tools
-
-**For Planning**: Use basic self-critique, max_attempts=1-2, keep lightweight
-
----
-
-### I'm Worried About Infinite Loops
-
-1. See Section 5.1 in REFLECTION_RESEARCH_REPORT.md
-2. Copy loop detection code from reflection-implementation-guide.md
-3. Implement all 4 detection strategies
-4. Set hard max_attempts limit (never exceed 3)
-
----
-
-### I'm Building a Secure System
-
-1. Read Section 6 in REFLECTION_RESEARCH_REPORT.md
-2. Read Section 4 in reflection-implementation-guide.md
-3. Implement input sanitization
-4. Set up role-based access control for introspection
-5. Complete Security Checklist in reflection-quick-reference.md
-
----
-
-## Key Research Findings
-
-### Finding 1: External Feedback is Critical
-
-LLM self-correction works best WITH external feedback:
-- With external feedback (tests, facts, tool results): 80-95% effective
-- Without external feedback (self-evaluation only): 30-50% effective
-
-**Implication**: Always implement introspection/feedback mechanisms before reflection
-
-### Finding 2: Minimal Signals Can Help
-
-Even simple "Try again" signals improve performance by 60%+ across all LLMs.
-
-**Implication**: Even basic reflection is worth implementing
-
-### Finding 3: Self-Correction Blind Spot
-
-LLMs struggle to correct their own errors without external guidance. However, minimal triggers like "Wait" prompts can reduce blind spots by 89.3%.
-
-**Implication**: Use multi-agent reflection or external validation
-
-### Finding 4: Reflection Improves with Information Richness
-
-Reflection types ranked by effectiveness:
-1. Instructions + Explanation + Solution (best)
-2. Evidence-grounded with citations
-3. Advice/suggestions
-4. Keywords
-5. Retry (simplest)
-
-**Implication**: More detailed feedback yields better results
-
-### Finding 5: Three Reflection Cycles is the Sweet Spot
-
-After 2-3 cycles, improvement plateaus. Additional cycles add cost with minimal benefit.
-
-**Implication**: Set max_attempts = 2-3, not higher
-
----
-
-## Reflection Patterns Summary
-
-| Pattern | Best For | Complexity | Token Cost | Effectiveness | External Feedback |
-|---------|----------|-----------|-----------|---------------|--------------------|
-| Retry | Quick fixes | Low | Low | 60% | No |
-| Self-Critique | Content quality | Medium | Medium | 75% | No |
-| Reflexion | Accuracy-critical | Medium | Medium-High | 85% | Yes (required) |
-| Multi-Agent | Highest quality | High | High | 90% | Yes (recommended) |
-| Tool-Interactive | Problem-solving | Medium | Medium | 85% | Yes (tools) |
-| Hierarchical | Complex planning | High | High | 90% | Yes (rewards) |
-
----
-
-## Security Patterns
-
-| Attack Vector | Defense | Section |
-|--------------|---------|---------|
-| Prompt injection via feedback | Input sanitization, keyword filtering | Section 6.1 |
-| Credential exposure in history | Credential masking, filtering | Section 6.2 |
-| Unauthorized context access | RBAC, permission model | Section 3.2 |
-| Agent context escape | Isolation, execution boundaries | Section 6.3 |
-| Loop-based DoS | Loop detection, hard limits | Section 5.1 |
-
----
-
-## Introspection Tools Reference
-
-**For Agent Introspection**:
-- `get_agent_metadata` - Agent capabilities, status
-- `read_parent_context` - Parent goals, constraints
-- `read_sibling_context` - Other agents' work
-- `read_execution_history` - Own prior attempts
-- `read_workflow_state` - Overall progress
-- `check_resource_constraints` - Token/time remaining
-
-All defined in Section 3.1 of REFLECTION_RESEARCH_REPORT.md
-
----
-
-## Configuration Profiles Summary
-
-### Speed-Optimized
-- max_attempts: 1
-- reflection: minimal
-- Cost: lowest
-- Quality: baseline
-
-### Quality-Optimized
-- max_attempts: 3
-- reflection: evidence_grounded
-- Cost: high
-- Quality: best
-
-### Balanced (Recommended)
-- max_attempts: 2
-- reflection: self_critique
-- Cost: medium
-- Quality: good
-
-### Safety-Critical
-- max_attempts: 3
-- reflection: multi_agent
-- Cost: highest
-- Quality: highest
-- Security: strict
-
----
-
-## Common Questions Answered
-
-**Q: Should I use reflection for every task?**
-A: No. See Decision Tree. Skip reflection for time-critical or purely creative tasks.
-
-**Q: How many reflection cycles should I do?**
-A: Typically 2-3. More yields diminishing returns.
-
-**Q: How much will reflection cost me?**
-A: See Token Budget Calculator. Expect 2-5x token cost.
-
-**Q: Will I get infinite loops?**
-A: Possibly, if you don't implement loop detection (Section 5.1).
-
-**Q: What's the best reflection template?**
-A: Evidence-grounded (Template 2) works for most tasks.
-
-**Q: How do I know if reflection is helping?**
-A: Measure quality before/after (Section 9).
-
-**Q: Is reflection safe?**
-A: See Section 6 for security considerations.
-
----
-
-## Getting Started in 5 Minutes
-
-1. **Determine if reflection is right for you**: Decision Tree (quick-reference.md)
-2. **Choose your approach**: Approach Selection Matrix (quick-reference.md)
-3. **Pick a configuration**: Configuration Profiles (quick-reference.md)
-4. **Get the code**: reflection-implementation-guide.md
-5. **Understand the theory**: REFLECTION_RESEARCH_REPORT.md
-
----
-
-## Document Files
-
-All research files are in `./plan/P1P2/research/`:
-
-1. `REFLECTION_RESEARCH_REPORT.md` - Main comprehensive report (15,000+ words)
-2. `reflection-implementation-guide.md` - Code examples (Python/TypeScript)
-3. `reflection-quick-reference.md` - Decision matrices and checklists
-4. `REFLECTION_INDEX.md` - This file, navigation guide
-
----
-
-**Created**: December 2025
-**Version**: 1.0
-**Status**: Comprehensive research package ready for implementation
-