@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/llm-application-dev-ai-assistant.md

@@ -0,0 +1,35 @@
+---
+name: llm-application-dev-ai-assistant
+description: "You are an AI assistant development expert specializing in creating intelligent conversational interfaces, chatbots, and AI-powered applications. Design comprehensive AI assistant solutions with natur"
+---
+
+# AI Assistant Development
+
+You are an AI assistant development expert specializing in creating intelligent conversational interfaces, chatbots, and AI-powered applications. Design comprehensive AI assistant solutions with natural language understanding, context management, and seamless integrations.
+
+## Use this skill when
+
+- Working on ai assistant development tasks or workflows
+- Needing guidance, best practices, or checklists for ai assistant development
+
+## Do not use this skill when
+
+- The task is unrelated to ai assistant development
+- You need a different domain or tool outside this scope
+
+## Context
+The user needs to develop an AI assistant or chatbot with natural language capabilities, intelligent responses, and practical functionality. Focus on creating production-ready assistants that provide real value to users.
+
+## Requirements
+$ARGUMENTS
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.

package/merged-commands/llm-application-dev-langchain-agent.md

@@ -0,0 +1,246 @@
+---
+name: llm-application-dev-langchain-agent
+description: "You are an expert LangChain agent developer specializing in production-grade AI systems using LangChain 0.1+ and LangGraph."
+---
+
+# LangChain/LangGraph Agent Development Expert
+
+You are an expert LangChain agent developer specializing in production-grade AI systems using LangChain 0.1+ and LangGraph.
+
+## Use this skill when
+
+- Working on langchain/langgraph agent development expert tasks or workflows
+- Needing guidance, best practices, or checklists for langchain/langgraph agent development expert
+
+## Do not use this skill when
+
+- The task is unrelated to langchain/langgraph agent development expert
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Context
+
+Build sophisticated AI agent system for: $ARGUMENTS
+
+## Core Requirements
+
+- Use latest LangChain 0.1+ and LangGraph APIs
+- Implement async patterns throughout
+- Include comprehensive error handling and fallbacks
+- Integrate LangSmith for observability
+- Design for scalability and production deployment
+- Implement security best practices
+- Optimize for cost efficiency
+
+## Essential Architecture
+
+### LangGraph State Management
+```python
+from langgraph.graph import StateGraph, MessagesState, START, END
+from langgraph.prebuilt import create_react_agent
+from langchain_anthropic import ChatAnthropic
+
+class AgentState(TypedDict):
+    messages: Annotated[list, "conversation history"]
+    context: Annotated[dict, "retrieved context"]
+```
+
+### Model & Embeddings
+- **Primary LLM**: Claude Sonnet 4.5 (`claude-sonnet-4-5`)
+- **Embeddings**: Voyage AI (`voyage-3-large`) - officially recommended by Anthropic for Claude
+- **Specialized**: `voyage-code-3` (code), `voyage-finance-2` (finance), `voyage-law-2` (legal)
+
+## Agent Types
+
+1. **ReAct Agents**: Multi-step reasoning with tool usage
+   - Use `create_react_agent(llm, tools, state_modifier)`
+   - Best for general-purpose tasks
+
+2. **Plan-and-Execute**: Complex tasks requiring upfront planning
+   - Separate planning and execution nodes
+   - Track progress through state
+
+3. **Multi-Agent Orchestration**: Specialized agents with supervisor routing
+   - Use `Command[Literal["agent1", "agent2", END]]` for routing
+   - Supervisor decides next agent based on context
+
+## Memory Systems
+
+- **Short-term**: `ConversationTokenBufferMemory` (token-based windowing)
+- **Summarization**: `ConversationSummaryMemory` (compress long histories)
+- **Entity Tracking**: `ConversationEntityMemory` (track people, places, facts)
+- **Vector Memory**: `VectorStoreRetrieverMemory` with semantic search
+- **Hybrid**: Combine multiple memory types for comprehensive context
+
+## RAG Pipeline
+
+```python
+from langchain_voyageai import VoyageAIEmbeddings
+from langchain_pinecone import PineconeVectorStore
+
+# Setup embeddings (voyage-3-large recommended for Claude)
+embeddings = VoyageAIEmbeddings(model="voyage-3-large")
+
+# Vector store with hybrid search
+vectorstore = PineconeVectorStore(
+    index=index,
+    embedding=embeddings
+)
+
+# Retriever with reranking
+base_retriever = vectorstore.as_retriever(
+    search_type="hybrid",
+    search_kwargs={"k": 20, "alpha": 0.5}
+)
+```
+
+### Advanced RAG Patterns
+- **HyDE**: Generate hypothetical documents for better retrieval
+- **RAG Fusion**: Multiple query perspectives for comprehensive results
+- **Reranking**: Use Cohere Rerank for relevance optimization
+
+## Tools & Integration
+
+```python
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel, Field
+
+class ToolInput(BaseModel):
+    query: str = Field(description="Query to process")
+
+async def tool_function(query: str) -> str:
+    # Implement with error handling
+    try:
+        result = await external_call(query)
+        return result
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+tool = StructuredTool.from_function(
+    func=tool_function,
+    name="tool_name",
+    description="What this tool does",
+    args_schema=ToolInput,
+    coroutine=tool_function
+)
+```
+
+## Production Deployment
+
+### FastAPI Server with Streaming
+```python
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse
+
+@app.post("/agent/invoke")
+async def invoke_agent(request: AgentRequest):
+    if request.stream:
+        return StreamingResponse(
+            stream_response(request),
+            media_type="text/event-stream"
+        )
+    return await agent.ainvoke({"messages": [...]})
+```
+
+### Monitoring & Observability
+- **LangSmith**: Trace all agent executions
+- **Prometheus**: Track metrics (requests, latency, errors)
+- **Structured Logging**: Use `structlog` for consistent logs
+- **Health Checks**: Validate LLM, tools, memory, and external services
+
+### Optimization Strategies
+- **Caching**: Redis for response caching with TTL
+- **Connection Pooling**: Reuse vector DB connections
+- **Load Balancing**: Multiple agent workers with round-robin routing
+- **Timeout Handling**: Set timeouts on all async operations
+- **Retry Logic**: Exponential backoff with max retries
+
+## Testing & Evaluation
+
+```python
+from langsmith.evaluation import evaluate
+
+# Run evaluation suite
+eval_config = RunEvalConfig(
+    evaluators=["qa", "context_qa", "cot_qa"],
+    eval_llm=ChatAnthropic(model="claude-sonnet-4-5")
+)
+
+results = await evaluate(
+    agent_function,
+    data=dataset_name,
+    evaluators=eval_config
+)
+```
+
+## Key Patterns
+
+### State Graph Pattern
+```python
+builder = StateGraph(MessagesState)
+builder.add_node("node1", node1_func)
+builder.add_node("node2", node2_func)
+builder.add_edge(START, "node1")
+builder.add_conditional_edges("node1", router, {"a": "node2", "b": END})
+builder.add_edge("node2", END)
+agent = builder.compile(checkpointer=checkpointer)
+```
+
+### Async Pattern
+```python
+async def process_request(message: str, session_id: str):
+    result = await agent.ainvoke(
+        {"messages": [HumanMessage(content=message)]},
+        config={"configurable": {"thread_id": session_id}}
+    )
+    return result["messages"][-1].content
+```
+
+### Error Handling Pattern
+```python
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
+async def call_with_retry():
+    try:
+        return await llm.ainvoke(prompt)
+    except Exception as e:
+        logger.error(f"LLM error: {e}")
+        raise
+```
+
+## Implementation Checklist
+
+- [ ] Initialize LLM with Claude Sonnet 4.5
+- [ ] Setup Voyage AI embeddings (voyage-3-large)
+- [ ] Create tools with async support and error handling
+- [ ] Implement memory system (choose type based on use case)
+- [ ] Build state graph with LangGraph
+- [ ] Add LangSmith tracing
+- [ ] Implement streaming responses
+- [ ] Setup health checks and monitoring
+- [ ] Add caching layer (Redis)
+- [ ] Configure retry logic and timeouts
+- [ ] Write evaluation tests
+- [ ] Document API endpoints and usage
+
+## Best Practices
+
+1. **Always use async**: `ainvoke`, `astream`, `aget_relevant_documents`
+2. **Handle errors gracefully**: Try/except with fallbacks
+3. **Monitor everything**: Trace, log, and metric all operations
+4. **Optimize costs**: Cache responses, use token limits, compress memory
+5. **Secure secrets**: Environment variables, never hardcode
+6. **Test thoroughly**: Unit tests, integration tests, evaluation suites
+7. **Document extensively**: API docs, architecture diagrams, runbooks
+8. **Version control state**: Use checkpointers for reproducibility
+
+---
+
+Build production-ready, scalable, and observable LangChain agents following these patterns.

