{"owner":"cortexproject","repo":"cortex","hasSkills":true,"totalSkillsCount":6,"totalTokensCount":5372,"categories":["root-instruction","claude-rule","mcp-config","marketplace","plugin-manifest","cursor-rule"],"hasMcp":true,"mcpConfig":{"mcpServers":{"cortex":{"command":"npx","args":["-y","@modelcontextprotocol/server-cortex"]}}},"found":["AGENTS.md","CLAUDE.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json",".cursorrules (snowflake-cortex-ai-cursorrules-prompt-file.mdc)"],"skills":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nCortex is a horizontally scalable, highly available, multi-tenant, long-term storage solution for Prometheus metrics. It uses a microservices architecture with components that can run as separate processes or as a single binary.\n\n## Build Commands\n\n```bash\nmake # Build all (runs in Docker container by default)\nmake BUILD_IN_CONTAINER=false # Build locally without Docker\nmake exes # Build binaries only\nmake protos # Generate protobuf files\nmake lint # Run all linters (golangci-lint, misspell, etc.)\nmake doc # Generate config documentation (run after changing flags/config)\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image for integration tests\n```\n\n## Vendored Dependencies\n\nGo modules are vendored in the `vendor/` folder. When upgrading a dependency or component:\n\n```bash\ngo get github.com/some/dependency@version # Update go.mod\ngo mod vendor # Sync vendor folder\ngo mod tidy # Clean up go.mod/go.sum\n```\n\n**Important**: Always check the `vendor/` folder for upstream library code (e.g., `vendor/github.com/prometheus/alertmanager/` for Alertmanager internals). Do not modify vendored code directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ngo test -timeout 2400s -tags \"netgo slicelabels\" ./... # Run tests with CI configuration\n```\n\n### Integration Tests\n\nIntegration tests require Docker and the Cortex image to be built first:\n\n```bash\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image first\n\n# Run all integration tests\ngo test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...\n\n# Run a specific integration test\ngo test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run \"^TestRulerAPISharding$\"\n```\n\nEnvironment variables for integration tests:\n\n- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`)\n- `E2E_TEMP_DIR` - Directory for temporary test files\n\n## Code Formatting\n\nUse goimports with Cortex-specific import grouping:\n\n```bash\ngoimports -local github.com/cortexproject/cortex -w ./path/to/file.go\n```\n\nImport order: stdlib, third-party packages, internal Cortex packages (separated by blank lines).\n\n## Architecture\n\n### Write Path\n\n- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing\n- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks)\n\n### Read Path\n\n- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage\n- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing\n- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling\n\n### Storage\n\n- **Compactor** (stateless) - Compacts TSDB blocks in object storage\n- **Store Gateway** (semi-stateful) - Queries blocks from object storage\n\n### Optional Services\n\n- **Ruler** - Executes recording rules and alerts\n- **Alertmanager** - Multi-tenant alert routing\n- **Configs API** - Configuration management\n\n### Key Patterns\n\n- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution\n- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header\n- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift\n\n### Main Entry Points\n\n- `cmd/cortex/main.go` - Main Cortex binary\n- `pkg/cortex/cortex.go` - Service orchestration and configuration\n\n## Code Conventions\n\n- **No global variables** - Use dependency injection\n- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer\n- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case`\n- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`)\n\n## PR Requirements\n\n- Sign commits with DCO: `git commit -s -m \"message\"`\n- Run `make doc` if config/flags changed\n- Include CHANGELOG entry for user-facing changes\n\n## Investigating CI Build Failures\n\nWhen asked to investigate a CI build failure:\n\n1. **Fetch job details** using `gh api repos/cortexproject/cortex/actions/runs//jobs` to identify failed jobs and steps. Note: `gh run view --log` only works after the entire run completes, not just individual jobs.\n2. **Get annotations** using `gh api repos/cortexproject/cortex/check-runs//annotations` to surface error messages when full logs are unavailable.\n3. **Fetch full logs** once the run completes using `gh run view --job --log`.\n4. **Determine root cause** — distinguish between infrastructure failures (e.g., Docker Hub rate limits, runner issues) and code-related failures (e.g., test regressions). Use `git log` and `gh pr diff` to check if the failure relates to the PR's changes.\n5. **For flaky/infrastructure issues**, use `git log` and `git log -p` to trace when the failing code was introduced and which PR added it.\n6. **File GitHub issues** with the user's permission, including:\n - The full error output in a `
` block (since job links can expire)\n - Root cause analysis\n - Which PR introduced the issue (but do not assign or tag individuals without the user's approval)\n - Proposed solutions\n\n## Related Policies\n\nThis file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md).\n","CLAUDE.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nCortex is a horizontally scalable, highly available, multi-tenant, long-term storage solution for Prometheus metrics. It uses a microservices architecture with components that can run as separate processes or as a single binary.\n\n## Build Commands\n\n```bash\nmake # Build all (runs in Docker container by default)\nmake BUILD_IN_CONTAINER=false # Build locally without Docker\nmake exes # Build binaries only\nmake protos # Generate protobuf files\nmake lint # Run all linters (golangci-lint, misspell, etc.)\nmake doc # Generate config documentation (run after changing flags/config)\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image for integration tests\n```\n\n## Vendored Dependencies\n\nGo modules are vendored in the `vendor/` folder. When upgrading a dependency or component:\n\n```bash\ngo get github.com/some/dependency@version # Update go.mod\ngo mod vendor # Sync vendor folder\ngo mod tidy # Clean up go.mod/go.sum\n```\n\n**Important**: Always check the `vendor/` folder for upstream library code (e.g., `vendor/github.com/prometheus/alertmanager/` for Alertmanager internals). Do not modify vendored code directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ngo test -timeout 2400s -tags \"netgo slicelabels\" ./... # Run tests with CI configuration\n```\n\n### Integration Tests\n\nIntegration tests require Docker and the Cortex image to be built first:\n\n```bash\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image first\n\n# Run all integration tests\ngo test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...\n\n# Run a specific integration test\ngo test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run \"^TestRulerAPISharding$\"\n```\n\nEnvironment variables for integration tests:\n\n- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`)\n- `E2E_TEMP_DIR` - Directory for temporary test files\n\n## Code Formatting\n\nUse goimports with Cortex-specific import grouping:\n\n```bash\ngoimports -local github.com/cortexproject/cortex -w ./path/to/file.go\n```\n\nImport order: stdlib, third-party packages, internal Cortex packages (separated by blank lines).\n\n## Architecture\n\n### Write Path\n\n- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing\n- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks)\n\n### Read Path\n\n- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage\n- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing\n- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling\n\n### Storage\n\n- **Compactor** (stateless) - Compacts TSDB blocks in object storage\n- **Store Gateway** (semi-stateful) - Queries blocks from object storage\n\n### Optional Services\n\n- **Ruler** - Executes recording rules and alerts\n- **Alertmanager** - Multi-tenant alert routing\n- **Configs API** - Configuration management\n\n### Key Patterns\n\n- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution\n- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header\n- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift\n\n### Main Entry Points\n\n- `cmd/cortex/main.go` - Main Cortex binary\n- `pkg/cortex/cortex.go` - Service orchestration and configuration\n\n## Code Conventions\n\n- **No global variables** - Use dependency injection\n- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer\n- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case`\n- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`)\n\n## PR Requirements\n\n- Sign commits with DCO: `git commit -s -m \"message\"`\n- Run `make doc` if config/flags changed\n- Include CHANGELOG entry for user-facing changes\n\n## Investigating CI Build Failures\n\nWhen asked to investigate a CI build failure:\n\n1. **Fetch job details** using `gh api repos/cortexproject/cortex/actions/runs//jobs` to identify failed jobs and steps. Note: `gh run view --log` only works after the entire run completes, not just individual jobs.\n2. **Get annotations** using `gh api repos/cortexproject/cortex/check-runs//annotations` to surface error messages when full logs are unavailable.\n3. **Fetch full logs** once the run completes using `gh run view --job --log`.\n4. **Determine root cause** — distinguish between infrastructure failures (e.g., Docker Hub rate limits, runner issues) and code-related failures (e.g., test regressions). Use `git log` and `gh pr diff` to check if the failure relates to the PR's changes.\n5. **For flaky/infrastructure issues**, use `git log` and `git log -p` to trace when the failing code was introduced and which PR added it.\n6. **File GitHub issues** with the user's permission, including:\n - The full error output in a `
` block (since job links can expire)\n - Root cause analysis\n - Which PR introduced the issue (but do not assign or tag individuals without the user's approval)\n - Proposed solutions\n\n## Related Policies\n\nThis file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md).\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.claude-plugin/plugin.json)",".cursorrules (snowflake-cortex-ai-cursorrules-prompt-file.mdc)":"---\ndescription: \"Cursor rules for Snowflake Cortex AI Functions (AI_COMPLETE, AI_CLASSIFY, AI_EXTRACT, etc.) and Cortex Search for RAG applications.\"\nglobs: **/*\nalwaysApply: false\n---\n// Snowflake Cortex AI\n// Expert guidance for Cortex AI Functions and Cortex Search (hybrid vector+keyword search)\n\nYou are an expert in Snowflake Cortex — the AI layer of Snowflake including Cortex AI Functions (SQL-callable LLM/ML functions) and Cortex Search (managed hybrid search for RAG applications). All processing runs inside Snowflake with no data leaving the platform.\n\n// ═══════════════════════════════════════════\n// CORTEX AI FUNCTIONS\n// ═══════════════════════════════════════════\n\n// Available Functions (use these names — they are the current versions):\n// AI_COMPLETE — General-purpose LLM completion (text, images, documents).\n// AI_CLASSIFY — Classify text/images into user-defined categories (multi-label supported).\n// AI_FILTER — Returns TRUE/FALSE for text/image input. Use in WHERE clauses.\n// AI_AGG — Aggregate insights across rows of text (no context window limit).\n// AI_EMBED — Generate embedding vectors (similarity search, clustering).\n// AI_EXTRACT — Extract structured info from text, images, or documents.\n// AI_SENTIMENT — Sentiment score from text (-1 to 1).\n// AI_SUMMARIZE_AGG — Summarize across rows (no context window limit).\n// AI_SIMILARITY — Embedding similarity between two inputs.\n// AI_TRANSCRIBE — Transcribe audio/video from stages.\n// AI_PARSE_DOCUMENT — OCR or text+layout extraction from documents in stages.\n// AI_REDACT — Redact PII from text.\n// AI_TRANSLATE — Translate between supported languages.\n\n// Helper Functions:\n// TO_FILE('@stage', 'filename') — File reference for document processing.\n// AI_COUNT_TOKENS(model, text) — Check token count before calling a model.\n// PROMPT('template {0}', arg) — Build prompt objects for AI_COMPLETE.\n// TRY_COMPLETE — Returns NULL on failure instead of error.\n\n// AI_COMPLETE — The Primary Function\n// Models: claude-4-opus, claude-4-sonnet, claude-sonnet-4-5, claude-opus-4-5, claude-haiku-4-5,\n// gemini-3-pro, llama3.1-70b, llama3.1-8b, llama3.3-70b, mistral-large2, mistral-small2, deepseek-r1\n\n// Text completion:\nSELECT AI_COMPLETE(MODEL => 'claude-4-sonnet', PROMPT => 'Summarize: ' || review_text) FROM reviews;\n\n// Document processing:\nSELECT AI_COMPLETE(\n MODEL => 'claude-4-sonnet',\n PROMPT => PROMPT('Extract the invoice total from {0}', TO_FILE('@docs', 'invoice.pdf'))\n);\n\n// Structured JSON output:\nSELECT AI_COMPLETE(MODEL => 'claude-4-sonnet',\n PROMPT => 'Extract name, email, company as JSON: ' || raw_text)::VARIANT AS extracted FROM contacts;\n\n// AI_CLASSIFY:\nSELECT AI_CLASSIFY(ticket_text, ['billing', 'technical', 'account', 'other']) AS category FROM tickets;\n// Multi-label: AI_CLASSIFY(input, categories, {'output_mode': 'multi'})\n\n// AI_FILTER (natural-language WHERE):\nSELECT * FROM reviews WHERE AI_FILTER(review_text, 'mentions product quality issues');\n\n// AI_AGG (cross-row aggregation):\nSELECT AI_AGG(feedback_text, 'What are the top 3 themes?') FROM customer_feedback;\n\n// AI_EXTRACT (entity extraction):\nSELECT AI_EXTRACT(email_body, 'meeting date', 'attendees', 'action items') FROM emails;\n\n// AI_SENTIMENT: SELECT review_text, AI_SENTIMENT(review_text) AS sentiment FROM product_reviews;\n// AI_EMBED: SELECT AI_EMBED(description) AS embedding FROM products;\n// AI_PARSE_DOCUMENT: SELECT AI_PARSE_DOCUMENT(TO_FILE('@docs', 'contract.pdf'), MODE => 'LAYOUT');\n// AI_TRANSCRIBE: SELECT AI_TRANSCRIBE(TO_FILE('@media', 'recording.mp3')) AS transcript;\n// AI_REDACT: SELECT AI_REDACT(customer_notes) AS redacted FROM support_cases;\n\n// Privileges: USE AI FUNCTIONS account privilege + SNOWFLAKE.CORTEX_USER database role (both granted to PUBLIC by default).\n\n// ═══════════════════════════════════════════\n// CORTEX SEARCH — Hybrid Vector + Keyword Search\n// ═══════════════════════════════════════════\n\n// Fully managed search combining vector (semantic) and keyword (lexical) search.\n// Use cases: RAG for LLM chatbots, enterprise search, AI-powered Q&A.\n\n// Single-index (simplest):\nCREATE OR REPLACE CORTEX SEARCH SERVICE my_search\n ON transcript_text\n ATTRIBUTES region, agent_id\n WAREHOUSE = my_wh\n TARGET_LAG = '1 day'\n EMBEDDING_MODEL = 'snowflake-arctic-embed-l-v2.0'\n AS (SELECT transcript_text, region, agent_id FROM support_transcripts);\n\n// Multi-index (text + vector on multiple columns):\nCREATE OR REPLACE CORTEX SEARCH SERVICE my_multi_search\n TEXT INDEXES transcript_text, summary\n VECTOR INDEXES transcript_text (model='snowflake-arctic-embed-l-v2.0')\n ATTRIBUTES region\n WAREHOUSE = my_wh\n TARGET_LAG = '1 hour'\n AS (SELECT transcript_text, summary, region FROM support_transcripts);\n\n// Key Parameters: ON (single-index column), TEXT INDEXES, VECTOR INDEXES, ATTRIBUTES (filter columns),\n// TARGET_LAG (freshness), EMBEDDING_MODEL, PRIMARY KEY (optimized incremental refresh).\n\n// Query — Python API (recommended for apps):\nfrom snowflake.core import Root\nroot = Root(session)\nservice = root.databases[\"db\"].schemas[\"schema\"].cortex_search_services[\"my_search\"]\nresp = service.search(\n query=\"internet connection issues\",\n columns=[\"transcript_text\", \"region\"],\n filter={\"@eq\": {\"region\": \"North America\"}},\n limit=5\n)\n\n// Query — REST API:\n// POST /api/v2/databases//schemas//cortex-search-services/:query\n// Body: {\"query\": \"...\", \"columns\": [...], \"filter\": {...}, \"limit\": N}\n\n// Filter syntax:\n// {\"@eq\": {\"region\": \"NA\"}}, {\"@contains\": {\"tags\": \"urgent\"}}, {\"@gte\": {\"score\": 0.8}}\n// {\"@and\": [f1, f2]}, {\"@or\": [f1, f2]}, {\"@not\": f}\n\n// Scoring config — adjust text vs vector vs reranker weights:\nresp = service.search(query=\"billing dispute\", columns=[\"transcript_text\"],\n scoring_config={\"weights\": {\"texts\": 0.3, \"vectors\": 0.5, \"reranker\": 0.2}}, limit=10)\n\n// RAG Pattern: 1) Search for context, 2) Pass to AI_COMPLETE:\n// results = service.search(query=question, columns=[\"content\"], limit=5)\n// SELECT AI_COMPLETE(MODEL=>'claude-4-sonnet', PROMPT=>'Answer from context: '||context||' Q: '||question);\n\n// Best Practices\n- Use AI_CLASSIFY for classification (cheaper than AI_COMPLETE).\n- Check token counts with AI_COUNT_TOKENS before large batch jobs.\n- Set PRIMARY KEY on Cortex Search for optimized incremental refresh.\n- Use ATTRIBUTES for filterable columns. Use SEARCH_PREVIEW for testing, Python/REST for production.\n- Use dedicated warehouse (no larger than MEDIUM) per search service.\n\n// Anti-Patterns\n- Do NOT use old function names (COMPLETE, CLASSIFY_TEXT, etc.) — use AI_* versions.\n- Do NOT pass entire tables through AI_COMPLETE row-by-row without cost estimation.\n- Do NOT hardcode model names without considering regional availability.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nCortex is a horizontally scalable, highly available, multi-tenant, long-term storage solution for Prometheus metrics. It uses a microservices architecture with components that can run as separate processes or as a single binary.\n\n## Build Commands\n\n```bash\nmake # Build all (runs in Docker container by default)\nmake BUILD_IN_CONTAINER=false # Build locally without Docker\nmake exes # Build binaries only\nmake protos # Generate protobuf files\nmake lint # Run all linters (golangci-lint, misspell, etc.)\nmake doc # Generate config documentation (run after changing flags/config)\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image for integration tests\n```\n\n## Vendored Dependencies\n\nGo modules are vendored in the `vendor/` folder. When upgrading a dependency or component:\n\n```bash\ngo get github.com/some/dependency@version # Update go.mod\ngo mod vendor # Sync vendor folder\ngo mod tidy # Clean up go.mod/go.sum\n```\n\n**Important**: Always check the `vendor/` folder for upstream library code (e.g., `vendor/github.com/prometheus/alertmanager/` for Alertmanager internals). Do not modify vendored code directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ngo test -timeout 2400s -tags \"netgo slicelabels\" ./... # Run tests with CI configuration\n```\n\n### Integration Tests\n\nIntegration tests require Docker and the Cortex image to be built first:\n\n```bash\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image first\n\n# Run all integration tests\ngo test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...\n\n# Run a specific integration test\ngo test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run \"^TestRulerAPISharding$\"\n```\n\nEnvironment variables for integration tests:\n\n- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`)\n- `E2E_TEMP_DIR` - Directory for temporary test files\n\n## Code Formatting\n\nUse goimports with Cortex-specific import grouping:\n\n```bash\ngoimports -local github.com/cortexproject/cortex -w ./path/to/file.go\n```\n\nImport order: stdlib, third-party packages, internal Cortex packages (separated by blank lines).\n\n## Architecture\n\n### Write Path\n\n- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing\n- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks)\n\n### Read Path\n\n- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage\n- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing\n- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling\n\n### Storage\n\n- **Compactor** (stateless) - Compacts TSDB blocks in object storage\n- **Store Gateway** (semi-stateful) - Queries blocks from object storage\n\n### Optional Services\n\n- **Ruler** - Executes recording rules and alerts\n- **Alertmanager** - Multi-tenant alert routing\n- **Configs API** - Configuration management\n\n### Key Patterns\n\n- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution\n- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header\n- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift\n\n### Main Entry Points\n\n- `cmd/cortex/main.go` - Main Cortex binary\n- `pkg/cortex/cortex.go` - Service orchestration and configuration\n\n## Code Conventions\n\n- **No global variables** - Use dependency injection\n- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer\n- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case`\n- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`)\n\n## PR Requirements\n\n- Sign commits with DCO: `git commit -s -m \"message\"`\n- Run `make doc` if config/flags changed\n- Include CHANGELOG entry for user-facing changes\n\n## Investigating CI Build Failures\n\nWhen asked to investigate a CI build failure:\n\n1. **Fetch job details** using `gh api repos/cortexproject/cortex/actions/runs//jobs` to identify failed jobs and steps. Note: `gh run view --log` only works after the entire run completes, not just individual jobs.\n2. **Get annotations** using `gh api repos/cortexproject/cortex/check-runs//annotations` to surface error messages when full logs are unavailable.\n3. **Fetch full logs** once the run completes using `gh run view --job --log`.\n4. **Determine root cause** — distinguish between infrastructure failures (e.g., Docker Hub rate limits, runner issues) and code-related failures (e.g., test regressions). Use `git log` and `gh pr diff` to check if the failure relates to the PR's changes.\n5. **For flaky/infrastructure issues**, use `git log` and `git log -p` to trace when the failing code was introduced and which PR added it.\n6. **File GitHub issues** with the user's permission, including:\n - The full error output in a `
` block (since job links can expire)\n - Root cause analysis\n - Which PR introduced the issue (but do not assign or tag individuals without the user's approval)\n - Proposed solutions\n\n## Related Policies\n\nThis file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md).\n","CLAUDE.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nCortex is a horizontally scalable, highly available, multi-tenant, long-term storage solution for Prometheus metrics. It uses a microservices architecture with components that can run as separate processes or as a single binary.\n\n## Build Commands\n\n```bash\nmake # Build all (runs in Docker container by default)\nmake BUILD_IN_CONTAINER=false # Build locally without Docker\nmake exes # Build binaries only\nmake protos # Generate protobuf files\nmake lint # Run all linters (golangci-lint, misspell, etc.)\nmake doc # Generate config documentation (run after changing flags/config)\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image for integration tests\n```\n\n## Vendored Dependencies\n\nGo modules are vendored in the `vendor/` folder. When upgrading a dependency or component:\n\n```bash\ngo get github.com/some/dependency@version # Update go.mod\ngo mod vendor # Sync vendor folder\ngo mod tidy # Clean up go.mod/go.sum\n```\n\n**Important**: Always check the `vendor/` folder for upstream library code (e.g., `vendor/github.com/prometheus/alertmanager/` for Alertmanager internals). Do not modify vendored code directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ngo test -timeout 2400s -tags \"netgo slicelabels\" ./... # Run tests with CI configuration\n```\n\n### Integration Tests\n\nIntegration tests require Docker and the Cortex image to be built first:\n\n```bash\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image first\n\n# Run all integration tests\ngo test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...\n\n# Run a specific integration test\ngo test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run \"^TestRulerAPISharding$\"\n```\n\nEnvironment variables for integration tests:\n\n- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`)\n- `E2E_TEMP_DIR` - Directory for temporary test files\n\n## Code Formatting\n\nUse goimports with Cortex-specific import grouping:\n\n```bash\ngoimports -local github.com/cortexproject/cortex -w ./path/to/file.go\n```\n\nImport order: stdlib, third-party packages, internal Cortex packages (separated by blank lines).\n\n## Architecture\n\n### Write Path\n\n- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing\n- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks)\n\n### Read Path\n\n- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage\n- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing\n- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling\n\n### Storage\n\n- **Compactor** (stateless) - Compacts TSDB blocks in object storage\n- **Store Gateway** (semi-stateful) - Queries blocks from object storage\n\n### Optional Services\n\n- **Ruler** - Executes recording rules and alerts\n- **Alertmanager** - Multi-tenant alert routing\n- **Configs API** - Configuration management\n\n### Key Patterns\n\n- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution\n- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header\n- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift\n\n### Main Entry Points\n\n- `cmd/cortex/main.go` - Main Cortex binary\n- `pkg/cortex/cortex.go` - Service orchestration and configuration\n\n## Code Conventions\n\n- **No global variables** - Use dependency injection\n- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer\n- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case`\n- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`)\n\n## PR Requirements\n\n- Sign commits with DCO: `git commit -s -m \"message\"`\n- Run `make doc` if config/flags changed\n- Include CHANGELOG entry for user-facing changes\n\n## Investigating CI Build Failures\n\nWhen asked to investigate a CI build failure:\n\n1. **Fetch job details** using `gh api repos/cortexproject/cortex/actions/runs//jobs` to identify failed jobs and steps. Note: `gh run view --log` only works after the entire run completes, not just individual jobs.\n2. **Get annotations** using `gh api repos/cortexproject/cortex/check-runs//annotations` to surface error messages when full logs are unavailable.\n3. **Fetch full logs** once the run completes using `gh run view --job --log`.\n4. **Determine root cause** — distinguish between infrastructure failures (e.g., Docker Hub rate limits, runner issues) and code-related failures (e.g., test regressions). Use `git log` and `gh pr diff` to check if the failure relates to the PR's changes.\n5. **For flaky/infrastructure issues**, use `git log` and `git log -p` to trace when the failing code was introduced and which PR added it.\n6. **File GitHub issues** with the user's permission, including:\n - The full error output in a `
` block (since job links can expire)\n - Root cause analysis\n - Which PR introduced the issue (but do not assign or tag individuals without the user's approval)\n - Proposed solutions\n\n## Related Policies\n\nThis file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md).\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.claude-plugin/plugin.json)",".cursorrules (snowflake-cortex-ai-cursorrules-prompt-file.mdc)":"---\ndescription: \"Cursor rules for Snowflake Cortex AI Functions (AI_COMPLETE, AI_CLASSIFY, AI_EXTRACT, etc.) and Cortex Search for RAG applications.\"\nglobs: **/*\nalwaysApply: false\n---\n// Snowflake Cortex AI\n// Expert guidance for Cortex AI Functions and Cortex Search (hybrid vector+keyword search)\n\nYou are an expert in Snowflake Cortex — the AI layer of Snowflake including Cortex AI Functions (SQL-callable LLM/ML functions) and Cortex Search (managed hybrid search for RAG applications). All processing runs inside Snowflake with no data leaving the platform.\n\n// ═══════════════════════════════════════════\n// CORTEX AI FUNCTIONS\n// ═══════════════════════════════════════════\n\n// Available Functions (use these names — they are the current versions):\n// AI_COMPLETE — General-purpose LLM completion (text, images, documents).\n// AI_CLASSIFY — Classify text/images into user-defined categories (multi-label supported).\n// AI_FILTER — Returns TRUE/FALSE for text/image input. Use in WHERE clauses.\n// AI_AGG — Aggregate insights across rows of text (no context window limit).\n// AI_EMBED — Generate embedding vectors (similarity search, clustering).\n// AI_EXTRACT — Extract structured info from text, images, or documents.\n// AI_SENTIMENT — Sentiment score from text (-1 to 1).\n// AI_SUMMARIZE_AGG — Summarize across rows (no context window limit).\n// AI_SIMILARITY — Embedding similarity between two inputs.\n// AI_TRANSCRIBE — Transcribe audio/video from stages.\n// AI_PARSE_DOCUMENT — OCR or text+layout extraction from documents in stages.\n// AI_REDACT — Redact PII from text.\n// AI_TRANSLATE — Translate between supported languages.\n\n// Helper Functions:\n// TO_FILE('@stage', 'filename') — File reference for document processing.\n// AI_COUNT_TOKENS(model, text) — Check token count before calling a model.\n// PROMPT('template {0}', arg) — Build prompt objects for AI_COMPLETE.\n// TRY_COMPLETE — Returns NULL on failure instead of error.\n\n// AI_COMPLETE — The Primary Function\n// Models: claude-4-opus, claude-4-sonnet, claude-sonnet-4-5, claude-opus-4-5, claude-haiku-4-5,\n// gemini-3-pro, llama3.1-70b, llama3.1-8b, llama3.3-70b, mistral-large2, mistral-small2, deepseek-r1\n\n// Text completion:\nSELECT AI_COMPLETE(MODEL => 'claude-4-sonnet', PROMPT => 'Summarize: ' || review_text) FROM reviews;\n\n// Document processing:\nSELECT AI_COMPLETE(\n MODEL => 'claude-4-sonnet',\n PROMPT => PROMPT('Extract the invoice total from {0}', TO_FILE('@docs', 'invoice.pdf'))\n);\n\n// Structured JSON output:\nSELECT AI_COMPLETE(MODEL => 'claude-4-sonnet',\n PROMPT => 'Extract name, email, company as JSON: ' || raw_text)::VARIANT AS extracted FROM contacts;\n\n// AI_CLASSIFY:\nSELECT AI_CLASSIFY(ticket_text, ['billing', 'technical', 'account', 'other']) AS category FROM tickets;\n// Multi-label: AI_CLASSIFY(input, categories, {'output_mode': 'multi'})\n\n// AI_FILTER (natural-language WHERE):\nSELECT * FROM reviews WHERE AI_FILTER(review_text, 'mentions product quality issues');\n\n// AI_AGG (cross-row aggregation):\nSELECT AI_AGG(feedback_text, 'What are the top 3 themes?') FROM customer_feedback;\n\n// AI_EXTRACT (entity extraction):\nSELECT AI_EXTRACT(email_body, 'meeting date', 'attendees', 'action items') FROM emails;\n\n// AI_SENTIMENT: SELECT review_text, AI_SENTIMENT(review_text) AS sentiment FROM product_reviews;\n// AI_EMBED: SELECT AI_EMBED(description) AS embedding FROM products;\n// AI_PARSE_DOCUMENT: SELECT AI_PARSE_DOCUMENT(TO_FILE('@docs', 'contract.pdf'), MODE => 'LAYOUT');\n// AI_TRANSCRIBE: SELECT AI_TRANSCRIBE(TO_FILE('@media', 'recording.mp3')) AS transcript;\n// AI_REDACT: SELECT AI_REDACT(customer_notes) AS redacted FROM support_cases;\n\n// Privileges: USE AI FUNCTIONS account privilege + SNOWFLAKE.CORTEX_USER database role (both granted to PUBLIC by default).\n\n// ═══════════════════════════════════════════\n// CORTEX SEARCH — Hybrid Vector + Keyword Search\n// ═══════════════════════════════════════════\n\n// Fully managed search combining vector (semantic) and keyword (lexical) search.\n// Use cases: RAG for LLM chatbots, enterprise search, AI-powered Q&A.\n\n// Single-index (simplest):\nCREATE OR REPLACE CORTEX SEARCH SERVICE my_search\n ON transcript_text\n ATTRIBUTES region, agent_id\n WAREHOUSE = my_wh\n TARGET_LAG = '1 day'\n EMBEDDING_MODEL = 'snowflake-arctic-embed-l-v2.0'\n AS (SELECT transcript_text, region, agent_id FROM support_transcripts);\n\n// Multi-index (text + vector on multiple columns):\nCREATE OR REPLACE CORTEX SEARCH SERVICE my_multi_search\n TEXT INDEXES transcript_text, summary\n VECTOR INDEXES transcript_text (model='snowflake-arctic-embed-l-v2.0')\n ATTRIBUTES region\n WAREHOUSE = my_wh\n TARGET_LAG = '1 hour'\n AS (SELECT transcript_text, summary, region FROM support_transcripts);\n\n// Key Parameters: ON (single-index column), TEXT INDEXES, VECTOR INDEXES, ATTRIBUTES (filter columns),\n// TARGET_LAG (freshness), EMBEDDING_MODEL, PRIMARY KEY (optimized incremental refresh).\n\n// Query — Python API (recommended for apps):\nfrom snowflake.core import Root\nroot = Root(session)\nservice = root.databases[\"db\"].schemas[\"schema\"].cortex_search_services[\"my_search\"]\nresp = service.search(\n query=\"internet connection issues\",\n columns=[\"transcript_text\", \"region\"],\n filter={\"@eq\": {\"region\": \"North America\"}},\n limit=5\n)\n\n// Query — REST API:\n// POST /api/v2/databases//schemas//cortex-search-services/:query\n// Body: {\"query\": \"...\", \"columns\": [...], \"filter\": {...}, \"limit\": N}\n\n// Filter syntax:\n// {\"@eq\": {\"region\": \"NA\"}}, {\"@contains\": {\"tags\": \"urgent\"}}, {\"@gte\": {\"score\": 0.8}}\n// {\"@and\": [f1, f2]}, {\"@or\": [f1, f2]}, {\"@not\": f}\n\n// Scoring config — adjust text vs vector vs reranker weights:\nresp = service.search(query=\"billing dispute\", columns=[\"transcript_text\"],\n scoring_config={\"weights\": {\"texts\": 0.3, \"vectors\": 0.5, \"reranker\": 0.2}}, limit=10)\n\n// RAG Pattern: 1) Search for context, 2) Pass to AI_COMPLETE:\n// results = service.search(query=question, columns=[\"content\"], limit=5)\n// SELECT AI_COMPLETE(MODEL=>'claude-4-sonnet', PROMPT=>'Answer from context: '||context||' Q: '||question);\n\n// Best Practices\n- Use AI_CLASSIFY for classification (cheaper than AI_COMPLETE).\n- Check token counts with AI_COUNT_TOKENS before large batch jobs.\n- Set PRIMARY KEY on Cortex Search for optimized incremental refresh.\n- Use ATTRIBUTES for filterable columns. Use SEARCH_PREVIEW for testing, Python/REST for production.\n- Use dedicated warehouse (no larger than MEDIUM) per search service.\n\n// Anti-Patterns\n- Do NOT use old function names (COMPLETE, CLASSIFY_TEXT, etc.) — use AI_* versions.\n- Do NOT pass entire tables through AI_COMPLETE row-by-row without cost estimation.\n- Do NOT hardcode model names without considering regional availability.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/cortexproject/cortex/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nCortex is a horizontally scalable, highly available, multi-tenant, long-term storage solution for Prometheus metrics. It uses a microservices architecture with components that can run as separate processes or as a single binary.\n\n## Build Commands\n\n```bash\nmake # Build all (runs in Docker container by default)\nmake BUILD_IN_CONTAINER=false # Build locally without Docker\nmake exes # Build binaries only\nmake protos # Generate protobuf files\nmake lint # Run all linters (golangci-lint, misspell, etc.)\nmake doc # Generate config documentation (run after changing flags/config)\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image for integration tests\n```\n\n## Vendored Dependencies\n\nGo modules are vendored in the `vendor/` folder. When upgrading a dependency or component:\n\n```bash\ngo get github.com/some/dependency@version # Update go.mod\ngo mod vendor # Sync vendor folder\ngo mod tidy # Clean up go.mod/go.sum\n```\n\n**Important**: Always check the `vendor/` folder for upstream library code (e.g., `vendor/github.com/prometheus/alertmanager/` for Alertmanager internals). Do not modify vendored code directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ngo test -timeout 2400s -tags \"netgo slicelabels\" ./... # Run tests with CI configuration\n```\n\n### Integration Tests\n\nIntegration tests require Docker and the Cortex image to be built first:\n\n```bash\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image first\n\n# Run all integration tests\ngo test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...\n\n# Run a specific integration test\ngo test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run \"^TestRulerAPISharding$\"\n```\n\nEnvironment variables for integration tests:\n\n- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`)\n- `E2E_TEMP_DIR` - Directory for temporary test files\n\n## Code Formatting\n\nUse goimports with Cortex-specific import grouping:\n\n```bash\ngoimports -local github.com/cortexproject/cortex -w ./path/to/file.go\n```\n\nImport order: stdlib, third-party packages, internal Cortex packages (separated by blank lines).\n\n## Architecture\n\n### Write Path\n\n- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing\n- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks)\n\n### Read Path\n\n- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage\n- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing\n- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling\n\n### Storage\n\n- **Compactor** (stateless) - Compacts TSDB blocks in object storage\n- **Store Gateway** (semi-stateful) - Queries blocks from object storage\n\n### Optional Services\n\n- **Ruler** - Executes recording rules and alerts\n- **Alertmanager** - Multi-tenant alert routing\n- **Configs API** - Configuration management\n\n### Key Patterns\n\n- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution\n- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header\n- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift\n\n### Main Entry Points\n\n- `cmd/cortex/main.go` - Main Cortex binary\n- `pkg/cortex/cortex.go` - Service orchestration and configuration\n\n## Code Conventions\n\n- **No global variables** - Use dependency injection\n- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer\n- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case`\n- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`)\n\n## PR Requirements\n\n- Sign commits with DCO: `git commit -s -m \"message\"`\n- Run `make doc` if config/flags changed\n- Include CHANGELOG entry for user-facing changes\n\n## Investigating CI Build Failures\n\nWhen asked to investigate a CI build failure:\n\n1. **Fetch job details** using `gh api repos/cortexproject/cortex/actions/runs//jobs` to identify failed jobs and steps. Note: `gh run view --log` only works after the entire run completes, not just individual jobs.\n2. **Get annotations** using `gh api repos/cortexproject/cortex/check-runs//annotations` to surface error messages when full logs are unavailable.\n3. **Fetch full logs** once the run completes using `gh run view --job --log`.\n4. **Determine root cause** — distinguish between infrastructure failures (e.g., Docker Hub rate limits, runner issues) and code-related failures (e.g., test regressions). Use `git log` and `gh pr diff` to check if the failure relates to the PR's changes.\n5. **For flaky/infrastructure issues**, use `git log` and `git log -p` to trace when the failing code was introduced and which PR added it.\n6. **File GitHub issues** with the user's permission, including:\n - The full error output in a `
` block (since job links can expire)\n - Root cause analysis\n - Which PR introduced the issue (but do not assign or tag individuals without the user's approval)\n - Proposed solutions\n\n## Related Policies\n\nThis file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md).\n","isInternal":false,"tokens":1351,"sizeBytes":5857},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/cortexproject/cortex/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nCortex is a horizontally scalable, highly available, multi-tenant, long-term storage solution for Prometheus metrics. It uses a microservices architecture with components that can run as separate processes or as a single binary.\n\n## Build Commands\n\n```bash\nmake # Build all (runs in Docker container by default)\nmake BUILD_IN_CONTAINER=false # Build locally without Docker\nmake exes # Build binaries only\nmake protos # Generate protobuf files\nmake lint # Run all linters (golangci-lint, misspell, etc.)\nmake doc # Generate config documentation (run after changing flags/config)\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image for integration tests\n```\n\n## Vendored Dependencies\n\nGo modules are vendored in the `vendor/` folder. When upgrading a dependency or component:\n\n```bash\ngo get github.com/some/dependency@version # Update go.mod\ngo mod vendor # Sync vendor folder\ngo mod tidy # Clean up go.mod/go.sum\n```\n\n**Important**: Always check the `vendor/` folder for upstream library code (e.g., `vendor/github.com/prometheus/alertmanager/` for Alertmanager internals). Do not modify vendored code directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ngo test -timeout 2400s -tags \"netgo slicelabels\" ./... # Run tests with CI configuration\n```\n\n### Integration Tests\n\nIntegration tests require Docker and the Cortex image to be built first:\n\n```bash\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image first\n\n# Run all integration tests\ngo test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...\n\n# Run a specific integration test\ngo test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run \"^TestRulerAPISharding$\"\n```\n\nEnvironment variables for integration tests:\n\n- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`)\n- `E2E_TEMP_DIR` - Directory for temporary test files\n\n## Code Formatting\n\nUse goimports with Cortex-specific import grouping:\n\n```bash\ngoimports -local github.com/cortexproject/cortex -w ./path/to/file.go\n```\n\nImport order: stdlib, third-party packages, internal Cortex packages (separated by blank lines).\n\n## Architecture\n\n### Write Path\n\n- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing\n- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks)\n\n### Read Path\n\n- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage\n- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing\n- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling\n\n### Storage\n\n- **Compactor** (stateless) - Compacts TSDB blocks in object storage\n- **Store Gateway** (semi-stateful) - Queries blocks from object storage\n\n### Optional Services\n\n- **Ruler** - Executes recording rules and alerts\n- **Alertmanager** - Multi-tenant alert routing\n- **Configs API** - Configuration management\n\n### Key Patterns\n\n- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution\n- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header\n- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift\n\n### Main Entry Points\n\n- `cmd/cortex/main.go` - Main Cortex binary\n- `pkg/cortex/cortex.go` - Service orchestration and configuration\n\n## Code Conventions\n\n- **No global variables** - Use dependency injection\n- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer\n- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case`\n- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`)\n\n## PR Requirements\n\n- Sign commits with DCO: `git commit -s -m \"message\"`\n- Run `make doc` if config/flags changed\n- Include CHANGELOG entry for user-facing changes\n\n## Investigating CI Build Failures\n\nWhen asked to investigate a CI build failure:\n\n1. **Fetch job details** using `gh api repos/cortexproject/cortex/actions/runs//jobs` to identify failed jobs and steps. Note: `gh run view --log` only works after the entire run completes, not just individual jobs.\n2. **Get annotations** using `gh api repos/cortexproject/cortex/check-runs//annotations` to surface error messages when full logs are unavailable.\n3. **Fetch full logs** once the run completes using `gh run view --job --log`.\n4. **Determine root cause** — distinguish between infrastructure failures (e.g., Docker Hub rate limits, runner issues) and code-related failures (e.g., test regressions). Use `git log` and `gh pr diff` to check if the failure relates to the PR's changes.\n5. **For flaky/infrastructure issues**, use `git log` and `git log -p` to trace when the failing code was introduced and which PR added it.\n6. **File GitHub issues** with the user's permission, including:\n - The full error output in a `
` block (since job links can expire)\n - Root cause analysis\n - Which PR introduced the issue (but do not assign or tag individuals without the user's approval)\n - Proposed solutions\n\n## Related Policies\n\nThis file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md).\n","isInternal":false,"tokens":1351,"sizeBytes":5857},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":199},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":185},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":178},{"name":".cursorrules","path":".cursorrules (snowflake-cortex-ai-cursorrules-prompt-file.mdc)","rawUrl":"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/snowflake-cortex-ai-cursorrules-prompt-file.mdc","title":"Awesome Cursorrules: snowflake cortex ai","category":"cursor-rule","format":"markdown","content":"---\ndescription: \"Cursor rules for Snowflake Cortex AI Functions (AI_COMPLETE, AI_CLASSIFY, AI_EXTRACT, etc.) and Cortex Search for RAG applications.\"\nglobs: **/*\nalwaysApply: false\n---\n// Snowflake Cortex AI\n// Expert guidance for Cortex AI Functions and Cortex Search (hybrid vector+keyword search)\n\nYou are an expert in Snowflake Cortex — the AI layer of Snowflake including Cortex AI Functions (SQL-callable LLM/ML functions) and Cortex Search (managed hybrid search for RAG applications). All processing runs inside Snowflake with no data leaving the platform.\n\n// ═══════════════════════════════════════════\n// CORTEX AI FUNCTIONS\n// ═══════════════════════════════════════════\n\n// Available Functions (use these names — they are the current versions):\n// AI_COMPLETE — General-purpose LLM completion (text, images, documents).\n// AI_CLASSIFY — Classify text/images into user-defined categories (multi-label supported).\n// AI_FILTER — Returns TRUE/FALSE for text/image input. Use in WHERE clauses.\n// AI_AGG — Aggregate insights across rows of text (no context window limit).\n// AI_EMBED — Generate embedding vectors (similarity search, clustering).\n// AI_EXTRACT — Extract structured info from text, images, or documents.\n// AI_SENTIMENT — Sentiment score from text (-1 to 1).\n// AI_SUMMARIZE_AGG — Summarize across rows (no context window limit).\n// AI_SIMILARITY — Embedding similarity between two inputs.\n// AI_TRANSCRIBE — Transcribe audio/video from stages.\n// AI_PARSE_DOCUMENT — OCR or text+layout extraction from documents in stages.\n// AI_REDACT — Redact PII from text.\n// AI_TRANSLATE — Translate between supported languages.\n\n// Helper Functions:\n// TO_FILE('@stage', 'filename') — File reference for document processing.\n// AI_COUNT_TOKENS(model, text) — Check token count before calling a model.\n// PROMPT('template {0}', arg) — Build prompt objects for AI_COMPLETE.\n// TRY_COMPLETE — Returns NULL on failure instead of error.\n\n// AI_COMPLETE — The Primary Function\n// Models: claude-4-opus, claude-4-sonnet, claude-sonnet-4-5, claude-opus-4-5, claude-haiku-4-5,\n// gemini-3-pro, llama3.1-70b, llama3.1-8b, llama3.3-70b, mistral-large2, mistral-small2, deepseek-r1\n\n// Text completion:\nSELECT AI_COMPLETE(MODEL => 'claude-4-sonnet', PROMPT => 'Summarize: ' || review_text) FROM reviews;\n\n// Document processing:\nSELECT AI_COMPLETE(\n MODEL => 'claude-4-sonnet',\n PROMPT => PROMPT('Extract the invoice total from {0}', TO_FILE('@docs', 'invoice.pdf'))\n);\n\n// Structured JSON output:\nSELECT AI_COMPLETE(MODEL => 'claude-4-sonnet',\n PROMPT => 'Extract name, email, company as JSON: ' || raw_text)::VARIANT AS extracted FROM contacts;\n\n// AI_CLASSIFY:\nSELECT AI_CLASSIFY(ticket_text, ['billing', 'technical', 'account', 'other']) AS category FROM tickets;\n// Multi-label: AI_CLASSIFY(input, categories, {'output_mode': 'multi'})\n\n// AI_FILTER (natural-language WHERE):\nSELECT * FROM reviews WHERE AI_FILTER(review_text, 'mentions product quality issues');\n\n// AI_AGG (cross-row aggregation):\nSELECT AI_AGG(feedback_text, 'What are the top 3 themes?') FROM customer_feedback;\n\n// AI_EXTRACT (entity extraction):\nSELECT AI_EXTRACT(email_body, 'meeting date', 'attendees', 'action items') FROM emails;\n\n// AI_SENTIMENT: SELECT review_text, AI_SENTIMENT(review_text) AS sentiment FROM product_reviews;\n// AI_EMBED: SELECT AI_EMBED(description) AS embedding FROM products;\n// AI_PARSE_DOCUMENT: SELECT AI_PARSE_DOCUMENT(TO_FILE('@docs', 'contract.pdf'), MODE => 'LAYOUT');\n// AI_TRANSCRIBE: SELECT AI_TRANSCRIBE(TO_FILE('@media', 'recording.mp3')) AS transcript;\n// AI_REDACT: SELECT AI_REDACT(customer_notes) AS redacted FROM support_cases;\n\n// Privileges: USE AI FUNCTIONS account privilege + SNOWFLAKE.CORTEX_USER database role (both granted to PUBLIC by default).\n\n// ═══════════════════════════════════════════\n// CORTEX SEARCH — Hybrid Vector + Keyword Search\n// ═══════════════════════════════════════════\n\n// Fully managed search combining vector (semantic) and keyword (lexical) search.\n// Use cases: RAG for LLM chatbots, enterprise search, AI-powered Q&A.\n\n// Single-index (simplest):\nCREATE OR REPLACE CORTEX SEARCH SERVICE my_search\n ON transcript_text\n ATTRIBUTES region, agent_id\n WAREHOUSE = my_wh\n TARGET_LAG = '1 day'\n EMBEDDING_MODEL = 'snowflake-arctic-embed-l-v2.0'\n AS (SELECT transcript_text, region, agent_id FROM support_transcripts);\n\n// Multi-index (text + vector on multiple columns):\nCREATE OR REPLACE CORTEX SEARCH SERVICE my_multi_search\n TEXT INDEXES transcript_text, summary\n VECTOR INDEXES transcript_text (model='snowflake-arctic-embed-l-v2.0')\n ATTRIBUTES region\n WAREHOUSE = my_wh\n TARGET_LAG = '1 hour'\n AS (SELECT transcript_text, summary, region FROM support_transcripts);\n\n// Key Parameters: ON (single-index column), TEXT INDEXES, VECTOR INDEXES, ATTRIBUTES (filter columns),\n// TARGET_LAG (freshness), EMBEDDING_MODEL, PRIMARY KEY (optimized incremental refresh).\n\n// Query — Python API (recommended for apps):\nfrom snowflake.core import Root\nroot = Root(session)\nservice = root.databases[\"db\"].schemas[\"schema\"].cortex_search_services[\"my_search\"]\nresp = service.search(\n query=\"internet connection issues\",\n columns=[\"transcript_text\", \"region\"],\n filter={\"@eq\": {\"region\": \"North America\"}},\n limit=5\n)\n\n// Query — REST API:\n// POST /api/v2/databases//schemas//cortex-search-services/:query\n// Body: {\"query\": \"...\", \"columns\": [...], \"filter\": {...}, \"limit\": N}\n\n// Filter syntax:\n// {\"@eq\": {\"region\": \"NA\"}}, {\"@contains\": {\"tags\": \"urgent\"}}, {\"@gte\": {\"score\": 0.8}}\n// {\"@and\": [f1, f2]}, {\"@or\": [f1, f2]}, {\"@not\": f}\n\n// Scoring config — adjust text vs vector vs reranker weights:\nresp = service.search(query=\"billing dispute\", columns=[\"transcript_text\"],\n scoring_config={\"weights\": {\"texts\": 0.3, \"vectors\": 0.5, \"reranker\": 0.2}}, limit=10)\n\n// RAG Pattern: 1) Search for context, 2) Pass to AI_COMPLETE:\n// results = service.search(query=question, columns=[\"content\"], limit=5)\n// SELECT AI_COMPLETE(MODEL=>'claude-4-sonnet', PROMPT=>'Answer from context: '||context||' Q: '||question);\n\n// Best Practices\n- Use AI_CLASSIFY for classification (cheaper than AI_COMPLETE).\n- Check token counts with AI_COUNT_TOKENS before large batch jobs.\n- Set PRIMARY KEY on Cortex Search for optimized incremental refresh.\n- Use ATTRIBUTES for filterable columns. Use SEARCH_PREVIEW for testing, Python/REST for production.\n- Use dedicated warehouse (no larger than MEDIUM) per search service.\n\n// Anti-Patterns\n- Do NOT use old function names (COMPLETE, CLASSIFY_TEXT, etc.) — use AI_* versions.\n- Do NOT pass entire tables through AI_COMPLETE row-by-row without cost estimation.\n- Do NOT hardcode model names without considering regional availability.\n","tokens":1770,"sizeBytes":7281}],"systemPromptSnippet":"\n\n# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nCortex is a horizontally scalable, highly available, multi-tenant, long-term storage solution for Prometheus metrics. It uses a microservices architecture with components that can run as separate processes or as a single binary.\n\n## Build Commands\n\n```bash\nmake # Build all (runs in Docker container by default)\nmake BUILD_IN_CONTAINER=false # Build locally without Docker\nmake exes # Build binaries only\nmake protos # Generate protobuf files\nmake lint # Run all linters (golangci-lint, misspell, etc.)\nmake doc # Generate config documentation (run after changing flags/config)\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image for integration tests\n```\n\n## Vendored Dependencies\n\nGo modules are vendored in the `vendor/` folder. When upgrading a dependency or component:\n\n```bash\ngo get github.com/some/dependency@version # Update go.mod\ngo mod vendor # Sync vendor folder\ngo mod tidy # Clean up go.mod/go.sum\n```\n\n**Important**: Always check the `vendor/` folder for upstream library code (e.g., `vendor/github.com/prometheus/alertmanager/` for Alertmanager internals). Do not modify vendored code directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ngo test -timeout 2400s -tags \"netgo slicelabels\" ./... # Run tests with CI configuration\n```\n\n### Integration Tests\n\nIntegration tests require Docker and the Cortex image to be built first:\n\n```bash\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image first\n\n# Run all integration tests\ngo test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...\n\n# Run a specific integration test\ngo test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run \"^TestRulerAPISharding$\"\n```\n\nEnvironment variables for integration tests:\n\n- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`)\n- `E2E_TEMP_DIR` - Directory for temporary test files\n\n## Code Formatting\n\nUse goimports with Cortex-specific import grouping:\n\n```bash\ngoimports -local github.com/cortexproject/cortex -w ./path/to/file.go\n```\n\nImport order: stdlib, third-party packages, internal Cortex packages (separated by blank lines).\n\n## Architecture\n\n### Write Path\n\n- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing\n- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks)\n\n### Read Path\n\n- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage\n- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing\n- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling\n\n### Storage\n\n- **Compactor** (stateless) - Compacts TSDB blocks in object storage\n- **Store Gateway** (semi-stateful) - Queries blocks from object storage\n\n### Optional Services\n\n- **Ruler** - Executes recording rules and alerts\n- **Alertmanager** - Multi-tenant alert routing\n- **Configs API** - Configuration management\n\n### Key Patterns\n\n- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution\n- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header\n- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift\n\n### Main Entry Points\n\n- `cmd/cortex/main.go` - Main Cortex binary\n- `pkg/cortex/cortex.go` - Service orchestration and configuration\n\n## Code Conventions\n\n- **No global variables** - Use dependency injection\n- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer\n- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case`\n- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`)\n\n## PR Requirements\n\n- Sign commits with DCO: `git commit -s -m \"message\"`\n- Run `make doc` if config/flags changed\n- Include CHANGELOG entry for user-facing changes\n\n## Investigating CI Build Failures\n\nWhen asked to investigate a CI build failure:\n\n1. **Fetch job details** using `gh api repos/cortexproject/cortex/actions/runs//jobs` to identify failed jobs and steps. Note: `gh run view --log` only works after the entire run completes, not just individual jobs.\n2. **Get annotations** using `gh api repos/cortexproject/cortex/check-runs//annotations` to surface error messages when full logs are unavailable.\n3. **Fetch full logs** once the run completes using `gh run view --job --log`.\n4. **Determine root cause** — distinguish between infrastructure failures (e.g., Docker Hub rate limits, runner issues) and code-related failures (e.g., test regressions). Use `git log` and `gh pr diff` to check if the failure relates to the PR's changes.\n5. **For flaky/infrastructure issues**, use `git log` and `git log -p` to trace when the failing code was introduced and which PR added it.\n6. **File GitHub issues** with the user's permission, including:\n - The full error output in a `
` block (since job links can expire)\n - Root cause analysis\n - Which PR introduced the issue (but do not assign or tag individuals without the user's approval)\n - Proposed solutions\n\n## Related Policies\n\nThis file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md).\n\n\n# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nCortex is a horizontally scalable, highly available, multi-tenant, long-term storage solution for Prometheus metrics. It uses a microservices architecture with components that can run as separate processes or as a single binary.\n\n## Build Commands\n\n```bash\nmake # Build all (runs in Docker container by default)\nmake BUILD_IN_CONTAINER=false # Build locally without Docker\nmake exes # Build binaries only\nmake protos # Generate protobuf files\nmake lint # Run all linters (golangci-lint, misspell, etc.)\nmake doc # Generate config documentation (run after changing flags/config)\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image for integration tests\n```\n\n## Vendored Dependencies\n\nGo modules are vendored in the `vendor/` folder. When upgrading a dependency or component:\n\n```bash\ngo get github.com/some/dependency@version # Update go.mod\ngo mod vendor # Sync vendor folder\ngo mod tidy # Clean up go.mod/go.sum\n```\n\n**Important**: Always check the `vendor/` folder for upstream library code (e.g., `vendor/github.com/prometheus/alertmanager/` for Alertmanager internals). Do not modify vendored code directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ngo test -timeout 2400s -tags \"netgo slicelabels\" ./... # Run tests with CI configuration\n```\n\n### Integration Tests\n\nIntegration tests require Docker and the Cortex image to be built first:\n\n```bash\nmake ./cmd/cortex/.uptodate # Build Cortex Docker image first\n\n# Run all integration tests\ngo test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...\n\n# Run a specific integration test\ngo test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run \"^TestRulerAPISharding$\"\n```\n\nEnvironment variables for integration tests:\n\n- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`)\n- `E2E_TEMP_DIR` - Directory for temporary test files\n\n## Code Formatting\n\nUse goimports with Cortex-specific import grouping:\n\n```bash\ngoimports -local github.com/cortexproject/cortex -w ./path/to/file.go\n```\n\nImport order: stdlib, third-party packages, internal Cortex packages (separated by blank lines).\n\n## Architecture\n\n### Write Path\n\n- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing\n- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks)\n\n### Read Path\n\n- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage\n- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing\n- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling\n\n### Storage\n\n- **Compactor** (stateless) - Compacts TSDB blocks in object storage\n- **Store Gateway** (semi-stateful) - Queries blocks from object storage\n\n### Optional Services\n\n- **Ruler** - Executes recording rules and alerts\n- **Alertmanager** - Multi-tenant alert routing\n- **Configs API** - Configuration management\n\n### Key Patterns\n\n- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution\n- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header\n- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift\n\n### Main Entry Points\n\n- `cmd/cortex/main.go` - Main Cortex binary\n- `pkg/cortex/cortex.go` - Service orchestration and configuration\n\n## Code Conventions\n\n- **No global variables** - Use dependency injection\n- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer\n- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case`\n- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`)\n\n## PR Requirements\n\n- Sign commits with DCO: `git commit -s -m \"message\"`\n- Run `make doc` if config/flags changed\n- Include CHANGELOG entry for user-facing changes\n\n## Investigating CI Build Failures\n\nWhen asked to investigate a CI build failure:\n\n1. **Fetch job details** using `gh api repos/cortexproject/cortex/actions/runs//jobs` to identify failed jobs and steps. Note: `gh run view --log` only works after the entire run completes, not just individual jobs.\n2. **Get annotations** using `gh api repos/cortexproject/cortex/check-runs//annotations` to surface error messages when full logs are unavailable.\n3. **Fetch full logs** once the run completes using `gh run view --job --log`.\n4. **Determine root cause** — distinguish between infrastructure failures (e.g., Docker Hub rate limits, runner issues) and code-related failures (e.g., test regressions). Use `git log` and `gh pr diff` to check if the failure relates to the PR's changes.\n5. **For flaky/infrastructure issues**, use `git log` and `git log -p` to trace when the failing code was introduced and which PR added it.\n6. **File GitHub issues** with the user's permission, including:\n - The full error output in a `
` block (since job links can expire)\n - Root cause analysis\n - Which PR introduced the issue (but do not assign or tag individuals without the user's approval)\n - Proposed solutions\n\n## Related Policies\n\nThis file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md).\n\n\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.claude-plugin/marketplace.json)\n\n\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.claude-plugin/plugin.json)\n\n\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/cortexproject/cortex/HEAD/.cursor/mcp.json)\n\n\n---\ndescription: \"Cursor rules for Snowflake Cortex AI Functions (AI_COMPLETE, AI_CLASSIFY, AI_EXTRACT, etc.) and Cortex Search for RAG applications.\"\nglobs: **/*\nalwaysApply: false\n---\n// Snowflake Cortex AI\n// Expert guidance for Cortex AI Functions and Cortex Search (hybrid vector+keyword search)\n\nYou are an expert in Snowflake Cortex — the AI layer of Snowflake including Cortex AI Functions (SQL-callable LLM/ML functions) and Cortex Search (managed hybrid search for RAG applications). All processing runs inside Snowflake with no data leaving the platform.\n\n// ═══════════════════════════════════════════\n// CORTEX AI FUNCTIONS\n// ═══════════════════════════════════════════\n\n// Available Functions (use these names — they are the current versions):\n// AI_COMPLETE — General-purpose LLM completion (text, images, documents).\n// AI_CLASSIFY — Classify text/images into user-defined categories (multi-label supported).\n// AI_FILTER — Returns TRUE/FALSE for text/image input. Use in WHERE clauses.\n// AI_AGG — Aggregate insights across rows of text (no context window limit).\n// AI_EMBED — Generate embedding vectors (similarity search, clustering).\n// AI_EXTRACT — Extract structured info from text, images, or documents.\n// AI_SENTIMENT — Sentiment score from text (-1 to 1).\n// AI_SUMMARIZE_AGG — Summarize across rows (no context window limit).\n// AI_SIMILARITY — Embedding similarity between two inputs.\n// AI_TRANSCRIBE — Transcribe audio/video from stages.\n// AI_PARSE_DOCUMENT — OCR or text+layout extraction from documents in stages.\n// AI_REDACT — Redact PII from text.\n// AI_TRANSLATE — Translate between supported languages.\n\n// Helper Functions:\n// TO_FILE('@stage', 'filename') — File reference for document processing.\n// AI_COUNT_TOKENS(model, text) — Check token count before calling a model.\n// PROMPT('template {0}', arg) — Build prompt objects for AI_COMPLETE.\n// TRY_COMPLETE — Returns NULL on failure instead of error.\n\n// AI_COMPLETE — The Primary Function\n// Models: claude-4-opus, claude-4-sonnet, claude-sonnet-4-5, claude-opus-4-5, claude-haiku-4-5,\n// gemini-3-pro, llama3.1-70b, llama3.1-8b, llama3.3-70b, mistral-large2, mistral-small2, deepseek-r1\n\n// Text completion:\nSELECT AI_COMPLETE(MODEL => 'claude-4-sonnet', PROMPT => 'Summarize: ' || review_text) FROM reviews;\n\n// Document processing:\nSELECT AI_COMPLETE(\n MODEL => 'claude-4-sonnet',\n PROMPT => PROMPT('Extract the invoice total from {0}', TO_FILE('@docs', 'invoice.pdf'))\n);\n\n// Structured JSON output:\nSELECT AI_COMPLETE(MODEL => 'claude-4-sonnet',\n PROMPT => 'Extract name, email, company as JSON: ' || raw_text)::VARIANT AS extracted FROM contacts;\n\n// AI_CLASSIFY:\nSELECT AI_CLASSIFY(ticket_text, ['billing', 'technical', 'account', 'other']) AS category FROM tickets;\n// Multi-label: AI_CLASSIFY(input, categories, {'output_mode': 'multi'})\n\n// AI_FILTER (natural-language WHERE):\nSELECT * FROM reviews WHERE AI_FILTER(review_text, 'mentions product quality issues');\n\n// AI_AGG (cross-row aggregation):\nSELECT AI_AGG(feedback_text, 'What are the top 3 themes?') FROM customer_feedback;\n\n// AI_EXTRACT (entity extraction):\nSELECT AI_EXTRACT(email_body, 'meeting date', 'attendees', 'action items') FROM emails;\n\n// AI_SENTIMENT: SELECT review_text, AI_SENTIMENT(review_text) AS sentiment FROM product_reviews;\n// AI_EMBED: SELECT AI_EMBED(description) AS embedding FROM products;\n// AI_PARSE_DOCUMENT: SELECT AI_PARSE_DOCUMENT(TO_FILE('@docs', 'contract.pdf'), MODE => 'LAYOUT');\n// AI_TRANSCRIBE: SELECT AI_TRANSCRIBE(TO_FILE('@media', 'recording.mp3')) AS transcript;\n// AI_REDACT: SELECT AI_REDACT(customer_notes) AS redacted FROM support_cases;\n\n// Privileges: USE AI FUNCTIONS account privilege + SNOWFLAKE.CORTEX_USER database role (both granted to PUBLIC by default).\n\n// ═══════════════════════════════════════════\n// CORTEX SEARCH — Hybrid Vector + Keyword Search\n// ═══════════════════════════════════════════\n\n// Fully managed search combining vector (semantic) and keyword (lexical) search.\n// Use cases: RAG for LLM chatbots, enterprise search, AI-powered Q&A.\n\n// Single-index (simplest):\nCREATE OR REPLACE CORTEX SEARCH SERVICE my_search\n ON transcript_text\n ATTRIBUTES region, agent_id\n WAREHOUSE = my_wh\n TARGET_LAG = '1 day'\n EMBEDDING_MODEL = 'snowflake-arctic-embed-l-v2.0'\n AS (SELECT transcript_text, region, agent_id FROM support_transcripts);\n\n// Multi-index (text + vector on multiple columns):\nCREATE OR REPLACE CORTEX SEARCH SERVICE my_multi_search\n TEXT INDEXES transcript_text, summary\n VECTOR INDEXES transcript_text (model='snowflake-arctic-embed-l-v2.0')\n ATTRIBUTES region\n WAREHOUSE = my_wh\n TARGET_LAG = '1 hour'\n AS (SELECT transcript_text, summary, region FROM support_transcripts);\n\n// Key Parameters: ON (single-index column), TEXT INDEXES, VECTOR INDEXES, ATTRIBUTES (filter columns),\n// TARGET_LAG (freshness), EMBEDDING_MODEL, PRIMARY KEY (optimized incremental refresh).\n\n// Query — Python API (recommended for apps):\nfrom snowflake.core import Root\nroot = Root(session)\nservice = root.databases[\"db\"].schemas[\"schema\"].cortex_search_services[\"my_search\"]\nresp = service.search(\n query=\"internet connection issues\",\n columns=[\"transcript_text\", \"region\"],\n filter={\"@eq\": {\"region\": \"North America\"}},\n limit=5\n)\n\n// Query — REST API:\n// POST /api/v2/databases//schemas//cortex-search-services/:query\n// Body: {\"query\": \"...\", \"columns\": [...], \"filter\": {...}, \"limit\": N}\n\n// Filter syntax:\n// {\"@eq\": {\"region\": \"NA\"}}, {\"@contains\": {\"tags\": \"urgent\"}}, {\"@gte\": {\"score\": 0.8}}\n// {\"@and\": [f1, f2]}, {\"@or\": [f1, f2]}, {\"@not\": f}\n\n// Scoring config — adjust text vs vector vs reranker weights:\nresp = service.search(query=\"billing dispute\", columns=[\"transcript_text\"],\n scoring_config={\"weights\": {\"texts\": 0.3, \"vectors\": 0.5, \"reranker\": 0.2}}, limit=10)\n\n// RAG Pattern: 1) Search for context, 2) Pass to AI_COMPLETE:\n// results = service.search(query=question, columns=[\"content\"], limit=5)\n// SELECT AI_COMPLETE(MODEL=>'claude-4-sonnet', PROMPT=>'Answer from context: '||context||' Q: '||question);\n\n// Best Practices\n- Use AI_CLASSIFY for classification (cheaper than AI_COMPLETE).\n- Check token counts with AI_COUNT_TOKENS before large batch jobs.\n- Set PRIMARY KEY on Cortex Search for optimized incremental refresh.\n- Use ATTRIBUTES for filterable columns. Use SEARCH_PREVIEW for testing, Python/REST for production.\n- Use dedicated warehouse (no larger than MEDIUM) per search service.\n\n// Anti-Patterns\n- Do NOT use old function names (COMPLETE, CLASSIFY_TEXT, etc.) — use AI_* versions.\n- Do NOT pass entire tables through AI_COMPLETE row-by-row without cost estimation.\n- Do NOT hardcode model names without considering regional availability.\n"}