moai-adk 0.8.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-workflow-jit-docs/optimization.md

@@ -0,0 +1,286 @@
+---
+name: moai-workflow-jit-docs/optimization
+description: Performance optimization for JIT documentation, indexing, caching, and memory management
+---
+
+# JIT Documentation Optimization (v5.0.0)
+
+## Memory-Efficient Caching
+
+### 1. LRU Cache with Size Limits
+
+```typescript
+interface CacheEntry<T> {
+ value: T;
+ size: number;
+ timestamp: number;
+ accessCount: number;
+}
+
+class LRUDocumentCache<T> {
+ private cache: Map<string, CacheEntry<T>> = new Map();
+ private maxSize: number; // bytes
+ private currentSize: number = 0;
+
+ constructor(maxSizeInMB: number = 100) {
+ this.maxSize = maxSizeInMB * 1024 * 1024;
+ }
+
+ set(key: string, value: T, sizeEstimate: number) {
+ // Remove existing entry if present
+ if (this.cache.has(key)) {
+ const existing = this.cache.get(key)!;
+ this.currentSize -= existing.size;
+ }
+
+ // Evict LRU items if necessary
+ while (this.currentSize + sizeEstimate > this.maxSize && this.cache.size > 0) {
+ this.evictLRU();
+ }
+
+ // Add new entry
+ this.cache.set(key, {
+ value,
+ size: sizeEstimate,
+ timestamp: Date.now(),
+ accessCount: 0
+ });
+
+ this.currentSize += sizeEstimate;
+ }
+
+ get(key: string): T | undefined {
+ const entry = this.cache.get(key);
+ if (!entry) return undefined;
+
+ // Update access tracking
+ entry.accessCount++;
+ entry.timestamp = Date.now();
+
+ return entry.value;
+ }
+
+ private evictLRU() {
+ // Find least recently used item
+ let lruKey: string | null = null;
+ let lruScore = Infinity;
+
+ for (const [key, entry] of this.cache.entries()) {
+ const score = entry.timestamp + (entry.accessCount * 1000);
+ if (score < lruScore) {
+ lruScore = score;
+ lruKey = key;
+ }
+ }
+
+ if (lruKey) {
+ const removed = this.cache.get(lruKey)!;
+ this.currentSize -= removed.size;
+ this.cache.delete(lruKey);
+ }
+ }
+
+ getStats() {
+ return {
+ items: this.cache.size,
+ usedBytes: this.currentSize,
+ usedMB: (this.currentSize / 1024 / 1024).toFixed(2),
+ maxMB: (this.maxSize / 1024 / 1024).toFixed(2),
+ hitRate: this.calculateHitRate()
+ };
+ }
+}
+```
+
+## Index Optimization
+
+### 1. Incremental Indexing
+
+```typescript
+class IncrementalDocumentIndex {
+ private index: Map<string, Set<string>> = new Map(); // word -> docIds
+ private docHashes: Map<string, string> = new Map(); // docId -> contentHash
+
+ async indexDocuments(docs: DocumentContent[]): Promise<void> {
+ for (const doc of docs) {
+ const hash = this.calculateHash(doc.content);
+ const previousHash = this.docHashes.get(doc.id);
+
+ // Only reindex if content changed
+ if (previousHash !== hash) {
+ await this.indexDocument(doc);
+ this.docHashes.set(doc.id, hash);
+ }
+ }
+ }
+
+ private async indexDocument(doc: DocumentContent) {
+ // Extract and tokenize content
+ const tokens = this.tokenize(doc.content);
+
+ for (const token of new Set(tokens)) {
+ if (!this.index.has(token)) {
+ this.index.set(token, new Set());
+ }
+
+ this.index.get(token)!.add(doc.id);
+ }
+ }
+
+ async search(query: string): Promise<string[]> {
+ const tokens = this.tokenize(query);
+
+ // Find intersection of document sets
+ let results = this.index.get(tokens[0]) || new Set<string>();
+
+ for (let i = 1; i < tokens.length; i++) {
+ const tokenDocs = this.index.get(tokens[i]) || new Set();
+ results = new Set([...results].filter(id => tokenDocs.has(id)));
+ }
+
+ return Array.from(results);
+ }
+
+ private tokenize(text: string): string[] {
+ return text
+ .toLowerCase()
+ .match(/\b\w+\b/g) || [];
+ }
+
+ private calculateHash(content: string): string {
+ return require('crypto')
+ .createHash('sha256')
+ .update(content)
+ .digest('hex');
+ }
+}
+```
+
+## Compression and Storage
+
+### 1. Content Compression
+
+```typescript
+import zlib from 'zlib';
+import brotli from 'brotli';
+
+class CompressedDocumentStorage {
+ async compressDocument(doc: DocumentContent): Promise<CompressedDoc> {
+ const json = JSON.stringify(doc);
+
+ // Compress with brotli (better compression)
+ const compressed = await this.brotliCompress(json);
+
+ return {
+ id: doc.id,
+ compressed: compressed.toString('base64'),
+ originalSize: Buffer.byteLength(json),
+ compressedSize: compressed.length,
+ compressionRatio: (compressed.length / Buffer.byteLength(json) * 100).toFixed(1) + '%'
+ };
+ }
+
+ private async brotliCompress(data: string): Promise<Buffer> {
+ return new Promise((resolve, reject) => {
+ brotli.compress(Buffer.from(data), (err, output) => {
+ if (err) reject(err);
+ else resolve(output);
+ });
+ });
+ }
+
+ async decompressDocument(compressed: CompressedDoc): Promise<DocumentContent> {
+ const buffer = Buffer.from(compressed.compressed, 'base64');
+
+ return new Promise((resolve, reject) => {
+ brotli.decompress(buffer, (err, output) => {
+ if (err) reject(err);
+ else resolve(JSON.parse(output.toString()));
+ });
+ });
+ }
+}
+```
+
+## Performance Monitoring
+
+### 1. Load Time Metrics
+
+```typescript
+class DocumentLoadMetrics {
+ async trackLoadTime(docId: string, stage: 'fetch' | 'parse' | 'enhance' | 'render') {
+ const startTime = performance.now();
+
+ try {
+ const result = await this.loadDocument(docId);
+
+ const duration = performance.now() - startTime;
+
+ // Log metrics
+ logger.info('Document load', {
+ doc_id: docId,
+ stage,
+ duration_ms: duration,
+ cache_hit: this.wasCacheHit,
+ timestamp: new Date()
+ });
+
+ // Alert if slow
+ if (duration > 1000) {
+ metrics.increment('doc.load.slow', { stage });
+ logger.warn('Slow document load', { docId, stage, duration });
+ }
+
+ return result;
+ } catch (error) {
+ metrics.increment('doc.load.error', { stage });
+ logger.error('Document load failed', { docId, stage, error });
+ throw error;
+ }
+ }
+
+ // Performance budgets
+ validatePerformanceBudget(stage: string, duration: number): boolean {
+ const budgets = {
+ 'fetch': 500, // 500ms
+ 'parse': 200, // 200ms
+ 'enhance': 1000, // 1s
+ 'render': 300 // 300ms
+ };
+
+ const budget = budgets[stage as keyof typeof budgets];
+ return duration <= budget;
+ }
+}
+```
+
+### 2. Memory Usage Monitoring
+
+```typescript
+class MemoryMonitor {
+ trackMemoryUsage() {
+ const memUsage = process.memoryUsage();
+
+ metrics.gauge('memory.heapUsed', memUsage.heapUsed / 1024 / 1024); // MB
+ metrics.gauge('memory.heapTotal', memUsage.heapTotal / 1024 / 1024);
+ metrics.gauge('memory.external', memUsage.external / 1024 / 1024);
+
+ // Alert if heap usage > 80%
+ const heapUsagePercent = (memUsage.heapUsed / memUsage.heapTotal) * 100;
+ if (heapUsagePercent > 80) {
+ logger.warn('High memory usage', {
+ heapUsagePercent: heapUsagePercent.toFixed(1)
+ });
+
+ // Trigger garbage collection
+ if (global.gc) {
+ global.gc();
+ }
+ }
+ }
+}
+```
+
+---
+
+Version: 5.0.0 | Last Updated: 2025-11-22 | Enterprise Ready:

