{"_id":"@arroyc/project-status-report-agent","_rev":"5-b7fdd7bd65d7de9cd51a5d7f2f2e9e75","name":"@arroyc/project-status-report-agent","dist-tags":{"latest":"1.3.2"},"versions":{"1.1.0":{"name":"@arroyc/project-status-report-agent","version":"1.1.0","keywords":["azure-devops","project-status","report-generator","llm","openai","ollama","cli"],"license":"MIT","_id":"@arroyc/project-status-report-agent@1.1.0","maintainers":[{"name":"arroyc2026","email":"roychoudhury.arjun@gmail.com"}],"homepage":"https://github.com/arroyc/ado-project-reporter#readme","bugs":{"url":"https://github.com/arroyc/ado-project-reporter/issues"},"bin":{"psr-agent":"dist/index.js"},"dist":{"shasum":"8978f30715b3f1059027840c8d379690a4dacb80","tarball":"https://registry.npmjs.org/@arroyc/project-status-report-agent/-/project-status-report-agent-1.1.0.tgz","fileCount":54,"integrity":"sha512-fMs0yBnLfeU2Z7V8QsVGpPjz1rcx8M/cyOgPw676D2Vcj4zS2571GWfQZIazFOeTlYId80RayjFsMffimDdGHg==","signatures":[{"sig":"MEUCIQCk2fr3oDh10czZzOPiN3ME6Cu9fkxzZHKKrZpbP/vXSAIgSMVtrSFHU1PUePqu6D8LlaGERk2LrkfZa8L4b/gIZ2c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":288727},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"64e4657b0777ab178ec56a417026a9c5f63ec878","scripts":{"lint":"eslint src/ test/","test":"vitest run --exclude 'test/e2e/**'","build":"tsc","start":"node dist/index.js","test:e2e":"vitest run --dir test/e2e","test:watch":"vitest --exclude 'test/e2e/**'","audit:check":"npm audit --omit=dev --audit-level=high","start:static":"node dist/index.js --static","test:coverage":"vitest run --coverage --exclude 'test/e2e/**'","prepublishOnly":"npm run build"},"_npmUser":{"name":"arroyc2026","email":"roychoudhury.arjun@gmail.com"},"repository":{"url":"git+https://github.com/arroyc/ado-project-reporter.git","type":"git"},"_npmVersion":"11.9.0","description":"AI-powered Project Status Report Agent — fetches Azure DevOps data, generates LLM-summarized reports","directories":{},"_nodeVersion":"24.14.0","dependencies":{"dotenv":"^16.4.7","openai":"^4.86.2","azure-devops-node-api":"^14.1.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.0.3","vitest":"^3.0.0","@eslint/js":"^10.0.1","typescript":"^5.7.0","@types/node":"^22.0.0","typescript-eslint":"^8.56.1","@vitest/coverage-v8":"^3.2.4","@bradygaster/squad-cli":"^0.8.20"},"_npmOperationalInternal":{"tmp":"tmp/project-status-report-agent_1.1.0_1772883414066_0.9161615228607407","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@arroyc/project-status-report-agent","version":"1.2.0","keywords":["azure-devops","project-status","report-generator","llm","openai","ollama","cli"],"license":"MIT","_id":"@arroyc/project-status-report-agent@1.2.0","maintainers":[{"name":"arroyc2026","email":"roychoudhury.arjun@gmail.com"}],"homepage":"https://github.com/arroyc/ado-project-reporter#readme","bugs":{"url":"https://github.com/arroyc/ado-project-reporter/issues"},"bin":{"psr-agent":"dist/index.js"},"dist":{"shasum":"038647ef73a2acb97e0b18d5a4337dc8f2a63cd6","tarball":"https://registry.npmjs.org/@arroyc/project-status-report-agent/-/project-status-report-agent-1.2.0.tgz","fileCount":57,"integrity":"sha512-0oap0poHsJgmXcl3v61FP9JYwWN6B7oXwHvWGwRxMGt4UyTz9ypdmJlbF8DxKpsf1pn9xgXGP68IqnCuGLOCOQ==","signatures":[{"sig":"MEUCIQD7l9ey99lCa5+6T5f4y+E7f2vqP47PaMrmKTDlUmO2rgIgOSs7PmHWbLoca40jtO6i+WrDKi0gIFzaf4k5W5KLqjo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":306940},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"878f36974c7a59e30396d47fc56cd82c048cc1d1","scripts":{"lint":"eslint src/ test/","test":"vitest run --exclude 'test/e2e/**'","build":"tsc","start":"node dist/index.js","test:e2e":"vitest run --dir test/e2e","test:watch":"vitest --exclude 'test/e2e/**'","audit:check":"npm audit --omit=dev --audit-level=high","postinstall":"node scripts/postinstall.js","start:static":"node dist/index.js --static","test:coverage":"vitest run --coverage --exclude 'test/e2e/**'","prepublishOnly":"npm run build"},"_npmUser":{"name":"arroyc2026","email":"roychoudhury.arjun@gmail.com"},"repository":{"url":"git+https://github.com/arroyc/ado-project-reporter.git","type":"git"},"_npmVersion":"11.9.0","description":"AI-powered Project Status Report Agent — fetches Azure DevOps data, generates LLM-summarized reports","directories":{},"_nodeVersion":"24.14.0","dependencies":{"dotenv":"^16.4.7","openai":"^4.86.2","azure-devops-node-api":"^14.1.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.0.3","vitest":"^3.0.0","@eslint/js":"^10.0.1","typescript":"^5.7.0","@types/node":"^22.0.0","typescript-eslint":"^8.56.1","@vitest/coverage-v8":"^3.2.4","@bradygaster/squad-cli":"^0.8.25"},"_npmOperationalInternal":{"tmp":"tmp/project-status-report-agent_1.2.0_1773025513375_0.7829242071152747","host":"s3://npm-registry-packages-npm-production"}},"1.3.0":{"name":"@arroyc/project-status-report-agent","version":"1.3.0","keywords":["azure-devops","project-status","report-generator","llm","openai","ollama","cli"],"license":"MIT","_id":"@arroyc/project-status-report-agent@1.3.0","maintainers":[{"name":"arroyc2026","email":"roychoudhury.arjun@gmail.com"}],"homepage":"https://github.com/arroyc/ado-project-reporter#readme","bugs":{"url":"https://github.com/arroyc/ado-project-reporter/issues"},"bin":{"psr-agent":"dist/index.js","psr-agent-setup":"dist/setup-cli.js"},"dist":{"shasum":"dfd419057b03ce2614e567a0e04e0052b0bd100f","tarball":"https://registry.npmjs.org/@arroyc/project-status-report-agent/-/project-status-report-agent-1.3.0.tgz","fileCount":65,"integrity":"sha512-lNvntawC2krS1uTndn6rD6OR1kQwdzA1Fd1nGv2PhIR9bj3vUYIJD+0jqFbQfQ/5gmce+6WGuQzYihgP7f0bcw==","signatures":[{"sig":"MEUCIQDaChyUJQaQ8+Hkm0ir76/zIJCXcAFBP/mOQZLn18MgvQIgepjWQTXE65vLTOQBQiruoWPTzE4vJypqcKvrG8OhKr4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":320178},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"471c18d18163b38a764fc75b0b2a46c38e2f2b01","scripts":{"lint":"eslint src/ test/","test":"vitest run --exclude 'test/e2e/**'","build":"tsc","start":"node dist/index.js","test:e2e":"vitest run --dir test/e2e","test:watch":"vitest --exclude 'test/e2e/**'","audit:check":"npm audit --omit=dev --audit-level=high","postinstall":"node scripts/postinstall.js","start:static":"node dist/index.js --static","test:coverage":"vitest run --coverage --exclude 'test/e2e/**'","prepublishOnly":"npm run build"},"_npmUser":{"name":"arroyc2026","email":"roychoudhury.arjun@gmail.com"},"repository":{"url":"git+https://github.com/arroyc/ado-project-reporter.git","type":"git"},"_npmVersion":"11.9.0","description":"AI-powered Project Status Report Agent — fetches Azure DevOps data, generates LLM-summarized reports","directories":{},"_nodeVersion":"24.14.0","dependencies":{"dotenv":"^16.4.7","ollama":"^0.6.3","openai":"^4.86.2","azure-devops-node-api":"^14.1.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.0.3","vitest":"^3.0.0","@eslint/js":"^10.0.1","typescript":"^5.7.0","@types/node":"^22.0.0","typescript-eslint":"^8.56.1","@vitest/coverage-v8":"^3.2.4","@bradygaster/squad-cli":"^0.8.25"},"_npmOperationalInternal":{"tmp":"tmp/project-status-report-agent_1.3.0_1773035573294_0.05974557131226432","host":"s3://npm-registry-packages-npm-production"}},"1.3.1":{"name":"@arroyc/project-status-report-agent","version":"1.3.1","keywords":["azure-devops","project-status","report-generator","llm","openai","ollama","cli"],"license":"MIT","_id":"@arroyc/project-status-report-agent@1.3.1","maintainers":[{"name":"arroyc2026","email":"roychoudhury.arjun@gmail.com"}],"homepage":"https://github.com/arroyc/ado-project-reporter#readme","bugs":{"url":"https://github.com/arroyc/ado-project-reporter/issues"},"bin":{"psr-agent":"dist/index.js","psr-agent-setup":"dist/setup-cli.js"},"dist":{"shasum":"e097b0d9d23784cfce2572f057df0321c2f2bffd","tarball":"https://registry.npmjs.org/@arroyc/project-status-report-agent/-/project-status-report-agent-1.3.1.tgz","fileCount":65,"integrity":"sha512-RSKCbp2x8nCXjrA3qFd9Nr8DufH1ty5nFcBK3oe1UTFyeDMIXUyhO5GL0wo2j5fvkt64pcKSo9jptekbjWeNZg==","signatures":[{"sig":"MEUCIQCzDLSGtHjXBM3oENubA1A8KJIHlGC55kbX+FfsY6p3nQIgG9lN9dklcMHJ/uIZU5VkZ7UMdGeesWTwQXDcrkhG4Qw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":324570},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"aec512a118961fe814c0824d0f7be6bdde585f5d","scripts":{"lint":"eslint src/ test/","test":"vitest run --exclude 'test/e2e/**'","build":"tsc","start":"node dist/index.js","test:e2e":"vitest run --dir test/e2e","test:watch":"vitest --exclude 'test/e2e/**'","audit:check":"npm audit --omit=dev --audit-level=high","postinstall":"node scripts/postinstall.js","start:static":"node dist/index.js --static","test:coverage":"vitest run --coverage --exclude 'test/e2e/**'","prepublishOnly":"npm run build"},"_npmUser":{"name":"arroyc2026","email":"roychoudhury.arjun@gmail.com"},"repository":{"url":"git+https://github.com/arroyc/ado-project-reporter.git","type":"git"},"_npmVersion":"11.9.0","description":"AI-powered Project Status Report Agent — fetches Azure DevOps data, generates LLM-summarized reports","directories":{},"_nodeVersion":"24.14.0","dependencies":{"dotenv":"^16.4.7","ollama":"^0.6.3","openai":"^4.86.2","azure-devops-node-api":"^14.1.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.0.3","vitest":"^3.0.0","@eslint/js":"^10.0.1","typescript":"^5.7.0","@types/node":"^22.0.0","typescript-eslint":"^8.56.1","@vitest/coverage-v8":"^3.2.4","@bradygaster/squad-cli":"^0.8.25"},"_npmOperationalInternal":{"tmp":"tmp/project-status-report-agent_1.3.1_1773042114654_0.15025363829467864","host":"s3://npm-registry-packages-npm-production"}},"1.3.2":{"name":"@arroyc/project-status-report-agent","version":"1.3.2","description":"AI-powered Project Status Report Agent — fetches Azure DevOps data, generates LLM-summarized reports","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"bin":{"psr-agent":"dist/index.js","psr-agent-setup":"dist/setup-cli.js"},"scripts":{"postinstall":"node scripts/postinstall.js","build":"tsc","start":"node dist/index.js","start:static":"node dist/index.js --static","lint":"eslint src/ test/","audit:check":"npm audit --omit=dev --audit-level=high","test":"vitest run --exclude 'test/e2e/**'","test:watch":"vitest --exclude 'test/e2e/**'","test:coverage":"vitest run --coverage --exclude 'test/e2e/**'","test:e2e":"vitest run --dir test/e2e","prepublishOnly":"npm run build"},"keywords":["azure-devops","project-status","report-generator","llm","openai","ollama","cli"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/arroyc/ado-project-reporter.git"},"homepage":"https://github.com/arroyc/ado-project-reporter#readme","bugs":{"url":"https://github.com/arroyc/ado-project-reporter/issues"},"engines":{"node":">=20.0.0"},"dependencies":{"azure-devops-node-api":"^14.1.0","dotenv":"^16.4.7","ollama":"^0.6.3","openai":"^4.86.2"},"devDependencies":{"@bradygaster/squad-cli":"^0.8.25","@eslint/js":"^10.0.1","@types/node":"^22.0.0","@vitest/coverage-v8":"^3.2.4","eslint":"^10.0.3","typescript":"^5.7.0","typescript-eslint":"^8.56.1","vitest":"^3.0.0"},"gitHead":"5d8bb5c93e4f23b937e6f6fb195e13e935c99c2b","_id":"@arroyc/project-status-report-agent@1.3.2","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-sOq1+w5bNJsLhvEnUFLLhYLT0XMaeDFI31MNkRg5UqeF0v9/S8k0sa2WOxXRzbEAd+PZ1+F2IE0mWstPafgFFw==","shasum":"f9272888e3f0b88ca5fa43c884f5af3c5682d1eb","tarball":"https://registry.npmjs.org/@arroyc/project-status-report-agent/-/project-status-report-agent-1.3.2.tgz","fileCount":69,"unpackedSize":341966,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDIveJhgq3/DlQ66Dulpe2whXI2ntPPLi8XJV1odiAZ8gIgb+ybPO6XjjzifycH+JPQ4bS9vWkmmb6bhZquaBe6sPo="}]},"_npmUser":{"name":"arroyc2026","email":"roychoudhury.arjun@gmail.com"},"directories":{},"maintainers":[{"name":"arroyc2026","email":"roychoudhury.arjun@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/project-status-report-agent_1.3.2_1773081267126_0.251076576865348"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-07T11:36:53.928Z","modified":"2026-03-09T18:34:27.407Z","1.1.0":"2026-03-07T11:36:54.304Z","1.2.0":"2026-03-09T03:05:13.545Z","1.3.0":"2026-03-09T05:52:53.441Z","1.3.1":"2026-03-09T07:41:54.914Z","1.3.2":"2026-03-09T18:34:27.277Z"},"bugs":{"url":"https://github.com/arroyc/ado-project-reporter/issues"},"license":"MIT","homepage":"https://github.com/arroyc/ado-project-reporter#readme","keywords":["azure-devops","project-status","report-generator","llm","openai","ollama","cli"],"repository":{"type":"git","url":"git+https://github.com/arroyc/ado-project-reporter.git"},"description":"AI-powered Project Status Report Agent — fetches Azure DevOps data, generates LLM-summarized reports","maintainers":[{"name":"arroyc2026","email":"roychoudhury.arjun@gmail.com"}],"readme":"# Project Status Report Agent\n\nAI-powered agent that fetches Azure DevOps work items, generates LLM-summarized sections, and produces formatted project status reports.\n\n![Sample Report Output](docs/images/sample-output.png)\n\n## Prerequisites\n\n- **Node.js 20 or later** — Download from [nodejs.org](https://nodejs.org)\n- **Ollama** (for local LLM) — Install from [ollama.com](https://ollama.com) before running setup:\n  - **Windows:** `winget install Ollama.Ollama`\n  - **macOS:** `brew install ollama`\n  - **Linux:** `curl -fsSL https://ollama.com/install.sh | sh`\n- **Azure DevOps access** — A Personal Access Token (PAT) with read access to your project's work items\n\n## Quick Start\n\n### Install as a global CLI\n\n```bash\nnpm install -g project-status-report-agent\n```\n\nThen run from anywhere:\n\n```bash\npsr-agent              # interactive mode\npsr-agent --static     # one-shot report generation\npsr-agent setup        # interactive Ollama setup wizard\n```\n\n### Or use in a project\n\n```bash\nnpm install project-status-report-agent\n```\n\n```typescript\nimport { loadConfig, generateReport } from \"project-status-report-agent\";\n\nconst config = loadConfig();     // reads from .env\nawait generateReport(config);    // generates the report\n```\n\n## Features\n\n- **Azure DevOps Integration** — Queries work items via WIQL, fetches details and comments\n- **LLM Summarization** — Uses OpenAI, Azure OpenAI, or a local Ollama model (e.g. Llama) to generate executive summaries, progress tables, metrics, challenges, and next steps\n- **Multi-Month Comparison** — Optional month-over-month comparison (toggle via `ENABLE_COMPARISON` env var, or per-request in interactive mode with \"with comparison\" / \"without comparison\")\n- **Dynamic Version** — Report version is read from `package.json` at runtime\n- **Auto Section Renumbering** — When conditional sections (e.g. comparison) are removed, remaining section headings are renumbered sequentially\n- **Template Engine** — Populates a Markdown template with structured report data, conditional blocks (`{{#if}}`), and configurable section titles\n- **Interactive Agent** — Conversational REPL for on-demand report generation and analysis\n- **Static Mode** — One-shot CLI for automated report generation\n- **Disk Cache** — File-based cache for ADO work items with configurable TTL, avoiding redundant API calls across runs\n- **Concurrent Fetching** — Parallel comment fetching with configurable concurrency (default: 10) for faster ADO data retrieval\n- **Configurable Section Titles** — Customize all report section headers via `SECTION_*` env vars\n- **Smart ICM Handling** — Automatically shows \"No ICMs reported\" when no ICM-tagged items exist; hotfix deployments are reported under Releases\n\n## Project Structure\n\n```\nsrc/               TypeScript source files\n  types.ts         Shared interfaces and type definitions\n  config.ts        Environment variable loader\n  ado-client.ts    Azure DevOps WIQL client (with concurrent fetching + cache)\n  cache.ts         File-based disk cache for ADO work items\n  extractor.ts     Work item categorizer and HTML stripper\n  summarizer.ts    LLM-powered section generation\n  refiner.ts       Second-pass LLM refinement\n  template-engine.ts  Template population engine (conditional blocks, configurable titles)\n  report-generator.ts Full pipeline orchestrator\n  agent.ts         Interactive conversational agent (REPL)\n  index.ts         CLI entry point\ntest/              Vitest test files\n  cache.test.ts\n  config.test.ts\n  extractor.test.ts\n  template-engine.test.ts\ndist/              Compiled JavaScript output (generated)\noutput/            Generated reports\n.cache/            ADO work item cache (auto-created, gitignored)\ndocs/              Documentation\n```\n\n## Setup\n\n1. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n2. Copy an example config from `environment-examples/` to `.env` and fill in your credentials:\n   ```bash\n   cp environment-examples/.env.azure-openai.example .env   # Azure OpenAI\n   cp environment-examples/.env.ollama.example .env         # Ollama (llava:13b)\n   cp environment-examples/.env.mistral.example .env        # Ollama (mistral)\n   cp environment-examples/.env.phi3.example .env           # Ollama (phi3)\n   ```\n   ```\n   ADO_ORG_URL=https://dev.azure.com/yourorg\n   ADO_PAT=your-personal-access-token\n   ADO_PROJECT=YourProject\n   LLM_PROVIDER=azure-openai\n   LLM_API_KEY=your-api-key\n   LLM_MODEL=gpt-4o\n   TEAM_NAME=YourTeam\n   CLIENT_NAME=YourClient\n   PREPARED_BY=YourName\n   REPORT_START_DATE=2026-01-01\n   REPORT_END_DATE=2026-02-01\n   ```\n\n### Running locally with Ollama (no cloud LLM required)\n\nInstead of using Azure OpenAI (which requires an Azure subscription, deployed model, and API key), you can run the entire agent locally using [Ollama](https://ollama.com/) — a free, open-source tool that runs LLMs on your own machine.\n\n#### Interactive setup\n\nOllama is the recommended local LLM runtime. After installing Ollama (see [Prerequisites](#prerequisites)), the setup wizard walks you through model selection and `.env` generation.\n\n1. **Install Ollama** (prerequisite — must be done first):\n   - **Windows:** `winget install Ollama.Ollama`\n   - **macOS:** `brew install ollama`\n   - **Linux:** `curl -fsSL https://ollama.com/install.sh | sh`\n\n2. **Install the package** — Setup runs automatically during `npm install`:\n   ```bash\n   npm install @arroyc/project-status-report-agent\n   ```\n   The setup checks for Ollama, lets you choose which model to pull, and auto-generates your `.env` file:\n   - **mistral** — fast, general-purpose text analysis (recommended)\n   - **phi3** — lightweight, good for limited hardware\n   - **llava:13b** — vision-enabled for image/chart analysis (~8 GB)\n\n   After setup, fill in your ADO credentials (`ADO_ORG_URL`, `ADO_PAT`, `ADO_PROJECT`) in the generated `.env`.\n   You can Ctrl+C at any time.\n3. **Re-run setup any time** — `npx psr-agent setup` to change models or regenerate `.env`.\n4. **Or set up manually** — run `ollama pull <model>` and copy an environment-examples template to `.env`.\n\n> Skip the postinstall setup entirely with: `SKIP_OLLAMA_SETUP=true npm install`\n\n#### Compatible models\n\n| Model | Size | Notes |\n|-------|------|-------|\n| `mistral` | ~4 GB | **Default.** Text-only, fast — best for general text analysis |\n| `phi3` | ~2 GB | Text-only, lightweight — good for limited hardware |\n| `llava:13b` | ~8 GB | Vision-capable (LLaVA 1.6) — required for image/chart analysis |\n| `llama3.1:8b` | ~4.7 GB | Text-only, good quality, lower resource usage |\n| `llama3:70b` | ~40 GB | Text-only, highest quality but requires significant RAM/VRAM |\n\nYou can verify pulled models with:\n\n```bash\nollama list\n```\n\n#### Configure `.env` for Ollama\n\n```\n# ── LLM (Local — Ollama) ───────────────────────────────────────────────\nLLM_PROVIDER=ollama\nLLM_ENDPOINT=http://localhost:11434/v1\nLLM_MODEL=llava:13b\n# LLM_API_KEY is not needed — automatically handled for Ollama\nVISION_ENABLED=true          # set to true when using a vision model like llava\n```\n\nAll other settings (ADO credentials, reporting period, team info, etc.) remain the same as the cloud setup.\n\n#### Build and run\n\n```bash\nnpm run build\nnpx psr-agent\n```\n\n> **Note:** Ollama runs inference locally, so generation speed depends on your hardware. A machine with a GPU will be significantly faster. The agent works the same way regardless of provider — only the LLM backend differs.\n\n3. Build:\n   ```bash\n   npm run build\n   ```\n\n## Usage\n\nThe agent supports two execution modes: **Interactive** and **Static**. Both modes use the same underlying pipeline — fetch work items from Azure DevOps, categorize them, summarize via LLM, and produce a Markdown report.\n\n### Interactive Mode (default)\n\n```bash\nnpx psr-agent\n# or explicitly:\nnode dist/index.js\n```\n\nInteractive mode starts a conversational REPL with a `psr-agent>` prompt. The agent uses the configured LLM to parse your natural language input into structured intents, so you can issue commands conversationally. It maintains a session with cached ADO data to avoid re-fetching between commands.\n\n![Interactive Mode — help command](docs/images/interactive-mode.png)\n\n**Available commands:**\n\n| Command | Description |\n|---------|-------------|\n| `generate report` | Generate a full report for the configured period (`REPORT_START_DATE` → `REPORT_END_DATE`) |\n| `generate report for January 2026` | Generate a report for a specific period (the agent infers the date range) |\n| `generate report for Feb with comparison` | Generate a report with month-over-month comparison enabled |\n| `generate report for March without comparison` | Generate a report with comparison explicitly disabled |\n| `compare last 3 months` | Fetch multiple months and produce a multi-month trend comparison |\n| `show S360 metrics` | Deep-dive into a specific category (s360, icm, rollout, monitoring, support, bugs, blockers, or all) |\n| `polish the executive summary` | Re-summarize or refine a specific section (executive, progress, metrics, challenges, next_steps, comparison, or all) |\n| `set team name to Platform Team` | Override any config value at runtime without restarting |\n| `list tags` / `show tags` | Display configured ADO category tag mappings |\n| `clear` / `clr` / `cls` | Clear the terminal screen |\n| `help` | Show all available commands |\n| `exit` | Quit the agent |\n\n**Example session:**\n```\npsr-agent> generate report for February 2026\n  📊 Generating report for 2026-02-01 → 2026-03-01 (without comparison)\n  ...\n  ✅ Report written to ./output/report-february-2026.md\n\npsr-agent> generate report for February 2026 with comparison\n  📊 Generating report for 2026-02-01 → 2026-03-01 (with comparison)\n  ...\n  ✅ Report written to ./output/report-february-2026.md\n\npsr-agent> compare last 3 months\n  ⏳ Fetching work items for Dec 2025, Jan 2026, Feb 2026...\n  ✓ Comparison table generated\n\npsr-agent> show all metrics in detail\n  ...\n\npsr-agent> exit\n```\n\n### Setup Command\n\n```bash\nnpx psr-agent setup\n```\n\nThe setup command is an interactive wizard that configures your local Ollama environment:\n\n1. **Checks for Ollama** — verifies Ollama is installed on your system (see [Prerequisites](#prerequisites) to install it)\n2. **Model selection** — choose which model to pull:\n   - `mistral` — fast, general-purpose text analysis (recommended)\n   - `phi3` — lightweight, good for limited hardware\n   - `llava:13b` — vision-enabled for image/chart analysis (~8 GB)\n3. **Generates `.env`** — creates a `.env` file pre-configured for Ollama with your chosen model (asks before overwriting an existing `.env`)\n\nAfter setup completes, fill in your Azure DevOps credentials (`ADO_ORG_URL`, `ADO_PAT`, `ADO_PROJECT`) in the generated `.env`.\n\nThe setup wizard also runs automatically during `npm install`. Skip it with `SKIP_OLLAMA_SETUP=true npm install`.\n\n### Static Mode (one-shot)\n\n```bash\nnpx psr-agent --static\n# or explicitly:\nnode dist/index.js --static\nnode dist/index.js -s\n```\n\nStatic mode generates a single report using the date range in `.env` and exits immediately. There is no interactive prompt — it runs the full pipeline end-to-end and writes the output file.\n\nThis is ideal for:\n- **CI/CD pipelines** — trigger report generation on a schedule\n- **Cron jobs** — automate monthly reports without manual intervention\n- **Scripting** — chain with other tools (e.g. email the report, commit to a repo)\n\n## Testing\n\n```bash\nnpm test\n```\n\n## Configuration\n\nAll configuration is via environment variables (loaded from `.env`):\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `ADO_ORG_URL` | Yes | Azure DevOps organization URL |\n| `ADO_PAT` | Yes | Personal Access Token |\n| `ADO_PROJECT` | Yes | Project name |\n| `ADO_TEAM` | No | Team name filter (scopes WIQL query to a specific team) |\n| `ADO_AREA_PATH` | No | Area path filter (e.g. `Project\\Area`) |\n| `ADO_TEAM_MEMBERS` | No | Comma-separated list of team member names for filtering work items |\n| `ADO_REQUIRED_TAGS` | No | Comma-separated tags that work items must have to be included |\n| `ADO_WORK_ITEM_TYPES` | No | Comma-separated work item types to query (default: `Bug,Prod Change Request,Feature,User Story,Task`) |\n| `ADO_STATES` | No | Comma-separated terminal states to query (default: `Closed,Removed,Resolved`) |\n| `REPORT_START_DATE` | Yes | Period start (YYYY-MM-DD) |\n| `REPORT_END_DATE` | Yes | Period end (YYYY-MM-DD) |\n| **LLM** | | |\n| `LLM_PROVIDER` | No | `openai`, `azure-openai`, or `ollama` (default: `openai`) |\n| `LLM_API_KEY` | Yes* | OpenAI / Azure OpenAI API key (*not required for Ollama) |\n| `LLM_ENDPOINT` | No | LLM API endpoint (required for `azure-openai` and `ollama`, e.g. `http://localhost:11434/v1`) |\n| `LLM_MODEL` | No | Model name (default: `mistral`) |\n| `LLM_API_VERSION` | No | Azure OpenAI API version (default: `2024-12-01-preview`) |\n| `VISION_ENABLED` | No | Attach work item images to LLM calls (`true`/`false`) |\n| **Category Tag Mappings** | | |\n| `ADO_CATEGORY_TAGS` | No | Comma-separated 1:1 category tags where tag name = category name (default: `s360,icm,rollout,support,milestone`) |\n| `ADO_S360_TAGS` | No | Override tags for S360 category (default: `s360`) |\n| `ADO_ICM_TAGS` | No | Override tags for ICM category (default: `icm`) |\n| `ADO_ROLLOUT_TAGS` | No | Override tags for Rollout category (default: `rollout`) |\n| `ADO_MONITORING_TAGS` | No | Override tags for Monitoring category (default: `Monitoring,dev-test-ci,pipeline-monitoring`) |\n| `ADO_SUPPORT_TAGS` | No | Override tags for Support category (default: `support`) |\n| `ADO_RISK_TAGS` | No | Override tags for Risk category (default: `risk,blocker`) |\n| `ADO_MILESTONE_TAGS` | No | Override tags for Milestone category (default: `milestone`) |\n| **Report Output** | | |\n| `TEAM_NAME` | No | Team name for report header |\n| `CLIENT_NAME` | No | Client name for report header |\n| `PREPARED_BY` | No | Author name |\n| `TEMPLATE_PATH` | No | Path to report template |\n| `OUTPUT_PATH` | No | Output file path (default: `./output/report.md`) |\n| `VERBOSE` | No | Enable verbose logging (`true`/`false`) |\n| `ENABLE_COMPARISON` | No | Enable month-over-month comparison (`true`/`false`, default: `false`) |\n| **Section Titles** | | |\n| `SECTION_KEY_METRICS` | No | Custom title for Key Metrics section |\n| `SECTION_S360` | No | Custom title for S360 Status section |\n| `SECTION_RELEASES` | No | Custom title for Releases section |\n| `SECTION_ICM` | No | Custom title for ICM On-Call Activity section |\n| `SECTION_MONITORING_SUPPORT` | No | Custom title for Monitoring & Support section |\n| `SECTION_MONITORING` | No | Custom title for Monitoring subsection |\n| `SECTION_SUPPORT` | No | Custom title for Support subsection |\n| `SECTION_COMPARISON` | No | Custom title for Comparison section |\n| `SECTION_TREND_ANALYSIS` | No | Custom title for Trend Analysis section |\n| **Performance** | | |\n| `CACHE_DIR` | No | ADO cache directory (default: `.cache`) |\n| `CACHE_TTL_MINUTES` | No | Cache TTL in minutes, `0` to disable (default: `60`) |\n| `CONCURRENCY` | No | Max concurrent ADO API requests (default: `10`, minimum: `1`) |\n","readmeFilename":"README.md"}