Step-by-Step: How to Build a RAG System for Jira Ticket Search Using LlamaIndex 0.10 and Atlassian API 3.0

{\n  \"results\": [\n    {\n      \"ticket_key\": \"PAY-1234\",\n      \"summary\": \"Login timeout for users with 2FA enabled\",\n      \"status\": \"Done\",\n      \"priority\": \"High\",\n      \"created\": \"2023-08-15T10:23:00.000Z\",\n      \"url\": \"https://your-domain.atlassian.net/browse/PAY-1234\",\n      \"score\": 0.92\n    },\n    {\n      \"ticket_key\": \"PAY-1189\",\n      \"summary\": \"Session expiry set to 5 minutes for EU users\",\n      \"status\": \"Done\",\n      \"priority\": \"Medium\",\n      \"created\": \"2023-07-02T14:12:00.000Z\",\n      \"url\": \"https://your-domain.atlassian.net/browse/PAY-1189\",\n      \"score\": 0.87\n    }\n  ],\n  \"total\": 2\n}

pip install llama-index==0.10.12 requests fastapi uvicorn python-dotenv huggingface-hub llama-index-embeddings-huggingface

curl -u \"your-email@domain.com:your-api-token\" \"https://your-domain.atlassian.net/rest/api/3/search?jql=project=PAY&maxResults=1\"

JIRA_DOMAIN=https://your-domain.atlassian.net\nJIRA_EMAIL=your-email@domain.com\nJIRA_API_TOKEN=your-api-token

import os\nimport requests\nimport json\nimport time\nfrom typing import List, Dict, Optional\nimport logging\n\n# Configure logging for audit trails and debugging\nlogging.basicConfig(\n    level=logging.INFO,\n    format=\"%(asctime)s - %(levelname)s - %(message)s\"\n)\nlogger = logging.getLogger(__name__)\n\nclass JiraApiClient:\n    \"\"\"Wrapper for Atlassian API 3.0 Jira endpoints with rate limit handling\"\"\"\n    \n    def __init__(self, domain: str, email: str, api_token: str):\n        self.domain = domain.rstrip(\"/\")  # Remove trailing slash to avoid double slashes\n        self.email = email\n        self.api_token = api_token\n        self.base_url = f\"{self.domain}/rest/api/3\"\n        self.session = requests.Session()\n        # Set auth header for all requests\n        self.session.auth = (self.email, self.api_token)\n        self.session.headers.update({\n            \"Accept\": \"application/json\",\n            \"Content-Type\": \"application/json\"\n        })\n        self.rate_limit_remaining = 1000  # Default from Atlassian docs\n        self.rate_limit_reset = 0  # Unix timestamp for rate limit reset\n        \n    def _handle_rate_limit(self, response: requests.Response) -> None:\n        \"\"\"Check rate limit headers and sleep if needed\"\"\"\n        if \"X-RateLimit-Remaining\" in response.headers:\n            self.rate_limit_remaining = int(response.headers[\"X-RateLimit-Remaining\"])\n        if \"X-RateLimit-Reset\" in response.headers:\n            self.rate_limit_reset = int(response.headers[\"X-RateLimit-Reset\"])\n        \n        if response.status_code == 429:\n            retry_after = int(response.headers.get(\"Retry-After\", 60))\n            logger.warning(f\"Rate limited. Sleeping for {retry_after} seconds\")\n            time.sleep(retry_after)\n            # Retry the request after sleeping\n            return True\n        return False\n    \n    def search_tickets(self, jql: str, max_results: int = 1000, fields: Optional[List[str]] = None) -> List[Dict]:\n        \"\"\"\n        Search Jira tickets using JQL via Atlassian API 3.0 search endpoint.\n        Handles pagination automatically up to max_results.\n        \"\"\"\n        if fields is None:\n            fields = [\"key\", \"summary\", \"description\", \"status\", \"priority\", \"created\", \"updated\", \"assignee\", \"labels\"]\n        \n        all_tickets = []\n        start_at = 0\n        batch_size = 100  # API 3.0 max per request\n        \n        while len(all_tickets) < max_results:\n            params = {\n                \"jql\": jql,\n                \"startAt\": start_at,\n                \"maxResults\": min(batch_size, max_results - len(all_tickets)),\n                \"fields\": \",\".join(fields)\n            }\n            \n            try:\n                response = self.session.get(f\"{self.base_url}/search\", params=params)\n                # Handle rate limiting\n                if self._handle_rate_limit(response):\n                    continue\n                response.raise_for_status()\n                data = response.json()\n                batch_tickets = data.get(\"issues\", [])\n                all_tickets.extend(batch_tickets)\n                logger.info(f\"Fetched {len(batch_tickets)} tickets. Total: {len(all_tickets)}\")\n                \n                if len(batch_tickets) < batch_size:\n                    break  # No more results\n                start_at += batch_size\n                \n            except requests.exceptions.HTTPError as e:\n                if e.response.status_code == 401:\n                    logger.error(\"Invalid API credentials. Check email and API token.\")\n                    raise\n                elif e.response.status_code == 403:\n                    logger.error(\"Insufficient permissions. Ensure API token has 'Read Jira' scope.\")\n                    raise\n                else:\n                    logger.error(f\"HTTP error: {e}\")\n                    raise\n            except Exception as e:\n                logger.error(f\"Unexpected error fetching tickets: {e}\")\n                raise\n        \n        logger.info(f\"Total tickets fetched: {len(all_tickets)}\")\n        return all_tickets

import json\nimport logging\nfrom typing import List, Dict\nfrom llama_index.core import Document, VectorStoreIndex, Settings\nfrom llama_index.core.node_parser import SentenceSplitter\nfrom llama_index.embeddings.huggingface import HuggingFaceEmbedding\nimport sys\nsys.path.append(\"./src\")  # Add src to path for JiraClient import\nfrom jira_client import JiraApiClient  # Import our earlier client\n\n# Configure logging\nlogging.basicConfig(level=logging.INFO)\nlogger = logging.getLogger(__name__)\n\nclass JiraRagIngestor:\n    \"\"\"Ingests Jira tickets into LlamaIndex 0.10 VectorStoreIndex\"\"\"\n    \n    def __init__(self, jira_client: JiraApiClient, model_name: str = \"BAAI/bge-small-en-v1.5\"):\n        # Configure LlamaIndex 0.10 settings\n        Settings.embed_model = HuggingFaceEmbedding(model_name=model_name)\n        Settings.node_parser = SentenceSplitter(chunk_size=512, chunk_overlap=64)\n        Settings.num_output = 1024\n        self.jira_client = jira_client\n        self.index = None\n        \n    def _ticket_to_document(self, ticket: Dict) -> Document:\n        \"\"\"Convert raw Jira ticket JSON to LlamaIndex Document with metadata\"\"\"\n        # Extract core fields, handle missing values\n        key = ticket.get(\"key\", \"UNKNOWN\")\n        summary = ticket.get(\"fields\", {}).get(\"summary\", \"\")\n        description = ticket.get(\"fields\", {}).get(\"description\", \"\")\n        if not description:\n            description = \"No description provided.\"\n        # Combine summary and description for embedding\n        text = f\"Ticket Key: {key}\nSummary: {summary}
Description: {description}\"\n        \n        # Extract metadata for filtering\n        metadata = {\n            \"ticket_key\": key,\n            \"summary\": summary,\n            \"status\": ticket.get(\"fields\", {}).get(\"status\", {}).get(\"name\", \"Unknown\"),\n            \"priority\": ticket.get(\"fields\", {}).get(\"priority\", {}).get(\"name\", \"Unknown\"),\n            \"created\": ticket.get(\"fields\", {}).get(\"created\", \"\"),\n            \"updated\": ticket.get(\"fields\", {}).get(\"updated\", \"\"),\n            \"assignee\": ticket.get(\"fields\", {}).get(\"assignee\", {}).get(\"displayName\", \"Unassigned\"),\n            \"labels\": ticket.get(\"fields\", {}).get(\"labels\", [])\n        }\n        return Document(text=text, metadata=metadata)\n    \n    def ingest(self, jql: str, persist_dir: str = \"./jira_rag_index\") -> VectorStoreIndex:\n        \"\"\"\n        Ingest tickets matching JQL into VectorStoreIndex, persist to disk.\n        \"\"\"\n        logger.info(f\"Fetching tickets with JQL: {jql}\")\n        try:\n            tickets = self.jira_client.search_tickets(jql, max_results=10000)\n        except Exception as e:\n            logger.error(f\"Failed to fetch tickets: {e}\")\n            raise\n        \n        logger.info(f\"Converting {len(tickets)} tickets to Documents\")\n        documents = [self._ticket_to_document(t) for t in tickets]\n        \n        logger.info(\"Building VectorStoreIndex\")\n        try:\n            self.index = VectorStoreIndex.from_documents(documents, show_progress=True)\n            # Persist index to disk to avoid re-ingestion\n            self.index.storage_context.persist(persist_dir)\n            logger.info(f\"Index persisted to {persist_dir}\")\n        except Exception as e:\n            logger.error(f\"Failed to build index: {e}\")\n            raise\n        \n        return self.index\n    \n    def load_existing_index(self, persist_dir: str = \"./jira_rag_index\") -> VectorStoreIndex:\n        \"\"\"Load persisted index from disk\"\"\"\n        try:\n            from llama_index.core import StorageContext, load_index_from_storage\n            storage_context = StorageContext.from_defaults(persist_dir=persist_dir)\n            self.index = load_index_from_storage(storage_context)\n            logger.info(f\"Loaded existing index from {persist_dir}\")\n            return self.index\n        except Exception as e:\n            logger.error(f\"Failed to load index: {e}\")\n            raise

import os\nimport logging\nfrom typing import List, Dict, Optional\nfrom fastapi import FastAPI, HTTPException, Query\nfrom fastapi.middleware.cors import CORSMiddleware\nfrom pydantic import BaseModel\nfrom llama_index.core import VectorStoreIndex, Settings\nfrom llama_index.core.query_engine import RetrieverQueryEngine\nfrom llama_index.core.retrievers import VectorIndexRetriever\nfrom llama_index.core.postprocessor import SimilarityPostprocessor\nimport sys\nsys.path.append(\"./src\")\nfrom ingest import JiraRagIngestor  # Import our ingestor\nfrom jira_client import JiraApiClient\n\n# Configure logging\nlogging.basicConfig(level=logging.INFO)\nlogger = logging.getLogger(__name__)\n\n# Initialize FastAPI app\napp = FastAPI(title=\"Jira RAG Search API\", version=\"1.0.0\")\n\n# Configure CORS for frontend access\napp.add_middleware(\n    CORSMiddleware,\n    allow_origins=[\"*\"],  # Restrict in production\n    allow_credentials=True,\n    allow_methods=[\"*\"],\n    allow_headers=[\"*\"]\n)\n\n# Request/Response models\nclass SearchQuery(BaseModel):\n    query: str\n    top_k: int = 5\n    similarity_cutoff: float = 0.7\n\nclass TicketResult(BaseModel):\n    ticket_key: str\n    summary: str\n    status: str\n    priority: str\n    created: str\n    url: str\n    score: float\n\nclass SearchResponse(BaseModel):\n    results: List[TicketResult]\n    total: int\n\n# Global variables for index and query engine\nindex = None\nquery_engine = None\n\n@app.on_event(\"startup\")\nasync def startup_event():\n    \"\"\"Load or build index on startup\"\"\"\n    global index, query_engine\n    logger.info(\"Starting up Jira RAG API\")\n    \n    # Initialize Jira client from env vars\n    jira_domain = os.getenv(\"JIRA_DOMAIN\")\n    jira_email = os.getenv(\"JIRA_EMAIL\")\n    jira_token = os.getenv(\"JIRA_API_TOKEN\")\n    \n    if not all([jira_domain, jira_email, jira_token]):\n        logger.error(\"Missing Jira env vars: JIRA_DOMAIN, JIRA_EMAIL, JIRA_API_TOKEN\")\n        raise RuntimeError(\"Missing Jira credentials\")\n    \n    jira_client = JiraApiClient(\n        domain=jira_domain,\n        email=jira_email,\n        api_token=jira_token\n    )\n    \n    ingestor = JiraRagIngestor(jira_client)\n    \n    # Try to load existing index, else build new one\n    try:\n        index = ingestor.load_existing_index()\n    except Exception as e:\n        logger.warning(f\"No existing index found: {e}. Building new index...\")\n        # Ingest last 6 months of tickets by default\n        jql = \"created >= -26w ORDER BY created DESC\"\n        index = ingestor.ingest(jql)\n    \n    # Configure query engine\n    retriever = VectorIndexRetriever(index=index, similarity_top_k=10)\n    postprocessor = SimilarityPostprocessor(similarity_cutoff=0.6)\n    query_engine = RetrieverQueryEngine(\n        retriever=retriever,\n        node_postprocessors=[postprocessor]\n    )\n    logger.info(\"Startup complete. Query engine ready.\")\n\n@app.post(\"/search\", response_model=SearchResponse)\nasync def search_tickets(query: SearchQuery):\n    \"\"\"Search Jira tickets using natural language query\"\"\"\n    global query_engine\n    if not query_engine:\n        raise HTTPException(status_code=503, detail=\"Query engine not initialized\")\n    \n    try:\n        # Execute query\n        response = query_engine.query(query.query)\n        # Parse response nodes into results\n        results = []\n        for node in response.source_nodes:\n            if node.score < query.similarity_cutoff:\n                continue\n            metadata = node.metadata\n            ticket_key = metadata.get(\"ticket_key\")\n            results.append(TicketResult(\n                ticket_key=ticket_key,\n                summary=metadata.get(\"summary\", \"\"),\n                status=metadata.get(\"status\", \"Unknown\"),\n                priority=metadata.get(\"priority\", \"Unknown\"),\n                created=metadata.get(\"created\", \"\"),\n                url=f\"{os.getenv('JIRA_DOMAIN')}/browse/{ticket_key}\",\n                score=round(node.score, 4)\n            ))\n        # Limit to top_k\n        results = results[:query.top_k]\n        return SearchResponse(results=results, total=len(results))\n    except Exception as e:\n        logger.error(f\"Search error: {e}\")\n        raise HTTPException(status_code=500, detail=str(e))\n\nif __name__ == \"__main__\":\n    import uvicorn\n    uvicorn.run(app, host=\"0.0.0.0\", port=8000)

from llama_index.core.node_parser import MarkdownNodeParser\nSettings.node_parser = MarkdownNodeParser(chunk_size=512, chunk_overlap=64)

from llama_index.core.cache import RedisCache\nfrom llama_index.core import Settings\nimport redis\n\n# Connect to Redis\nredis_client = redis.Redis(host=\"localhost\", port=6379, db=0)\nSettings.cache = RedisCache(redis_client=redis_client, ttl=3600)

from opentelemetry.instrumentation.llamaindex import LlamaIndexInstrumentor\nfrom opentelemetry import metrics\nfrom opentelemetry.sdk.metrics import MeterProvider\nfrom opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader\nfrom opentelemetry.exporter.prometheus import PrometheusMetricReader\n\n# Set up Prometheus exporter\nreader = PrometheusMetricReader()\nprovider = MeterProvider(metric_readers=[reader])\nmetrics.set_meter_provider(provider)\n\n# Instrument LlamaIndex\nLlamaIndexInstrumentor().instrument()

jira-rag-llamaindex/\n├── src/\n│   ├── jira_client.py       # Atlassian API 3.0 client\n│   ├── ingest.py            # LlamaIndex 0.10 ingestion logic\n│   └── api.py               # FastAPI query endpoint\n├── tests/\n│   ├── test_jira_client.py\n│   ├── test_ingest.py\n│   └── test_api.py\n├── .env.example             # Environment variable template\n├── requirements.txt         # Python dependencies\n├── docker-compose.yml       # Local dev environment\n└── README.md                # Setup instructions