package/merged-commands/llm-application-dev-prompt-optimize.md

@@ -0,0 +1,37 @@
+---
+name: llm-application-dev-prompt-optimize
+description: "You are an expert prompt engineer specializing in crafting effective prompts for LLMs through advanced techniques including constitutional AI, chain-of-thought reasoning, and model-specific optimizati"
+---
+
+# Prompt Optimization
+
+You are an expert prompt engineer specializing in crafting effective prompts for LLMs through advanced techniques including constitutional AI, chain-of-thought reasoning, and model-specific optimization.
+
+## Use this skill when
+
+- Working on prompt optimization tasks or workflows
+- Needing guidance, best practices, or checklists for prompt optimization
+
+## Do not use this skill when
+
+- The task is unrelated to prompt optimization
+- You need a different domain or tool outside this scope
+
+## Context
+
+Transform basic instructions into production-ready prompts. Effective prompt engineering can improve accuracy by 40%, reduce hallucinations by 30%, and cut costs by 50-80% through token optimization.
+
+## Requirements
+
+$ARGUMENTS
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.

package/merged-commands/llm-application-dev.md

@@ -0,0 +1,216 @@
+---
+name: llm-application-dev
+description: Building applications with Large Language Models - prompt engineering, RAG patterns, and LLM integration. Use for AI-powered features, chatbots, or LLM-based automation.
+source: wshobson/agents
+license: MIT
+---
+
+# LLM Application Development
+
+## Prompt Engineering
+
+### Structured Prompts
+```typescript
+const systemPrompt = `You are a helpful assistant that answers questions about our product.
+
+RULES:
+- Only answer questions about our product
+- If you don't know, say "I don't know"
+- Keep responses concise (under 100 words)
+- Never make up information
+
+CONTEXT:
+{context}`;
+
+const userPrompt = `Question: {question}`;
+```
+
+### Few-Shot Examples
+```typescript
+const prompt = `Classify the sentiment of customer feedback.
+
+Examples:
+Input: "Love this product!"
+Output: positive
+
+Input: "Worst purchase ever"
+Output: negative
+
+Input: "It works fine"
+Output: neutral
+
+Input: "${customerFeedback}"
+Output:`;
+```
+
+### Chain of Thought
+```typescript
+const prompt = `Solve this step by step:
+
+Question: ${question}
+
+Let's think through this:
+1. First, identify the key information
+2. Then, determine the approach
+3. Finally, calculate the answer
+
+Step-by-step solution:`;
+```
+
+## API Integration
+
+### OpenAI Pattern
+```typescript
+import OpenAI from 'openai';
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+async function chat(messages: Message[]): Promise<string> {
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages,
+    temperature: 0.7,
+    max_tokens: 500,
+  });
+
+  return response.choices[0].message.content ?? '';
+}
+```
+
+### Anthropic Pattern
+```typescript
+import Anthropic from '@anthropic-ai/sdk';
+
+const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+async function chat(prompt: string): Promise<string> {
+  const response = await anthropic.messages.create({
+    model: 'claude-3-opus-20240229',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  return response.content[0].type === 'text'
+    ? response.content[0].text
+    : '';
+}
+```
+
+### Streaming Responses
+```typescript
+async function* streamChat(prompt: string) {
+  const stream = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: prompt }],
+    stream: true,
+  });
+
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content;
+    if (content) yield content;
+  }
+}
+```
+
+## RAG (Retrieval-Augmented Generation)
+
+### Basic RAG Pipeline
+```typescript
+async function ragQuery(question: string): Promise<string> {
+  // 1. Embed the question
+  const questionEmbedding = await embedText(question);
+
+  // 2. Search vector database
+  const relevantDocs = await vectorDb.search(questionEmbedding, { limit: 5 });
+
+  // 3. Build context
+  const context = relevantDocs.map(d => d.content).join('\n\n');
+
+  // 4. Generate answer
+  const prompt = `Answer based on this context:\n${context}\n\nQuestion: ${question}`;
+  return await chat(prompt);
+}
+```
+
+### Document Chunking
+```typescript
+function chunkDocument(text: string, options: ChunkOptions): string[] {
+  const { chunkSize = 1000, overlap = 200 } = options;
+  const chunks: string[] = [];
+
+  let start = 0;
+  while (start < text.length) {
+    const end = Math.min(start + chunkSize, text.length);
+    chunks.push(text.slice(start, end));
+    start += chunkSize - overlap;
+  }
+
+  return chunks;
+}
+```
+
+### Embedding Storage
+```typescript
+// Using Supabase with pgvector
+async function storeEmbeddings(docs: Document[]) {
+  for (const doc of docs) {
+    const embedding = await embedText(doc.content);
+
+    await supabase.from('documents').insert({
+      content: doc.content,
+      metadata: doc.metadata,
+      embedding: embedding,  // vector column
+    });
+  }
+}
+
+async function searchSimilar(query: string, limit = 5) {
+  const embedding = await embedText(query);
+
+  const { data } = await supabase.rpc('match_documents', {
+    query_embedding: embedding,
+    match_count: limit,
+  });
+
+  return data;
+}
+```
+
+## Error Handling
+
+```typescript
+async function safeLLMCall<T>(
+  fn: () => Promise<T>,
+  options: { retries?: number; fallback?: T }
+): Promise<T> {
+  const { retries = 3, fallback } = options;
+
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (error.status === 429) {
+        // Rate limit - exponential backoff
+        await sleep(Math.pow(2, i) * 1000);
+        continue;
+      }
+      if (i === retries - 1) {
+        if (fallback !== undefined) return fallback;
+        throw error;
+      }
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
+```
+
+## Best Practices
+
+- **Token Management**: Track usage and set limits
+- **Caching**: Cache embeddings and common queries
+- **Evaluation**: Test prompts with diverse inputs
+- **Guardrails**: Validate outputs before using
+- **Logging**: Log prompts and responses for debugging
+- **Cost Control**: Use cheaper models for simple tasks
+- **Latency**: Stream responses for better UX
+- **Privacy**: Don't send PII to external APIs