{"id":48648378,"url":"https://github.com/juspay/lumos","last_synced_at":"2026-04-26T13:01:14.986Z","repository":{"id":348558618,"uuid":"1052629301","full_name":"juspay/lumos","owner":"juspay","description":"Create an AI-powered error intelligence \u0026 test validation system using Juspay's Neurolink SDK - focused on debugging assistance rather than test generation.","archived":false,"fork":false,"pushed_at":"2026-04-22T10:46:33.000Z","size":439,"stargazers_count":1,"open_issues_count":12,"forks_count":4,"subscribers_count":1,"default_branch":"release","last_synced_at":"2026-04-22T21:33:09.174Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/juspay.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-08T10:21:41.000Z","updated_at":"2026-04-22T10:46:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/juspay/lumos","commit_stats":null,"previous_names":["juspay/lumos"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/juspay/lumos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juspay%2Flumos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juspay%2Flumos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juspay%2Flumos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juspay%2Flumos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/juspay","download_url":"https://codeload.github.com/juspay/lumos/tar.gz/refs/heads/release","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juspay%2Flumos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32297899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-10T08:15:29.305Z","updated_at":"2026-04-26T13:01:14.980Z","avatar_url":"https://github.com/juspay.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lumos\n\nAI-powered test failure analysis agent. Parses Playwright JSON reports, correlates failures with Bitbucket PR diffs using a NeuroLink autonomous AI agent, and posts actionable fix suggestions as PR comments.\n\nBuilt as a standalone npm package (`@juspay/lumos`) consumed by [Lighthouse](https://bitbucket.juspay.net/projects/BZ/repos/lighthouse) (the Breeze merchant dashboard).\n\n## How It Works\n\n1. **Parse** -- Reads a Playwright JSON report and extracts structured failure data (error messages, stack traces, locations, flaky detection).\n2. **Correlate** -- A NeuroLink AI agent fetches the PR diff via Bitbucket MCP, reads relevant source files, and determines which failures are caused by PR changes vs pre-existing/flaky vs infrastructure issues.\n3. **Post** -- The agent composes and posts a single structured comment on the Bitbucket PR with root cause analysis and fix suggestions for each failure.\n\nLumos runs in the Jenkinsfile `catch` block after mock tests fail, wrapped in its own `try/catch` so it never blocks the build pipeline.\n\n## Setup\n\n### Prerequisites\n\n- Node.js \u003e= 20.12.0\n- pnpm\n\n### Install\n\n```bash\npnpm install\n```\n\n### Configure\n\n1. Copy `.env.example` to `.env` and fill in your credentials:\n\n```bash\ncp .env.example .env\n```\n\nRequired env vars:\n\n- `LITELLM_BASE_URL` / `LITELLM_API_KEY` -- AI provider (LiteLLM proxy for local, Vertex for production)\n- `BITBUCKET_USERNAME` / `BITBUCKET_TOKEN` -- Bitbucket MCP access\n- `JIRA_API_TOKEN` / `JIRA_EMAIL` -- Optional, for Jira MCP context (`JIRA` is also accepted as the token fallback)\n\n2. Optionally edit `lumos.config.yaml` to override defaults (AI model, timeout, token budget, report path, etc.). Environment variables take highest precedence.\n\nSupported Lumos config overrides from env:\n\n- `LUMOS_PROVIDER`\n- `LUMOS_MODEL`\n- `LUMOS_TIMEOUT`\n- `LUMOS_MAX_TOKENS`\n- `LUMOS_MAX_TOKEN_BUDGET`\n- `LUMOS_MAX_COST`\n\n## Usage\n\n### Programmatic\n\n```typescript\nimport { createLumos } from '@juspay/lumos';\n\nconst lumos = await createLumos();\nconst result = await lumos.analyze({\n  workspace: 'BZ',\n  repository: 'lighthouse',\n  pullRequestId: '4638',\n  type: 'mock',\n});\n\nconsole.log(result.failuresAnalyzed); // 17\nconsole.log(result.commentsPosted); // 1\nconsole.log(result.hasCritical); // true\n```\n\n`createLumos()` returns a small handle with a single `analyze()` function; the consumer does not manage the orchestrator lifecycle directly.\n\n### Local Testing\n\n```bash\n# Dry run (parses report, builds prompt, skips AI call)\nnpx tsx scripts/test-local.ts\n\n# Live run (calls AI, posts PR comment)\nnpx tsx scripts/test-local.ts --live\n\n# Against a specific PR\nnpx tsx scripts/test-local.ts --live --pr 4638\n```\n\n## Project Structure\n\n```\nsrc/\n  index.ts              -- Async factory (createLumos) + all exports\n  config.ts             -- 3-layer config loader (defaults \u003c YAML \u003c env vars) with Zod validation\n  orchestrator.ts       -- Main class: initialize MCP servers, run AI analysis, track tokens/cost\n  parsers/\n    types.ts            -- All TypeScript interfaces\n    playwright.ts       -- Playwright JSON report parser\n  prompts/\n    system-prompt.ts    -- System prompt + user message builders\n    schemas.ts          -- Zod schemas for structured AI output (future use)\n  utils/\n    errors.ts           -- Custom error hierarchy (6 classes)\n    logger.ts           -- Leveled logger\nscripts/\n  test-local.ts         -- Local test runner with fixture reports\n```\n\n## Development\n\n```bash\npnpm run typecheck      # Type check without emitting\npnpm run lint           # ESLint\npnpm run format:check   # Prettier check\npnpm run validate       # Lint + format check\npnpm run validate:all   # validate + test\npnpm run build          # Compile to dist/\npnpm run dev            # Watch mode\n```\n\n## Validation Status\n\nRepresentative validation runs against Jenkins reports:\n\n| PR    | Failures | PR-Caused | Flaky/Pre-existing | Infra | Tokens | Duration |\n| ----- | -------- | --------- | ------------------ | ----- | ------ | -------- |\n| #4610 | 4        | 0         | 4                  | 0     | 131k   | ~3 min   |\n| #4571 | 9        | 4         | 5                  | 0     | 540k   | ~8 min   |\n| #4638 | 17       | 10        | 5                  | 3     | 250k   | 210.8s   |\n\nCurrent local verification:\n\n- `pnpm typecheck` passes\n- `pnpm test` passes with no test files present (`vitest` is configured with `passWithNoTests`)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuspay%2Flumos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuspay%2Flumos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuspay%2Flumos/lists"}