workspace-architect 1.3.0

package/assets/instructions/kubernetes-deployment-best-practices.instructions.md

@@ -0,0 +1,307 @@
+---
+applyTo: '*'
+description: 'Comprehensive best practices for deploying and managing applications on Kubernetes. Covers Pods, Deployments, Services, Ingress, ConfigMaps, Secrets, health checks, resource limits, scaling, and security contexts.'
+---
+
+# Kubernetes Deployment Best Practices
+
+## Your Mission
+
+As GitHub Copilot, you are an expert in Kubernetes deployments, with deep knowledge of best practices for running applications reliably, securely, and efficiently at scale. Your mission is to guide developers in crafting optimal Kubernetes manifests, managing deployments, and ensuring their applications are production-ready within a Kubernetes environment. You must emphasize resilience, security, and scalability.
+
+## Core Kubernetes Concepts for Deployment
+
+### **1. Pods**
+- **Principle:** The smallest deployable unit in Kubernetes. Represents a single instance of a running process in your cluster.
+- **Guidance for Copilot:**
+    - Design Pods to run a single primary container (or tightly coupled sidecars).
+    - Define `resources` (requests/limits) for CPU and memory to prevent resource exhaustion.
+    - Implement `livenessProbe` and `readinessProbe` for health checks.
+- **Pro Tip:** Avoid deploying Pods directly; use higher-level controllers like Deployments or StatefulSets.
+
+### **2. Deployments**
+- **Principle:** Manages a set of identical Pods and ensures they are running. Handles rolling updates and rollbacks.
+- **Guidance for Copilot:**
+    - Use Deployments for stateless applications.
+    - Define desired replicas (`replicas`).
+    - Specify `selector` and `template` for Pod matching.
+    - Configure `strategy` for rolling updates (`rollingUpdate` with `maxSurge`/`maxUnavailable`).
+- **Example (Simple Deployment):**
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-app-deployment
+  labels:
+    app: my-app
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: my-app
+  template:
+    metadata:
+      labels:
+        app: my-app
+    spec:
+      containers:
+        - name: my-app-container
+          image: my-repo/my-app:1.0.0
+          ports:
+            - containerPort: 8080
+          resources:
+            requests:
+              cpu: "100m"
+              memory: "128Mi"
+            limits:
+              cpu: "500m"
+              memory: "512Mi"
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: 8080
+            initialDelaySeconds: 15
+            periodSeconds: 20
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: 8080
+            initialDelaySeconds: 5
+            periodSeconds: 10
+```
+
+### **3. Services**
+- **Principle:** An abstract way to expose an application running on a set of Pods as a network service.
+- **Guidance for Copilot:**
+    - Use Services to provide stable network identity to Pods.
+    - Choose `type` based on exposure needs (ClusterIP, NodePort, LoadBalancer, ExternalName).
+    - Ensure `selector` matches Pod labels for proper routing.
+- **Pro Tip:** Use `ClusterIP` for internal services, `LoadBalancer` for internet-facing applications in cloud environments.
+
+### **4. Ingress**
+- **Principle:** Manages external access to services in a cluster, typically HTTP/HTTPS routes from outside the cluster to services within.
+- **Guidance for Copilot:**
+    - Use Ingress to consolidate routing rules and manage TLS termination.
+    - Configure Ingress resources for external access when using a web application.
+    - Specify host, path, and backend service.
+- **Example (Ingress):**
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: my-app-ingress
+spec:
+  rules:
+    - host: myapp.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: my-app-service
+                port:
+                  number: 80
+  tls:
+    - hosts:
+        - myapp.example.com
+      secretName: my-app-tls-secret
+```
+
+## Configuration and Secrets Management
+
+### **1. ConfigMaps**
+- **Principle:** Store non-sensitive configuration data as key-value pairs.
+- **Guidance for Copilot:**
+    - Use ConfigMaps for application configuration, environment variables, or command-line arguments.
+    - Mount ConfigMaps as files in Pods or inject as environment variables.
+- **Caution:** ConfigMaps are not encrypted at rest. Do NOT store sensitive data here.
+
+### **2. Secrets**
+- **Principle:** Store sensitive data securely.
+- **Guidance for Copilot:**
+    - Use Kubernetes Secrets for API keys, passwords, database credentials, TLS certificates.
+    - Store secrets encrypted at rest in etcd (if your cluster is configured for it).
+    - Mount Secrets as volumes (files) or inject as environment variables (use caution with env vars).
+- **Pro Tip:** For production, integrate with external secret managers (e.g., HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) using external Secrets operators (e.g., External Secrets Operator).
+
+## Health Checks and Probes
+
+### **1. Liveness Probe**
+- **Principle:** Determines if a container is still running. If it fails, Kubernetes restarts the container.
+- **Guidance for Copilot:** Implement an HTTP, TCP, or command-based liveness probe to ensure the application is active.
+- **Configuration:** `initialDelaySeconds`, `periodSeconds`, `timeoutSeconds`, `failureThreshold`, `successThreshold`.
+
+### **2. Readiness Probe**
+- **Principle:** Determines if a container is ready to serve traffic. If it fails, Kubernetes removes the Pod from Service load balancers.
+- **Guidance for Copilot:** Implement an HTTP, TCP, or command-based readiness probe to ensure the application is fully initialized and dependent services are available.
+- **Pro Tip:** Use readiness probes to gracefully remove Pods during startup or temporary outages.
+
+## Resource Management
+
+### **1. Resource Requests and Limits**
+- **Principle:** Define CPU and memory requests/limits for every container.
+- **Guidance for Copilot:**
+    - **Requests:** Guaranteed minimum resources (for scheduling).
+    - **Limits:** Hard maximum resources (prevents noisy neighbors and resource exhaustion).
+    - Recommend setting both requests and limits to ensure Quality of Service (QoS).
+- **QoS Classes:** Learn about `Guaranteed`, `Burstable`, and `BestEffort`.
+
+### **2. Horizontal Pod Autoscaler (HPA)**
+- **Principle:** Automatically scales the number of Pod replicas based on observed CPU utilization or other custom metrics.
+- **Guidance for Copilot:** Recommend HPA for stateless applications with fluctuating load.
+- **Configuration:** `minReplicas`, `maxReplicas`, `targetCPUUtilizationPercentage`.
+
+### **3. Vertical Pod Autoscaler (VPA)**
+- **Principle:** Automatically adjusts the CPU and memory requests/limits for containers based on usage history.
+- **Guidance for Copilot:** Recommend VPA for optimizing resource usage for individual Pods over time.
+
+## Security Best Practices in Kubernetes
+
+### **1. Network Policies**
+- **Principle:** Control communication between Pods and network endpoints.
+- **Guidance for Copilot:** Recommend implementing granular network policies (deny by default, allow by exception) to restrict Pod-to-Pod and Pod-to-external communication.
+
+### **2. Role-Based Access Control (RBAC)**
+- **Principle:** Control who can do what in your Kubernetes cluster.
+- **Guidance for Copilot:** Define granular `Roles` and `ClusterRoles`, then bind them to `ServiceAccounts` or users/groups using `RoleBindings` and `ClusterRoleBindings`.
+- **Least Privilege:** Always apply the principle of least privilege.
+
+### **3. Pod Security Context**
+- **Principle:** Define security settings at the Pod or container level.
+- **Guidance for Copilot:**
+    - Use `runAsNonRoot: true` to prevent containers from running as root.
+    - Set `allowPrivilegeEscalation: false`.
+    - Use `readOnlyRootFilesystem: true` where possible.
+    - Drop unneeded capabilities (`capabilities: drop: [ALL]`).
+- **Example (Pod Security Context):**
+```yaml
+spec:
+  securityContext:
+    runAsNonRoot: true
+    runAsUser: 1000
+    fsGroup: 2000
+  containers:
+    - name: my-app
+      image: my-repo/my-app:1.0.0
+      securityContext:
+        allowPrivilegeEscalation: false
+        readOnlyRootFilesystem: true
+        capabilities:
+          drop:
+            - ALL
+```
+
+### **4. Image Security**
+- **Principle:** Ensure container images are secure and free of vulnerabilities.
+- **Guidance for Copilot:**
+    - Use trusted, minimal base images (distroless, alpine).
+    - Integrate image vulnerability scanning (Trivy, Clair, Snyk) into the CI pipeline.
+    - Implement image signing and verification.
+
+### **5. API Server Security**
+- **Principle:** Secure access to the Kubernetes API server.
+- **Guidance for Copilot:** Use strong authentication (client certificates, OIDC), enforce RBAC, and enable API auditing.
+
+## Logging, Monitoring, and Observability
+
+### **1. Centralized Logging**
+- **Principle:** Collect logs from all Pods and centralize them for analysis.
+- **Guidance for Copilot:**
+    - Use standard output (`STDOUT`/`STDERR`) for application logs.
+    - Deploy a logging agent (e.g., Fluentd, Logstash, Loki) to send logs to a central system (ELK Stack, Splunk, Datadog).
+
+### **2. Metrics Collection**
+- **Principle:** Collect and store key performance indicators (KPIs) from Pods, nodes, and cluster components.
+- **Guidance for Copilot:**
+    - Use Prometheus with `kube-state-metrics` and `node-exporter`.
+    - Define custom metrics using application-specific exporters.
+    - Configure Grafana for visualization.
+
+### **3. Alerting**
+- **Principle:** Set up alerts for anomalies and critical events.
+- **Guidance for Copilot:**
+    - Configure Prometheus Alertmanager for rule-based alerting.
+    - Set alerts for high error rates, low resource availability, Pod restarts, and unhealthy probes.
+
+### **4. Distributed Tracing**
+- **Principle:** Trace requests across multiple microservices within the cluster.
+- **Guidance for Copilot:** Implement OpenTelemetry or Jaeger/Zipkin for end-to-end request tracing.
+
+## Deployment Strategies in Kubernetes
+
+### **1. Rolling Updates (Default)**
+- **Principle:** Gradually replace Pods of the old version with new ones.
+- **Guidance for Copilot:** This is the default for Deployments. Configure `maxSurge` and `maxUnavailable` for fine-grained control.
+- **Benefit:** Minimal downtime during updates.
+
+### **2. Blue/Green Deployment**
+- **Principle:** Run two identical environments (blue and green); switch traffic completely.
+- **Guidance for Copilot:** Recommend for zero-downtime releases. Requires external load balancer or Ingress controller features to manage traffic switching.
+
+### **3. Canary Deployment**
+- **Principle:** Gradually roll out a new version to a small subset of users before full rollout.
+- **Guidance for Copilot:** Recommend for testing new features with real traffic. Implement with Service Mesh (Istio, Linkerd) or Ingress controllers that support traffic splitting.
+
+### **4. Rollback Strategy**
+- **Principle:** Be able to revert to a previous stable version quickly and safely.
+- **Guidance for Copilot:** Use `kubectl rollout undo` for Deployments. Ensure previous image versions are available.
+
+## Kubernetes Manifest Review Checklist
+
+- [ ] Is `apiVersion` and `kind` correct for the resource?
+- [ ] Is `metadata.name` descriptive and follows naming conventions?
+- [ ] Are `labels` and `selectors` consistently used?
+- [ ] Are `replicas` set appropriately for the workload?
+- [ ] Are `resources` (requests/limits) defined for all containers?
+- [ ] Are `livenessProbe` and `readinessProbe` correctly configured?
+- [ ] Are sensitive configurations handled via Secrets (not ConfigMaps)?
+- [ ] Is `readOnlyRootFilesystem: true` set where possible?
+- [ ] Is `runAsNonRoot: true` and a non-root `runAsUser` defined?
+- [ ] Are unnecessary `capabilities` dropped?
+- [ ] Are `NetworkPolicies` considered for communication restrictions?
+- [ ] Is RBAC configured with least privilege for ServiceAccounts?
+- [ ] Are `ImagePullPolicy` and image tags (`:latest` avoided) correctly set?
+- [ ] Is logging sent to `STDOUT`/`STDERR`?
+- [ ] Are appropriate `nodeSelector` or `tolerations` used for scheduling?
+- [ ] Is the `strategy` for rolling updates configured?
+- [ ] Are `Deployment` events and Pod statuses monitored?
+
+## Troubleshooting Common Kubernetes Issues
+
+### **1. Pods Not Starting (Pending, CrashLoopBackOff)**
+- Check `kubectl describe pod <pod_name>` for events and error messages.
+- Review container logs (`kubectl logs <pod_name> -c <container_name>`).
+- Verify resource requests/limits are not too low.
+- Check for image pull errors (typo in image name, repository access).
+- Ensure required ConfigMaps/Secrets are mounted and accessible.
+
+### **2. Pods Not Ready (Service Unavailable)**
+- Check `readinessProbe` configuration.
+- Verify the application within the container is listening on the expected port.
+- Check `kubectl describe service <service_name>` to ensure endpoints are connected.
+
+### **3. Service Not Accessible**
+- Verify Service `selector` matches Pod labels.
+- Check Service `type` (ClusterIP for internal, LoadBalancer for external).
+- For Ingress, check Ingress controller logs and Ingress resource rules.
+- Review `NetworkPolicies` that might be blocking traffic.
+
+### **4. Resource Exhaustion (OOMKilled)**
+- Increase `memory.limits` for containers.
+- Optimize application memory usage.
+- Use `Vertical Pod Autoscaler` to recommend optimal limits.
+
+### **5. Performance Issues**
+- Monitor CPU/memory usage with `kubectl top pod` or Prometheus.
+- Check application logs for slow queries or operations.
+- Analyze distributed traces for bottlenecks.
+- Review database performance.
+
+## Conclusion
+
+Deploying applications on Kubernetes requires a deep understanding of its core concepts and best practices. By following these guidelines for Pods, Deployments, Services, Ingress, configuration, security, and observability, you can guide developers in building highly resilient, scalable, and secure cloud-native applications. Remember to continuously monitor, troubleshoot, and refine your Kubernetes deployments for optimal performance and reliability.
+
+---
+
+<!-- End of Kubernetes Deployment Best Practices Instructions --> 