moai_adk/templates/.claude/skills/moai-workflow-jit-docs/reference.md

@@ -0,0 +1,307 @@
+# moai-workflow-jit-docs Reference
+
+## API Reference
+
+### Intent Analysis API
+
+Intent Detection Functions:
+- `analyze_user_intent(user_input, context)`: Determine documentation needs
+- `extract_technologies(user_input)`: Identify technology keywords
+- `extract_domains(user_input)`: Identify domain keywords
+- `classify_question(user_input)`: Categorize question type
+- `assess_complexity(user_input)`: Evaluate question complexity
+- `determine_urgency(user_input)`: Assess information urgency
+
+Intent Structure:
+```python
+{
+    "technologies": ["FastAPI", "JWT"],
+    "domains": ["authentication", "security"],
+    "question_type": "implementation",
+    "complexity": "medium",
+    "urgency": "standard"
+}
+```
+
+Question Types:
+- `implementation`: How to build/create something
+- `troubleshooting`: How to fix issues
+- `conceptual`: Understanding concepts
+- `best_practices`: Recommended approaches
+- `comparison`: Evaluating options
+
+### Source Prioritization API
+
+Priority Functions:
+- `prioritize_documentation_sources(intent)`: Rank sources by relevance
+- `has_local_docs()`: Check for project documentation
+- `get_official_docs(technology)`: Get official documentation URL
+- `calculate_relevance(content, context)`: Score content relevance
+
+Source Types and Weights:
+- `local`: Project documentation (priority 1.0)
+- `official`: Official documentation (priority 0.9)
+- `web`: Real-time web research (priority 0.8)
+- `community`: Community resources (priority 0.7)
+
+### Caching API
+
+DocumentationCache Class:
+- `get(key, context)`: Retrieve cached documentation
+- `store(key, content, relevance_score)`: Cache with relevance
+- `remove(key)`: Remove from cache
+- `is_relevant(key, context)`: Check current relevance
+- `update_access_time(key)`: Track access patterns
+
+Cache Levels:
+- `session`: Current session only
+- `project`: Project-specific persistent cache
+- `global`: Cross-project shared cache
+
+### Quality Assessment API
+
+Quality Functions:
+- `assess_documentation_quality(content)`: Evaluate content quality
+- `is_official_source(content)`: Check source authority
+- `is_recent(content, months)`: Check content age
+- `has_examples(content)`: Check for code examples
+- `has_explanations(content)`: Check for explanations
+
+Quality Scoring:
+- Authority: 30% (official sources preferred)
+- Recency: 25% (recent content preferred)
+- Completeness: 25% (examples and explanations)
+- Relevance: 20% (match to user context)
+
+---
+
+## Configuration Options
+
+### Source Configuration
+
+Local Documentation Paths:
+- `.moai/docs/`: Project-specific documentation
+- `.moai/specs/`: Requirements and specifications
+- `README.md`: General project information
+- `CHANGELOG.md`: Version history
+- `docs/`: Comprehensive documentation directory
+
+Official Documentation URLs:
+```python
+official_docs = {
+    "FastAPI": "https://fastapi.tiangolo.com/",
+    "React": "https://react.dev/",
+    "PostgreSQL": "https://www.postgresql.org/docs/",
+    "Docker": "https://docs.docker.com/",
+    "Kubernetes": "https://kubernetes.io/docs/",
+    "TypeScript": "https://www.typescriptlang.org/docs/"
+}
+```
+
+### Cache Configuration
+
+Cache Settings:
+- `cache_duration_days`: How long to keep cached content
+- `max_cache_size_mb`: Maximum cache size
+- `auto_cleanup_enabled`: Enable automatic cleanup
+- `relevance_threshold`: Minimum relevance to cache
+
+Eviction Policies:
+- Remove content older than 30 days
+- Keep high-authority sources longer
+- Prioritize frequently accessed content
+- Remove low-relevance content first
+
+### Intent Detection Settings
+
+Technology Keywords:
+- Frameworks: FastAPI, React, Vue, Django, Flask
+- Languages: Python, TypeScript, JavaScript, Go, Rust
+- Databases: PostgreSQL, MongoDB, Redis, MySQL
+- DevOps: Docker, Kubernetes, Terraform, AWS
+
+Domain Keywords:
+- Security: authentication, authorization, encryption
+- Performance: optimization, caching, scaling
+- Database: queries, migrations, indexing
+- API: endpoints, REST, GraphQL
+
+---
+
+## Integration Patterns
+
+### Question-Based Loading
+
+Trigger Pattern:
+1. User asks specific question
+2. Intent analysis identifies needs
+3. Sources prioritized by relevance
+4. Documentation loaded and cached
+5. Enhanced response generated
+
+Example Flow:
+```
+User: "How do I implement JWT in FastAPI?"
+
+1. Intent: {technologies: [FastAPI, JWT], domains: [auth]}
+2. Sources: [FastAPI docs, JWT best practices]
+3. Load: Official FastAPI security guide
+4. Cache: Store with high relevance score
+5. Response: Comprehensive JWT implementation guide
+```
+
+### Technology-Specific Loading
+
+Trigger Pattern:
+1. Technology keyword detected
+2. Official documentation identified
+3. Relevant sections loaded
+4. Community resources added
+5. Latest updates checked
+
+Technology Coverage:
+- Language-specific patterns and idioms
+- Framework configuration and usage
+- Library integration examples
+- Version-specific changes
+
+### Domain-Specific Loading
+
+Trigger Pattern:
+1. Domain keyword detected
+2. Domain expertise documentation loaded
+3. Best practices identified
+4. Common patterns extracted
+5. Troubleshooting guides added
+
+Domain Coverage:
+- Authentication and authorization patterns
+- Database optimization strategies
+- API design best practices
+- Performance tuning guides
+
+### Real-Time Web Research
+
+Trigger Pattern:
+1. Latest information needed
+2. WebSearch executed with current year
+3. Results quality-assessed
+4. High-quality content extracted
+5. Cached for future use
+
+Search Optimization:
+```python
+WebSearch(f"{query} best practices 2024 2025")
+```
+
+---
+
+## Troubleshooting
+
+### Documentation Not Loading
+
+Symptoms: Skill not activating, missing context
+
+Solutions:
+1. Verify intent detection triggered
+2. Check local documentation paths exist
+3. Confirm network connectivity for web sources
+4. Review cache for stale entries
+
+### Low Quality Results
+
+Symptoms: Irrelevant or outdated documentation
+
+Solutions:
+1. Adjust relevance threshold higher
+2. Clear cache to force fresh fetch
+3. Prioritize official sources
+4. Add year filter to web searches
+
+### Cache Issues
+
+Symptoms: Stale content, cache bloat
+
+Solutions:
+1. Clear session cache: Reset current session
+2. Clear project cache: Remove project-specific cache
+3. Reduce cache duration
+4. Lower max cache size
+
+### Intent Misdetection
+
+Symptoms: Wrong documentation loaded
+
+Solutions:
+1. User clarification requested
+2. Refine keyword extraction
+3. Adjust domain mappings
+4. Add technology aliases
+
+### Network Failures
+
+Symptoms: Web sources unavailable
+
+Solutions:
+1. Fall back to cached content
+2. Use local documentation
+3. Provide partial results with notice
+4. Retry with backoff
+
+---
+
+## External Resources
+
+### Documentation Sources
+
+Official Sources by Category:
+- Languages: Official language documentation
+- Frameworks: Framework official guides
+- Databases: Database documentation
+- Cloud: Provider documentation
+
+Community Resources:
+- Stack Overflow (highly-voted answers)
+- GitHub Discussions (official projects)
+- Dev.to (tutorial articles)
+- Medium (technical deep-dives)
+
+### Quality Indicators
+
+High-Quality Sources:
+- Official documentation (docs.*.com, *.io/docs)
+- GitHub repositories with high stars
+- Conference talks and official blogs
+- Books from recognized publishers
+
+Low-Quality Sources:
+- Outdated content (older than 2 years)
+- No code examples
+- Missing author attribution
+- Scraped or aggregated content
+
+### Related Skills
+
+- `moai-docs-generation`: Generate documentation
+- `moai-workflow-docs`: Documentation workflows
+- `moai-library-nextra`: Nextra documentation sites
+- `moai-foundation-context`: Token budget management
+
+### Performance Optimization
+
+Loading Strategies:
+- Lazy loading: Load only when needed
+- Batch processing: Combine related queries
+- Progressive disclosure: Load detail on demand
+- Intelligent caching: Predict future needs
+
+Metrics:
+- Cache hit rate target: Greater than 70%
+- Average load time: Less than 2 seconds
+- Relevance score threshold: 0.7 minimum
+- Quality score threshold: 0.6 minimum
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-06