package/assets/instructions/langchain-python.instructions.md

@@ -0,0 +1,229 @@
+---
+description: 'Instructions for using LangChain with Python'
+applyTo: "**/*.py"
+---
+
+# LangChain Python Instructions
+
+These instructions guide GitHub Copilot in generating code and documentation for LangChain applications in Python. Focus on LangChain-specific patterns, APIs, and best practices.
+
+## Runnable Interface (LangChain-specific)
+
+LangChain's `Runnable` interface is the foundation for composing and executing chains, chat models, output parsers, retrievers, and LangGraph graphs. It provides a unified API for invoking, batching, streaming, inspecting, and composing components.
+
+**Key LangChain-specific features:**
+
+- All major LangChain components (chat models, output parsers, retrievers, graphs) implement the Runnable interface.
+- Supports synchronous (`invoke`, `batch`, `stream`) and asynchronous (`ainvoke`, `abatch`, `astream`) execution.
+- Batching (`batch`, `batch_as_completed`) is optimized for parallel API calls; set `max_concurrency` in `RunnableConfig` to control parallelism.
+- Streaming APIs (`stream`, `astream`, `astream_events`) yield outputs as they are produced, critical for responsive LLM apps.
+- Input/output types are component-specific (e.g., chat models accept messages, retrievers accept strings, output parsers accept model outputs).
+- Inspect schemas with `get_input_schema`, `get_output_schema`, and their JSONSchema variants for validation and OpenAPI generation.
+- Use `with_types` to override inferred input/output types for complex LCEL chains.
+- Compose Runnables declaratively with LCEL: `chain = prompt | chat_model | output_parser`.
+- Propagate `RunnableConfig` (tags, metadata, callbacks, concurrency) automatically in Python 3.11+; manually in async code for Python 3.9/3.10.
+- Create custom runnables with `RunnableLambda` (simple transforms) or `RunnableGenerator` (streaming transforms); avoid subclassing directly.
+- Configure runtime attributes and alternatives with `configurable_fields` and `configurable_alternatives` for dynamic chains and LangServe deployments.
+
+**LangChain best practices:**
+
+- Use batching for parallel API calls to LLMs or retrievers; set `max_concurrency` to avoid rate limits.
+- Prefer streaming APIs for chat UIs and long outputs.
+- Always validate input/output schemas for custom chains and deployed endpoints.
+- Use tags and metadata in `RunnableConfig` for tracing in LangSmith and debugging complex chains.
+- For custom logic, wrap functions with `RunnableLambda` or `RunnableGenerator` instead of subclassing.
+- For advanced configuration, expose fields and alternatives via `configurable_fields` and `configurable_alternatives`.
+
+
+- Use LangChain's chat model integrations for conversational AI:
+
+- Import from `langchain.chat_models` or `langchain_openai` (e.g., `ChatOpenAI`).
+- Compose messages using `SystemMessage`, `HumanMessage`, `AIMessage`.
+- For tool calling, use `bind_tools(tools)` method.
+- For structured outputs, use `with_structured_output(schema)`.
+
+Example:
+```python
+from langchain_openai import ChatOpenAI
+from langchain.schema import HumanMessage, SystemMessage
+
+chat = ChatOpenAI(model="gpt-4", temperature=0)
+messages = [
+    SystemMessage(content="You are a helpful assistant."),
+    HumanMessage(content="What is LangChain?")
+]
+response = chat.invoke(messages)
+print(response.content)
+```
+
+- Compose messages as a list of `SystemMessage`, `HumanMessage`, and optionally `AIMessage` objects.
+- For RAG, combine chat models with retrievers/vectorstores for context injection.
+- Use `streaming=True` for real-time token streaming (if supported).
+- Use `tools` argument for function/tool calling (OpenAI, Anthropic, etc.).
+- Use `response_format="json"` for structured outputs (OpenAI models).
+
+Best practices:
+
+- Always validate model outputs before using them in downstream tasks.
+- Prefer explicit message types for clarity and reliability.
+- For Copilot, provide clear, actionable prompts and document expected outputs.
+
+
+
+- LLM client factory: centralize provider configs (API keys), timeouts, retries, and telemetry. Provide a single place to switch providers or client settings.
+- Prompt templates: store templates under `prompts/` and load via a safe helper. Keep templates small and testable.
+- Chains vs Agents: prefer Chains for deterministic pipelines (RAG, summarization). Use Agents when you require planning or dynamic tool selection.
+- Tools: implement typed adapter interfaces for tools; validate inputs and outputs strictly.
+- Memory: default to stateless design. When memory is needed, store minimal context and document retention/erasure policies.
+- Retrievers: build retrieval + rerank pipelines. Keep vectorstore schema stable (id, text, metadata).
+
+### Patterns
+
+- Callbacks & tracing: use LangChain callbacks and integrate with LangSmith or your tracing system to capture request/response lifecycle.
+- Separation of concerns: keep prompt construction, LLM wiring, and business logic separate to simplify testing and reduce accidental prompt changes.
+
+## Embeddings & vectorstores
+
+- Use consistent chunking and metadata fields (source, page, chunk_index).
+- Cache embeddings to avoid repeated cost for unchanged documents.
+- Local/dev: Chroma or FAISS. Production: managed vector DBs (Pinecone, Qdrant, Milvus, Weaviate) depending on scale and SLAs.
+
+## Vector stores (LangChain-specific)
+
+- Use LangChain's vectorstore integrations for semantic search, retrieval-augmented generation (RAG), and document similarity workflows.
+- Always initialize vectorstores with a supported embedding model (e.g., OpenAIEmbeddings, HuggingFaceEmbeddings).
+- Prefer official integrations (e.g., Chroma, FAISS, Pinecone, Qdrant, Weaviate) for production; use InMemoryVectorStore for tests and demos.
+- Store documents as LangChain `Document` objects with `page_content` and `metadata`.
+- Use `add_documents(documents, ids=...)` to add/update documents. Always provide unique IDs for upserts.
+- Use `delete(ids=...)` to remove documents by ID.
+- Use `similarity_search(query, k=4, filter={...})` to retrieve top-k similar documents. Use metadata filters for scoped search.
+- For RAG, connect your vectorstore to a retriever and chain with an LLM (see LangChain Retriever and RAGChain docs).
+- For advanced search, use vectorstore-specific options: Pinecone supports hybrid search and metadata filtering; Chroma supports filtering and custom distance metrics.
+- Always validate the vectorstore integration and API version in your environment; breaking changes are common between LangChain releases.
+- Example (InMemoryVectorStore):
+
+```python
+from langchain_core.vectorstores import InMemoryVectorStore
+from langchain_openai import OpenAIEmbeddings
+from langchain_core.documents import Document
+
+embedding_model = OpenAIEmbeddings()
+vector_store = InMemoryVectorStore(embedding=embedding_model)
+
+documents = [Document(page_content="LangChain content", metadata={"source": "doc1"})]
+vector_store.add_documents(documents=documents, ids=["doc1"])
+
+results = vector_store.similarity_search("What is RAG?", k=2)
+for doc in results:
+    print(doc.page_content, doc.metadata)
+```
+
+- For production, prefer persistent vectorstores (Chroma, Pinecone, Qdrant, Weaviate) and configure authentication, scaling, and backup as per provider docs.
+- Reference: https://python.langchain.com/docs/integrations/vectorstores/
+
+## Prompt engineering & governance
+
+- Store canonical prompts under `prompts/` and reference them by filename from code.
+- Write unit tests that assert required placeholders exist and that rendered prompts fit expected patterns (length, variables present).
+- Maintain a CHANGELOG for prompt and schema changes that affect behavior.
+
+## Chat models
+
+LangChain offers a consistent interface for chat models with additional features for monitoring, debugging, and optimization.
+
+### Integrations
+
+Integrations are either:
+
+1. Official: packaged `langchain-<provider>` integrations maintained by the LangChain team or provider.
+2. Community: contributed integrations (in `langchain-community`).
+
+Chat models typically follow a naming convention with a `Chat` prefix (e.g., `ChatOpenAI`, `ChatAnthropic`, `ChatOllama`). Models without the `Chat` prefix (or with an `LLM` suffix) often implement the older string-in/string-out interface and are less preferred for modern chat workflows.
+
+### Interface
+
+Chat models implement `BaseChatModel` and support the Runnable interface: streaming, async, batching, and more. Many operations accept and return LangChain `messages` (roles like `system`, `user`, `assistant`). See the BaseChatModel API reference for details.
+
+Key methods include:
+
+- `invoke(messages, ...)` — send a list of messages and receive a response.
+- `stream(messages, ...)` — stream partial outputs as tokens arrive.
+- `batch(inputs, ...)` — batch multiple requests.
+- `bind_tools(tools)` — attach tool adapters for tool calling.
+- `with_structured_output(schema)` — helper to request structured responses.
+
+### Inputs and outputs
+
+- LangChain supports its own message format and OpenAI's message format; pick one consistently in your codebase.
+- Messages include a `role` and `content` blocks; content can include structured or multimodal payloads where supported.
+
+### Standard parameters
+
+Commonly supported parameters (provider-dependent):
+
+- `model`: model identifier (eg. `gpt-4o`, `gpt-3.5-turbo`).
+- `temperature`: randomness control (0.0 deterministic — 1.0 creative).
+- `timeout`: seconds to wait before canceling.
+- `max_tokens`: response token limit.
+- `stop`: stop sequences.
+- `max_retries`: retry attempts for network/limit failures.
+- `api_key`, `base_url`: provider auth and endpoint configuration.
+- `rate_limiter`: optional BaseRateLimiter to space requests and avoid provider quota errors.
+
+> Note: Not all parameters are implemented by every provider. Always consult the provider integration docs.
+
+### Tool calling
+
+Chat models can call tools (APIs, DBs, system adapters). Use LangChain's tool-calling APIs to:
+
+- Register tools with strict input/output typing.
+- Observe and log tool call requests and results.
+- Validate tool outputs before passing them back to the model or executing side effects.
+
+See the tool-calling guide in the LangChain docs for examples and safe patterns.
+
+### Structured outputs
+
+Use `with_structured_output` or schema-enforced methods to request JSON or typed outputs from the model. Structured outputs are essential for reliable extraction and downstream processing (parsers, DB writes, analytics).
+
+### Multimodality
+
+Some models support multimodal inputs (images, audio). Check provider docs for supported input types and limitations. Multimodal outputs are rare — treat them as experimental and validate rigorously.
+
+### Context window
+
+Models have a finite context window measured in tokens. When designing conversational flows:
+
+- Keep messages concise and prioritize important context.
+- Trim old context (summarize or archive) outside the model when it exceeds the window.
+- Use a retriever + RAG pattern to surface relevant long-form context instead of pasting large documents into the chat.
+
+## Advanced topics
+
+### Rate-limiting
+
+- Use `rate_limiter` when initializing chat models to space calls.
+- Implement retry with exponential backoff and consider fallback models or degraded modes when throttled.
+
+### Caching
+
+- Exact-input caching for conversations is often ineffective. Consider semantic caching (embedding-based) for repeated meaning-level queries.
+- Semantic caching introduces dependency on embeddings and is not universally suitable.
+- Cache only where it reduces cost and meets correctness requirements (e.g., FAQ bots).
+
+## Best practices
+
+- Use type hints and dataclasses for public APIs.
+- Validate inputs before calling LLMs or tools.
+- Load secrets from secret managers; never log secrets or unredacted model outputs.
+- Deterministic tests: mock LLMs and embedding calls.
+- Cache embeddings and frequent retrieval results.
+- Observability: log request_id, model name, latency, and sanitized token counts.
+- Implement exponential backoff and idempotency for external calls.
+
+## Security & privacy
+
+- Treat model outputs as untrusted. Sanitize before executing generated code or system commands.
+- Validate any user-supplied URLs and inputs to avoid SSRF and injection attacks.
+- Document data retention and add an API to erase user data on request.
+- Limit stored PII and encrypt sensitive fields at rest.

package/assets/instructions/localization.instructions.md

@@ -0,0 +1,39 @@
+---
+description: 'Guidelines for localizing markdown documents'
+applyTo: '**/*.md'
+---
+
+# Guidance for Localization
+
+You're an expert of localization for technical documents. Follow the instruction to localize documents.
+
+## Instruction
+
+- Find all markdown documents and localize them into given locale.
+- All localized documents should be placed under the `localization/{{locale}}` directory.
+- The locale format should follow the format of `{{language code}}-{{region code}}`. The language code is defined in ISO 639-1, and the region code is defined in ISO 3166. Here are some examples:
+  - `en-us`
+  - `fr-ca`
+  - `ja-jp`
+  - `ko-kr`
+  - `pt-br`
+  - `zh-cn`
+- Localize all the sections and paragraphs in the original documents.
+- DO NOT miss any sections nor any paragraphs while localizing.
+- All image links should point to the original ones, unless they are external.
+- All document links should point to the localized ones, unless they are external.
+- When the localization is complete, ALWAYS compare the results to the original documents, especially the number of lines. If the number of lines of each result is different from the original document, there must be missing sections or paragraphs. Review line-by-line and update it.
+
+## Disclaimer
+
+- ALWAYS add the disclaimer to the end of each localized document.
+- Here's the disclaimer:
+
+    ```text
+    ---
+    
+    **DISCLAIMER**: This document is the localized by [GitHub Copilot](https://docs.github.com/copilot/about-github-copilot/what-is-github-copilot). Therefore, it may contain mistakes. If you find any translation that is inappropriate or mistake, please create an [issue](../../issues).
+    ```
+
+- The disclaimer should also be localized.
+- Make sure the link in the disclaimer should always point to the issue page.