| - | - | - | Total Number of | -Approximate Dollar | -
| - | - | - | Shares Purchased | -Value of Shares | -
| - | Total Number | -- | as Part of Publicly | -that May Yet Be | -
| - | of Shares | -Average Price | -Announced | -Purchased Under | -
| - | Purchased | -Paid per Share | -Program (In | -the Program (In | -
| Period | -(In millions) | -(1) | -millions) | -billions) | -
| October 27, 2025 - November 23, 2025 | -5.6 | -$ 198.89 | -5.6 | -$ 61.1 | -
| November 24, 2025 - December 21, | -- | - | - | - |
| 2025 | -6.6 | -$ 179.41 | -6.6 | -$ 59.9 | -
| December 22, 2025 - January 25, 2026 | -7.3 | -$ 186.52 | -7.3 | -$ 58.5 | -
| Total | -19.5 | -- | 19.5 | -- |
| - | 1/31/2021 | -1/30/2022 | -1/29/2023 | -1/28/2024 | -1/26/2025 | -1/25/2026 | -
| NVIDIA Corporation | -$ 100.00 | -$ 175.98 | -$ 157.05 | -$ 470.88 | -$ 1,100.68 | -$ 1,448.75 | -
| S&P 500 | -$ 100.00 | -$ 121.00 | -$ 112.98 | -$ 137.98 | -$ 174.50 | -$ 200.33 | -
| Nasdaq 100 | -$ 100.00 | -$ 112.60 | -$ 95.60 | -$ 138.07 | -$ 173.95 | -$ 206.01 | -
| Item 6. [Reserved] | -- | - | - | - | - | - |
| - | - | Year Ended | -
| - | Jan 25, 2026 | -Jan 26, 2025 Change | -
| - | ($ in millions, except per share data) | -- |
| Revenue | -$ 215,938 | -$ 130,497 Up 65% | -
| Gross margin | -71.1 % | -75.0 % -3.9 pts | -
| Operating expenses | -$ 23,076 | -$ 16,405 Up 41% | -
| Operating income | -$ 130,387 | -$ 81,453 Up 60% | -
| Net income | -$ 120,067 | -$ 72,880 Up 65% | -
| Net income per diluted share | -$ 4.90 | -$ 2.94 Up 67% | -
| - | - | Year Ended | -- | - |
| - | - | - | $ | -% | -
| - | Jan 25, 2026 | -Jan 26, 2025 Change | -- | Change | -
| - | - | ($ in millions) | -- | - |
| Research and development | -$ 18,497 | -$ 12,914 $ | -5,583 | -43 % | -
| Sales, general and administrative | -4,579 | -3,491 | -1,088 | -31 % | -
| - | - | - | - | Year Ended | -- | - | - |
| - | - | - | - | - | - | $ | -- |
| - | - | Jan 25, 2026 | -- | Jan 26, 2025 | -- | Change | -- |
| - | - | - | - | ($ in millions) | -- | - | - |
| Interest income | -$ | -2,300 | -$ | -1,786 | -$ | -- | 514 | -
| Interest expense | -- | (259) | -- | (247) | -- | - | (12) | -
| Other income, net | -- | 9,022 | -- | 1,034 | -- | - | 7,988 | -
| Total other income, net | -$ | -11,063 | -$ | -2,573 | -$ | -- | 8,490 | -
| - | Jan 25, 2026 Jan 26, 2025 | -- |
| - | (In millions) | -- |
| Cash and cash equivalents | -$ 10,605 $ | -8,589 | -
| Marketable securities | -51,951 | -34,621 | -
| Cash, cash equivalents, and marketable securities | -$ 62,556 $ | -43,210 | -
| - | Year Ended | -
| - | Jan 25, 2026 Jan 26, 2025 | -
| - | (In millions) | -
| Net cash provided by operating activities | -$ 102,718 $ 64,089 | -
| Net cash used in investing activities | -$ (52,228) $ (20,421) | -
| Net cash used in financing activities | -$ (48,474) $ (42,359) | -
| - | - | (In millions) | -
| Due in one year | -$ | -1,000 | -
| Due in one to five years | -- | 2,750 | -
| Due in five to ten years | -- | 1,250 | -
| Due in greater than ten years | -- | 3,500 | -
| Unamortized debt discount and issuance costs | -- | (32) | -
| Net carrying amount | -$ | -8,468 | -
| Less short-term portion | -- | 999 | -
| Total long-term portion | -$ | -7,469 | -
| - | NVIDIA Corporation and Subsidiaries | -- | - |
| - | Consolidated Statements of Income | -- | - |
| - | (In millions, except per share data) | -- | - |
| - | - | Year Ended | -- |
| - | Jan 25, 2026 | -Jan 26, 2025 | -Jan 28, 2024 | -
| Revenue | -$ 215,938 | -$ 130,497 | -$ 60,922 | -
| Cost of revenue | -62,475 | -32,639 | -16,621 | -
| Gross profit | -153,463 | -97,858 | -44,301 | -
| Operating expenses | -- | - | - |
| Research and development | -18,497 | -12,914 | -8,675 | -
| Sales, general and administrative | -4,579 | -3,491 | -2,654 | -
| Total operating expenses | -23,076 | -16,405 | -11,329 | -
| Operating income | -130,387 | -81,453 | -32,972 | -
| Interest income | -2,300 | -1,786 | -866 | -
| Interest expense | -(259) | -(247) | -(257) | -
| Other income, net | -9,022 | -1,034 | -237 | -
| Total other income, net | -11,063 | -2,573 | -846 | -
| Income before income tax | -141,450 | -84,026 | -33,818 | -
| Income tax expense | -21,383 | -11,146 | -4,058 | -
| Net income | -$ 120,067 | -$ 72,880 | -$ 29,760 | -
| Net income per share: | -- | - | - |
| Basic | -$ 4.93 | -$ 2.97 | -$ 1.21 | -
| Diluted | -$ 4.90 | -$ 2.94 | -$ 1.19 | -
| Weighted average shares used in per share computation: | -- | - | - |
| Basic | -24,359 | -24,555 | -24,690 | -
| Net income | -$ 120,067 | -$ 72,880 | -$ 29,760 | -
| Other comprehensive income, net of tax | -- | - | - |
| Available-for-sale securities: | -- | - | - |
| Net change in unrealized gain | -107 | -1 | -80 | -
| Cash flow hedges: | -- | - | - |
| Net change in unrealized gain (loss) | -43 | -— | -(10) | -
| Other comprehensive income, net of tax | -150 | -1 | -70 | -
| - | Jan 25, 2026 | -Jan 26, 202 | -
| Assets | -- | - |
| Current assets: | -- | - |
| Cash and cash equivalents | -$ 10,605 | -$ 8,58 | -
| Marketable securities | -51,951 | -34,62 | -
| Accounts receivable, net | -38,466 | -23,06 | -
| Inventories | -21,403 | -10,08 | -
| Prepaid expenses and other current assets | -3,180 | -3,77 | -
| Total current assets | -125,605 | -80,12 | -
| Property and equipment, net | -10,383 | -6,28 | -
| Operating lease assets | -2,867 | -1,79 | -
| Goodwill | -20,832 | -5,18 | -
| Intangible assets, net | -3,306 | -80 | -
| Deferred income tax assets | -13,258 | -10,97 | -
| Non-marketable equity securities | -22,251 | -3,38 | -
| Other assets | -8,301 | -3,03 | -
| Total assets | -$ 206,803 | -$ 111,60 | -
| Liabilities and Shareholders' Equity | -- | - |
| Current liabilities: | -- | - |
| Accounts payable | -$ 9,812 | -$ 6,31 | -
| Accrued and other current liabilities | -21,352 | -11,73 | -
| Short-term debt | -999 | -- |
| Total current liabilities | -32,163 | -18,04 | -
| Long-term debt | -7,469 | -8,46 | -
| Long-term operating lease liabilities | -2,572 | -1,51 | -
| Other long-term liabilities | -7,306 | -4,24 | -
| Total liabilities | -49,510 | -32,27 | -
| Commitments and contingencies - see Note 12 | -— | -- |
| Shareholders’ equity: | -- | - |
| Preferred stock, $0.001 par value; 2 shares authorized; none issued | -— | -- |
| Common stock, $0.001 par value; 80,000 shares authorized; 24,304 shares | -- | - |
| issued and outstanding as of January 25, 2026; 24,477 shares issued and | -- | - |
| outstanding as of January 26, 2025 | -24 | -2 | -
| Additional paid-in capital | -10,118 | -11,23 | -
| Accumulated other comprehensive income | -178 | -2 | -
| Retained earnings | -146,973 | -68,03 | -
| Total shareholders' equity | -157,293 | -79,32 | -
| Total liabilities and shareholders' equity | -$ 206,803 | -$ 111,60 | -
| - | - | - | - | Accumulated | -- | - | - |
| - | Common Stock | -- | Additional | -Other | -- | - | Total | -
| - | Outstanding | -- | Paid-in | -Comprehensive | -- | Retained | -Shareholders' | -
| - | Shares Amount | -- | Capital | -Income (Loss) | -- | Earnings | -Equity | -
| (In millions, except per share data) | -- | - | - | - | - | - | - |
| Balances as of Jan 29, 2023 | -24,661 $ 25 | -$ | -11,948 | -$ (43) | -$ | -10,171 | -$ 22,101 | -
| Net income | -— — | -- | — | -— | -- | 29,760 | -29,760 | -
| Other comprehensive income | -— — | -- | — | -70 | -- | — | -70 | -
| Issuance of common stock | -265 — | -- | 403 | -— | -- | — | -403 | -
| Tax withholding related to common stock | -(72) — | -- | (2,783) | -— | -- | — | -(2,783) | -
| Shares repurchased | -(211) — | -- | (27) | -— | -- | (9,719) | -(9,746) | -
| Cash dividends declared and paid ($0.016 per common share) | -— — | -- | — | -— | -- | (395) | -(395) | -
| Stock-based compensation | -— — | -- | 3,568 | -— | -- | — | -3,568 | -
| Balances as of Jan 28, 2024 | -24,643 25 | -- | 13,109 | -27 | -- | 29,817 | -42,978 | -
| Net income | -— — | -- | — | -— | -- | 72,880 | -72,880 | -
| Other comprehensive income | -— — | -- | — | -1 | -- | — | -1 | -
| Issuance of common stock | -203 — | -- | 490 | -— | -- | — | -490 | -
| Tax withholding related to common stock | -(59) — | -- | (6,930) | -— | -- | — | -(6,930) | -
| Shares repurchased | -(310) (1) | -- | (189) | -— | -- | (33,825) | -(34,015) | -
| Cash dividends declared and paid ($0.034 per common share) | -— — | -- | — | -— | -- | (834) | -(834) | -
| Stock-based compensation | -— — | -- | 4,757 | -— | -- | — | -4,757 | -
| Balances as of Jan 26, 2025 | -24,477 24 | -- | 11,237 | -28 | -- | 68,038 | -79,327 | -
| Net income | -— — | -- | — | -— | -- | 120,067 | -120,067 | -
| Other comprehensive income | -— — | -- | — | -150 | -- | — | -150 | -
| Issuance of common stock | -160 — | -- | 644 | -— | -- | — | -644 | -
| Tax withholding related to common stock | -(51) — | -- | (7,948) | -— | -- | — | -(7,948) | -
| Shares repurchased | -(282) — | -- | (230) | -— | -- | (40,158) | -(40,388) | -
| Cash dividends declared and paid ($0.04 per common share) | -— — | -- | — | -— | -- | (974) | -(974) | -
| Fair value of partially vested equity awards assumed in connection with | -- | - | - | - | - | - | - |
| acquisitions | -— — | -- | 28 | -— | -- | — | -28 | -
| Stock-based compensation | -— — | -- | 6,387 | -— | -- | — | -6,387 | -
| Balances as of Jan 25, 2026 | -24,304 $ 24 | -$ | -10,118 | -$ 178 | -$ | -146,973 | -$ 157,293 | -
| - | - | Year Ended | -- |
| - | Jan 25, 2026 | -Jan 26, 2025 | -Jan 28, 2024 | -
| Cash flows from operating activities: | -- | - | - |
| Net income | -$ 120,067 | -$ 72,880 | -$ 29,760 | -
| Adjustments to reconcile net income to net cash provided by operating | -- | - | - |
| activities: | -- | - | - |
| Stock-based compensation expense | -6,386 | -4,737 | -3,549 | -
| Depreciation and amortization | -2,843 | -1,864 | -1,508 | -
| Gains on non-marketable equity securities and publicly-held | -- | - | - |
| equity securities, net | -(8,918) | -(1,030) | -(238) | -
| Deferred income taxes | -(1,424) | -(4,477) | -(2,489) | -
| Other | -(287) | -(502) | -(278) | -
| Changes in operating assets and liabilities, net of acquisitions: | -- | - | - |
| Accounts receivable | -(15,399) | -(13,063) | -(6,172) | -
| Inventories | -(11,324) | -(4,781) | -(98) | -
| Prepaid expenses and other assets | -577 | -(395) | -(1,522) | -
| Accounts payable | -3,096 | -3,357 | -1,531 | -
| Accrued and other current liabilities | -5,257 | -4,278 | -2,025 | -
| Other long-term liabilities | -1,844 | -1,221 | -514 | -
| Net cash provided by operating activities | -102,718 | -64,089 | -28,090 | -
| Cash flows from investing activities: | -- | - | - |
| Proceeds from sales of marketable securities | -15,157 | -495 | -50 | -
| Proceeds from maturities of marketable securities | -11,226 | -11,195 | -9,732 | -
| Proceeds from sales of non-marketable equity securities | -84 | -171 | -1 | -
| Purchases of marketable securities | -(40,616) | -(26,575) | -(18,211) | -
| Purchases of non-marketable equity securities | -(17,502) | -(1,486) | -(862) | -
| Groq, Inc. | -(13,000) | -— | -— | -
| Purchases related to property and equipment and intangible | -- | - | - |
| assets | -(6,042) | -(3,236) | -(1,069) | -
| Acquisitions, net of cash acquired | -(1,535) | -(1,007) | -(83) | -
| Other | -— | -22 | -(124) | -
| Net cash used in investing activities | -(52,228) | -(20,421) | -(10,566) | -
| Cash flows from financing activities: | -- | - | - |
| Proceeds related to employee stock plans | -644 | -490 | -403 | -
| Payments related to repurchases of common stock | -(40,086) | -(33,706) | -(9,533) | -
| Payments related to employee stock plan taxes | -(7,948) | -(6,930) | -(2,783) | -
| Dividends paid | -(974) | -(834) | -(395) | -
| Principal payments on property and equipment and intangible | -- | - | - |
| assets | -(101) | -(129) | -(74) | -
| Repayment of debt | -— | -(1,250) | -(1,250) | -
| Other | -(9) | -— | -(1) | -
| Net cash used in financing activities | -(48,474) | -(42,359) | -(13,633) | -
| Change in cash and cash equivalents | -2,016 | -1,309 | -3,891 | -
| Cash and cash equivalents at beginning of period | -8,589 | -7,280 | -3,389 | -
| Cash and cash equivalents at end of period | -$ 10,605 | -$ 8,589 | -$ 7,280 | -
| Supplemental disclosures of cash flow information: | -- | - | - |
| Cash paid for income taxes, net | -$ 20,288 | -$ 15,118 | -$ 6,549 | -
| - | - | Year Ended | -- |
| - | Jan 25, 2026 | -Jan 26, 2025 | -Jan 28, 2024 | -
| - | - | (In millions) | -- |
| Cost of revenue | -$ 261 | -$ 178 | -$ 141 | -
| Research and development | -4,676 | -3,423 | -2,532 | -
| Sales, general and administrative | -1,449 | -1,136 | -876 | -
| Total | -$ 6,386 | -$ 4,737 | -$ 3,549 | -
| - | - | Year Ended | -- |
| - | Jan 25, 2026 | -Jan 26, 2025 Jan 28, 2024 | -- |
| - | (In millions, except per share data) | -- | - |
| RSUs, PSUs and Market-based PSUs | -- | - | - |
| Awards granted | -70 | -89 | -140 | -
| Estimated total grant-date fair value | -$ 9,389 | -$ 7,834 $ | -5,316 | -
| Weighted average grant-date fair value per share | -$ 133.97 | -$ 87.99 $ | -37.41 | -
| ESPP | -- | - | - |
| Shares purchased | -13 | -30 | -30 | -
| Weighted average price per share | -$ 49.13 | -$ 17.74 $ | -15.81 | -
| Weighted average grant-date fair value per share | -$ 20.75 | -$ 8.61 $ | -6.99 | -
| - | - | Year Ended | -
| - | Jan 25, 2026 | -Jan 26, 2025 Jan 28, 2024 | -
| - | (Using the Black-Scholes model) | -- |
| ESPP | -- | - |
| Weighted average expected life (in years) | -0.1-2.0 | -0.1-2.0 0.1-2.0 | -
| Risk-free interest rate | -3.5%-4.3% | -3.6%-5.4% 3.9%-5.5% | -
| Volatility | -26%-96% | -31%-75% 31%-67% | -
| Dividend yield | -0.03% | -0.03% 0.06% | -
| - | RSUs, PSUs and Market-based PSUs Outstanding | -
| - | Weighted Average | -
| - | Grant-Date Fair Value | -
| - | Number of Shares Per Share | -
| - | (In millions, except per share data) | -
| Balance as of Jan 26, 2025 | -274 $ 44.75 | -
| Granted | -70 $ 133.97 | -
| Vested | -(146) $ 39.14 | -
| Canceled and forfeited | -(9) $ 59.29 | -
| Balance as of Jan 25, 2026 | -189 $ 81.51 | -
| Vested and expected to vest after Jan 25, 2026 | -188 $ 81.15 | -
| - | - | Year Ended | -
| - | Jan 25, 2026 | -Jan 26, 2025 Jan 28, 2024 | -
| - | (In millions, except per share data) | -- |
| Numerator: | -- | - |
| Net income | -$ 120,067 | -$ 72,880 $ 29,760 | -
| Denominator: | -- | - |
| Basic weighted average shares | -24,359 | -24,555 24,690 | -
| Dilutive impact of outstanding equity awards | -155 | -249 250 | -
| Diluted weighted average shares | -24,514 | -24,804 24,940 | -
| Net income per share: | -- | - |
| Basic (1) | -$ 4.93 | -$ 2.97 $ 1.21 | -
| Diluted (2) | -$ 4.90 | -$ 2.94 $ 1.19 | -
| Anti-dilutive equity awards excluded from diluted net income per share | -41 | -51 150 | -
| - | - | - | Jan 25, 2026 | -- | - | - | Jan 26, 2025 | -- | - |
| - | - | Gross | -- | - | Net Gross | -- | - | - | Net | -
| - | - | Carrying | -Accumulated | -- | Carrying Carrying | -- | Accumulated | -- | Carrying | -
| - | - | Amount | -Amortization | -- | Amount Amount | -- | Amortization | -- | Amount | -
| - | - | - | - | - | (In millions) | -- | - | - | - |
| Acquisition-related | -- | - | - | - | - | - | - | - | - |
| intangible assets | -$ | -5,656 | -$ (2,580) | -$ | -3,076 $ | -2,900 | -$ (2,264) | -$ | -636 | -
| Patents and licensed | -- | - | - | - | - | - | - | - | - |
| technology | -- | 528 | -(298) | -- | 230 | -449 | -(278) | -- | 171 | -
| Total intangible assets | -$ | -6,184 | -$ (2,878) | -$ | -3,306 $ | -3,349 | -$ (2,542) | -$ | -807 | -
| - | - | Future Amortization Expense | -
| - | - | (In millions) | -
| Fiscal Year: | -- | - |
| 2027 | -$ | -923 | -
| 2028 | -- | 729 | -
| 2029 | -- | 592 | -
| 2030 | -- | 511 | -
| 2031 | -- | 468 | -
| 2032 and thereafter | -- | 83 | -
| Total | -$ | -3,306 | -
| - | - | - | - | Jan 25, 2026 | -- | - | - |
| - | - | - | - | - | - | Reported as | -- |
| - | - | Cost or | -- | - | - | - | - |
| - | Pricing | -Amortized | -Unrealized | -Unrealized Estimated | -Cash | -Marketable | -Other | -
| - | Category | -Cost | -Gain | -Loss Fair Value | -Equivalents | -Securities | -Assets | -
| - | - | - | - | (In millions) | -- | - | - |
| Debt securities | -- | - | - | - | - | - | - |
| issued by the | -- | - | - | - | - | - | - |
| U.S. Treasury | -Level 2 | -$ 21,635 | -$ 77 | -$ (3) $ 21,709 | -$ — | -$ 21,709 | -$ — | -
| Corporate debt | -- | - | - | - | - | - | - |
| securities | -Level 2 | -15,410 | -92 | -(3) 15,499 | -345 | -15,154 | -— | -
| Debt securities | -- | - | - | - | - | - | - |
| issued by U.S. | -- | - | - | - | - | - | - |
| government | -- | - | - | - | - | - | - |
| agencies | -Level 2 | -2,157 | -4 | -— 2,161 | -— | -2,161 | -— | -
| Certificates of | -- | - | - | - | - | - | - |
| deposit | -Level 2 | -110 | -— | -— 110 | -110 | -— | -— | -
| Foreign | -- | - | - | - | - | - | - |
| government | -- | - | - | - | - | - | - |
| bonds | -Level 2 | -40 | -1 | -— 41 | -— | -41 | -— | -
| Money market | -- | - | - | - | - | - | - |
| funds | -Level 1 | -7,830 | -— | -— 7,830 | -7,830 | -— | -— | -
| Publicly-held | -- | - | - | - | - | - | - |
| equity | -- | - | - | - | - | - | - |
| securities (1) (2) | -Level 1 | -- | - | 17,726 | -— | -12,886 | -4,840 | -
| Total | -- | $ 47,182 | -$ 174 | -$ (6) $ 65,076 | -$ 8,285 | -$ 51,951 | -$ 4,840 | -
| - | - | Jan 26, 2025 | -
| - | - | Reported asCost or | -
| - | Pricing | -Amortized Unrealized Unrealized Estimated Cash Marketable | -
| - | Category | -Cost Gain Loss Fair Value Equivalents Securities | -
| - | - | (In millions) | -
| Corporate debt | -- | - |
| securities | -Level 2 | -$ 18,504 $ 51 $ (29) $ 18,526 $ 2,071 $ 16,455 | -
| Debt securities | -- | - |
| issued by the U.S. | -- | - |
| Treasury | -Level 2 | -16,749 42 (22) 16,769 1,801 14,968 | -
| Debt securities | -- | - |
| issued by U.S. | -- | - |
| government | -- | - |
| agencies | -Level 2 | -2,775 7 (5) 2,777 — 2,777 | -
| Foreign government | -- | - |
| bonds | -Level 2 | -177 — — 177 137 40 | -
| Certificates of | -- | - |
| deposit | -Level 2 | -97 — — 97 97 — | -
| Money market | -- | - |
| funds | -Level 1 | -3,760 — — 3,760 3,760 — | -
| Publicly-held equity | -- | - |
| securities | -Level 1 | -381 — 381 | -
| Total | -- | $ 42,062 $ 100 $ (56) $ 42,487 $ 7,866 $ 34,621 | -
| - | Jan 25, 2026 | -Jan 26, 2025 | -
| - | Less than 12 Months Less than 12 Months | -- |
| - | Gross | -Gross | -
| - | Estimated Unrealized Estimated | -Unrealized | -
| - | Fair Value Loss Fair Value | -Loss | -
| - | (In millions) | -- |
| Debt securities issued by the U.S. Treasury | -$ 10,666 $ (3) $ | -6,315 $ (22) | -
| Corporate debt securities | -1,332 (3) | -5,291 (29) | -
| Debt securities issued by U.S. government agencies | -1,134 — | -816 (5) | -
| Total | -$ 13,132 $ (6) $ | -12,422 $ (56) | -
| - | - | Jan 25, 2026 | -- |
| - | - | (In millions) | -- |
| Less than one year | -$ | -- | 20,427 | -
| Due in 1 - 5 years | -- | - | 19,093 | -
| Total | -$ | -- | 39,520 | -
| - | - | Year Ended | -
| - | - | Jan 25, 2026 Jan 26, 2025 | -
| - | - | (In millions) | -
| Balance at beginning of period | -$ | -3,387 $ 1,321 | -
| Adjustments related to non-marketable equity securities: | -- | - |
| Net additions | -- | 17,444 1,309 | -
| Unrealized gains | -- | 2,369 816 | -
| Reclassification (1) | -- | (848) — | -
| Impairments and unrealized losses | -- | (101) (59) | -
| Balance at end of period | -$ | -22,251 $ 3,387 | -
| - | - | Jan 25, 2026 Jan 26, 2025 | -- |
| Inventories: | -- | (In millions) | -- |
| Raw materials | -$ | -3,807 $ | -3,408 | -
| Work in process | -- | 8,822 | -3,399 | -
| Finished goods | -- | 8,774 | -3,273 | -
| Total inventories (1) | -$ | -21,403 $ | -10,080 | -
| - | - | - | Estimated | -
| - | Jan 25, 2026 Jan 26, 2025 | -- | Useful Life | -
| Property and Equipment: | -(In millions) | -- | (In years) | -
| Land | -$ 777 $ | -511 | -(A) | -
| Buildings, leasehold improvements, and furniture | -2,891 | -2,076 | -(B) | -
| Equipment, compute hardware, and software | -12,619 | -7,568 | -2-7 | -
| Construction in process | -683 | -529 | -(C) | -
| Total property and equipment, gross | -16,970 | -10,684 | -- |
| Accumulated depreciation and amortization | -(6,587) | -(4,401) | -- |
| Total property and equipment, net | -$ 10,383 $ | -6,283 | -- |
| - | - | Jan 25, 2026 Jan 26, 2025 | -- |
| Accrued and Other Current Liabilities: | -- | (In millions) | -- |
| Customer program accruals | -$ | -5,318 $ | -4,880 | -
| Accrued purchase consideration | -- | 3,921 | -9 | -
| Product warranty | -- | 2,807 | -1,290 | -
| Excess inventory purchase obligations (1) | -- | 2,739 | -2,095 | -
| Taxes payable | -- | 2,669 | -881 | -
| Deferred revenue (2) | -- | 1,379 | -837 | -
| Accrued payroll and related expenses | -- | 1,146 | -848 | -
| Other | -- | 1,373 | -897 | -
| Total accrued and other current liabilities | -$ | -21,352 $ | -11,737 | -
| - | - | Jan 25, 2026 Jan 26, 2025 | -- |
| Other Long-Term Liabilities: | -- | (In millions) | -- |
| Income tax payable (1) | -$ | -3,958 $ | -2,188 | -
| Deferred income tax | -- | 1,774 | -886 | -
| Deferred revenue (2) | -- | 1,193 | -976 | -
| Other | -- | 381 | -195 | -
| Total other long-term liabilities | -$ | -7,306 $ | -4,245 | -
| - | - | Jan 25, 2026 Jan 26, 2025 | -- |
| - | - | (In millions) | -- |
| Balance at beginning of period | -$ | -1,813 $ | -1,337 | -
| Deferred revenue additions (1) | -- | 11,137 | -5,083 | -
| Revenue recognized (2) | -- | (10,378) | -(4,607) | -
| Balance at end of period | -$ | -2,572 $ | -1,813 | -
| - | Expected | -Effective | -- | - |
| - | Remaining Term | -Interest | -- | - |
| - | (years) | -Rate | -Jan 25, 2026 Jan 26, 2025 | -- |
| - | - | - | (In millions) | -- |
| 3.20% Notes Due 2026 | -0.6 | -3.31% | -1,000 | -1,000 | -
| 1.55% Notes Due 2028 | -2.4 | -1.64% | -1,250 | -1,250 | -
| 2.85% Notes Due 2030 | -4.2 | -2.93% | -1,500 | -1,500 | -
| 2.00% Notes Due 2031 | -5.4 | -2.09% | -1,250 | -1,250 | -
| 3.50% Notes Due 2040 | -14.2 | -3.54% | -1,000 | -1,000 | -
| 3.50% Notes Due 2050 | -24.2 | -3.54% | -2,000 | -2,000 | -
| 3.70% Notes Due 2060 | -34.2 | -3.73% | -500 | -500 | -
| Unamortized debt discount and issuance costs | -- | - | (32) | -(37) | -
| Net carrying amount | -- | - | 8,468 | -8,463 | -
| Less short-term portion | -- | - | (999) | -— | -
| - | - | - | - | Year Ended | -- | - |
| - | - | Jan 25, 2026 | -- | Jan 26, 2025 | -- | Jan 28, 2024 | -
| - | - | - | - | (In millions) | -- | - |
| Balance at beginning of period | -$ | -1,290 | -$ | -306 | -$ | -82 | -
| Additions | -- | 2,474 | -- | 1,203 | -- | 278 | -
| Utilization | -- | (957) | -- | (219) | -- | (54) | -
| Balance at end of period | -$ | -2,807 | -$ | -1,290 | -$ | -306 | -
| - | - | Year Ended | -- |
| - | Jan 25, 2026 | -Jan 26, 2025 | -Jan 28, 2024 | -
| - | - | (In millions) | -- |
| Current income taxes: | -- | - | - |
| Federal | -$ 19,039 | -$ 14,032 | -$ 5,710 | -
| State | -1,218 | -892 | -335 | -
| Foreign | -2,550 | -699 | -502 | -
| Total current | -22,807 | -15,623 | -6,547 | -
| Deferred income taxes: | -- | - | - |
| Federal | -(1,364) | -(4,515) | -(2,499) | -
| State | -(885) | -(242) | -(206) | -
| Foreign | -825 | -280 | -216 | -
| Total deferred | -(1,424) | -(4,477) | -(2,489) | -
| Income tax expense | -$ 21,383 | -$ 11,146 | -$ 4,058 | -
| - | - | Year Ended | -- |
| - | Jan 25, 2026 | -Jan 26, 2025 | -Jan 28, 2024 | -
| - | - | (In millions) | -- |
| U.S. | -$ 123,181 | -$ 77,456 | -$ 29,495 | -
| Foreign | -18,269 | -6,570 | -4,323 | -
| Income before income tax | -$ 141,450 | -$ 84,026 | -$ 33,818 | -
| The income tax expense (benefit) differs from the amount computed by applying the U.S. federal statutory rate of 21.0 | -
| to income before income taxes for the fiscal year ended January 25, 2026 as follows: | -
| Year Ended | -
| Jan 25, 2026 | -
| (In millions, except | -
| percentages) | -
| US Federal Statutory Tax Rate $ 29,704 21.0 % | -
| State and Local Income Taxes, Net of Federal Income Tax Effect (1) 258 0.2 % | -
| Foreign tax effects | -
| Israel | -
| Reduced statutory tax rate on qualifying income (3,064) (2.2) % | -
| Other 1,606 1.2 % | -
| Other foreign jurisdictions 741 0.5 % | -
| Effect of cross-border tax laws | -
| Foreign-derived deduction eligible income (4,208) (3.0)% | -
| Other (142) (0.1) % | -
| Tax credits (1,933) (1.4) % | -
| Nontaxable or nondeductible items | -
| Stock-based compensation (1,475) (1.0)% | -
| Other 29 — % | -
| Other (2) (133) (0.1) % | -
| Income tax expense $ 21,383 15.1 % | -
| - | - | - | Year Ended | -- | - |
| - | - | Jan 26, 2025 | -Jan 28, 2024 | -- | - |
| - | - | (In millions, except percentages) | -- | - | - |
| Tax expense computed at federal statutory rate | -$ | -17,645 | -21.0 % $ 7,102 | -- | 21.0 % | -
| Expense (benefit) resulting from: | -- | - | - | - | - |
| State income taxes, net of federal tax effect | -- | 554 | -0.7 % 120 | -- | 0.4 % | -
| Foreign-derived deduction eligible income | -- | (2,976) | -(3.5) % (1,408) | -- | (4.2)% | -
| Stock-based compensation | -- | (2,097) | -(2.5)% (741) | -- | (2.2) % | -
| U.S. federal research and development tax credit | -- | (990) | -(1.2) % (431) | -- | (1.3) % | -
| Foreign tax rate differential | -- | (984) | -(1.2) % (467) | -- | (1.4)% | -
| Other | -- | (6) | -— % (117) | -- | (0.3)% | -
| Income tax expense | -$ | -11,146 | -13.3 % $ 4,058 | -- | 12.0 % | -
| - | Year Ende | -
| - | Jan 25, 202 | -
| - | (In millions) | -
| Federal | -$ 16,7 | -
| State | -- |
| California | -1,0 | -
| Other | -1,0 | -
| Foreign | -- |
| Israel | -1,2 | -
| Other | -1 | -
| Total income taxes paid, net of refunds | -$ 20,2 | -
| - | Jan 25, 2026 Jan 26, 2025 | -- |
| - | (In millions) | -- |
| Deferred tax assets: | -- | - |
| Capitalized research and development expenditure | -$ 5,436 $ | -6,256 | -
| Net controlled foreign corporation tested income deferred tax assets | -5,389 | -2,820 | -
| Accruals and reserves, not currently deductible for tax purposes | -3,644 | -2,058 | -
| Research and other tax credit carryforwards | -718 | -759 | -
| Operating lease liabilities | -554 | -299 | -
| Net operating loss and capital loss carryforwards | -443 | -456 | -
| Other deferred tax assets | -679 | -566 | -
| Gross deferred tax assets | -16,863 | -13,214 | -
| Less valuation allowance | -(768) | -(1,610) | -
| Total deferred tax assets | -16,095 | -11,604 | -
| Deferred tax liabilities: | -- | - |
| Equity investments | -(2,227) | -(264) | -
| Unremitted earnings of foreign subsidiaries | -(1,813) | -(891) | -
| Operating lease assets | -(533) | -(286) | -
| Acquired intangibles | -(38) | -(70) | -
| Gross deferred tax liabilities | -(4,611) | -(1,511) | -
| Net deferred tax asset (1) | -$ 11,484 $ | -10,093 | -
| - | Jan 25, 2026 | -Jan 26, 2025 | -Jan 28, 2024 | -
| - | - | (In millions) | -- |
| Balance at beginning of period | -$ 2,861 | -$ 1,670 | -$ 1,238 | -
| Increases in tax positions for current year | -1,959 | -1,268 | -616 | -
| Increases in tax positions for prior years | -57 | -48 | -87 | -
| Lapse in statute of limitations | -(224) | -(27) | -(19) | -
| Decreases in tax positions for prior years | -(157) | -(88) | -(148) | -
| Settlements | -(76) | -(10) | -(104) | -
| Balance at end of period | -$ 4,420 | -$ 2,861 | -$ 1,670 | -
| - | - | Compute & | -- | - | - | - |
| - | - | Networking | -- | Graphics | -- | Total | -
| - | - | - | - | (In millions) | -- | - |
| Year Ended Jan 25, 2026 | -- | - | - | - | - | - |
| Revenue | -$ | -193,479 | -$ | -22,459 | -$ | -215,938 | -
| Other segment items (1) | -- | 63,338 | -- | 13,303 | -- | 76,641 | -
| Operating income | -$ | -130,141 | -$ | -9,156 | -$ | -139,297 | -
| Year Ended Jan 26, 2025 | -- | - | - | - | - | - |
| Revenue | -$ | -116,193 | -$ | -14,304 | -$ | -130,497 | -
| Other segment items (1) | -- | 33,318 | -- | 9,219 | -- | 42,537 | -
| Operating income | -$ | -82,875 | -$ | -5,085 | -$ | -87,960 | -
| Year Ended Jan 28, 2024 | -- | - | - | - | - | - |
| Revenue | -$ | -47,405 | -$ | -13,517 | -$ | -60,922 | -
| Other segment items (1) | -- | 15,389 | -- | 7,671 | -- | 23,060 | -
| Operating income | -$ | -32,016 | -$ | -5,846 | -$ | -37,862 | -
| - | - | Year Ended | -- |
| - | Jan 25, 2026 | -Jan 26, 2025 | -Jan 28, 2024 | -
| - | - | (In millions) | -- |
| Segment operating income | -$ 139,297 | -$ 87,960 | -$ 37,862 | -
| Stock-based compensation expense | -(6,386) | -(4,737) | -(3,549) | -
| Unallocated operating expenses | -(1,997) | -(1,171) | -(728) | -
| Acquisition-related and other costs | -(527) | -(599) | -(613) | -
| Interest income | -2,300 | -1,786 | -866 | -
| Interest expense | -(259) | -(247) | -(257) | -
| Other income, net | -9,022 | -1,034 | -237 | -
| Consolidated income before income tax | -$ 141,450 | -$ 84,026 | -$ 33,818 | -
| - | - | - | - | - | - | - | Year Ended | -- |
| - | - | - | - | - | - | Jan 25, 2026 | -Jan 26, 2025 | -Jan 28, 2024 | -
| Geographic Revenue | -based | -- | upon | -Customer | -Headquarters | -- | - | - |
| Location (1): | -- | - | - | - | - | - | (In millions) | -- |
| United States | -- | - | - | - | - | $ 149,617 | -$ 77,482 | -$ 31,533 | -
| Taiwan (2) | -- | - | - | - | - | 42,345 | -23,600 | -14,912 | -
| China (including Hong Kong) | -- | - | - | - | - | 19,677 | -25,048 | -12,330 | -
| Other | -- | - | - | - | - | 4,299 | -4,367 | -2,147 | -
| Total revenue | -- | - | - | - | - | $ 215,938 | -$ 130,497 | -$ 60,922 | -
| - | - | Year Ended | -- |
| - | Jan 25, 2026 | -Jan 26, 2025 | -Jan 28, 2024 | -
| Revenue by End Market: | -- | (In millions) | -- |
| Data Center | -$ 193,737 | -$ 115,186 | -$ 47,525 | -
| Compute | -162,361 | -102,196 | -38,950 | -
| Networking | -31,376 | -12,990 | -8,575 | -
| Gaming | -16,042 | -11,350 | -10,447 | -
| Professional Visualization | -3,191 | -1,878 | -1,553 | -
| Automotive | -2,349 | -1,694 | -1,091 | -
| OEM and Other | -619 | -389 | -306 | -
| Total revenue | -$ 215,938 | -$ 130,497 | -$ 60,922 | -
| - | Jan 25, 2026 Jan 26, 2025 | -- |
| Long-lived assets: | -(In millions) | -- |
| United States | -$ 5,125 $ | -3,626 | -
| Taiwan | -3,219 | -1,481 | -
| Israel | -1,471 | -840 | -
| Other | -568 | -336 | -
| Total long-lived assets | -$ 10,383 $ | -6,283 | -
| - | - | Operating Lease | -
| - | - | Obligations | -
| - | - | (In millions) | -
| Fiscal Year: | -- | - |
| 2027 | -$ | -493 | -
| 2028 | -- | 485 | -
| 2029 | -- | 457 | -
| 2030 | -- | 381 | -
| 2031 | -- | 314 | -
| 2032 and thereafter | -- | 1,494 | -
| Total | -- | 3,624 | -
| Less imputed interest | -- | 680 | -
| Present value of net future minimum lease payments | -- | 2,944 | -
| Less short-term operating lease liabilities | -- | 372 | -
| Long-term operating lease liabilities | -$ | -2,572 | -
| - | - | - | - | - | Year Ended | -- | - | - | - |
| - | - | Jan 25, 2026 | -- | - | Jan 26, 2025 | -- | - | Jan 28, 2024 | -- |
| - | - | - | - | - | (In millions) | -- | - | - | - |
| Supplemental cash flows information | -- | - | - | - | - | - | - | - | - |
| Operating cash flow used for operating leases | -$ | -428 | -- | $ | -- | 313.0 | -$ | -- | 286.0 | -
| Operating lease assets obtained in exchange | -- | - | - | - | - | - | - | - | - |
| for lease obligations | -$ | -1,439 | -- | $ | -- | 877.0 | -$ | -- | 531.0 | -
| - | Balance at | -- | - | - | - | - |
| - | Beginning of | -- | - | - | - | Balance at | -
| Description | -Period | -- | Additions | -Deductions | -- | End of Period | -
| - | - | - | (In millions) | -- | - | - |
| Fiscal year 2026 | -- | - | - | - | - | - |
| Allowance for doubtful accounts | -$ 4 | -$ | -— | -(1) $ — (1) | -- | $ 4 | -
| Sales return allowance | -$ 82 | -$ | -188 | -(2) $ (100) (4) | -- | $ 170 | -
| Deferred tax valuation allowance | -$ 1,610 | -$ | -31 | -(3) $ (873) (3) | -- | $ 768 | -
| Fiscal year 2025 | -- | - | - | - | - | - |
| Allowance for doubtful accounts | -$ 4 | -$ | -— | -(1) $ — (1) | -- | $ 4 | -
| Sales return allowance | -$ 109 | -$ | -151 | -(2) $ (178) (4) | -- | $ 82 | -
| Deferred tax valuation allowance | -$ 1,552 | -$ | -58 | -(3) $ — (3) | -- | $ 1,610 | -
| Fiscal year 2024 | -- | - | - | - | - | - |
| Allowance for doubtful accounts | -$ 4 | -$ | -— | -(1) $ — (1) | -- | $ 4 | -
| Sales return allowance | -$ 26 | -$ | -213 | -(2) $ (130) (4) | -- | $ 109 | -
| Deferred tax valuation allowance | -$ 1,484 | -$ | -162 | -(3) $ (94) (3) | -- | $ 1,552 | -
| 2007 Plan | -NVIDIA Corporation Amended and Restated 2007 Equity Incentive Plan | -
| AC | -Audit Committee of the Board | -
| ASC 718 | -Financial Accounting Standards Board Accounting Standards Codification Topic 718: Compensation - Stock | -
| - | Compensation | -
| Base Compensation | -Performance goal necessary to earn the target award under the Variable Cash Plan and for the target | -
| Plan | -numbers of SY PSUs and MY PSUs to become eligible to vest | -
| Board | -The Company’s board of directors | -
| Bylaws | -The Company’s Amended and Restated Bylaws | -
| CAP | -“Compensation actually paid,” as defined under Item 402(v) of Regulation S-K | -
| CC | -Compensation Committee of the Board | -
| CD&A | -Compensation Discussion and Analysis | -
| CEO | -Chief Executive Officer | -
| CFO | -Chief Financial Officer | -
| Charter | -The Company’s Restated Certificate of Incorporation | -
| Control Number | -Identification number for each stockholder included in Notice or proxy card | -
| CS | -Corporate Sustainability | -
| CSSC | -Corporate Sustainability Steering Committee | -
| DEI | -Diversity, Equity, and Inclusion | -
| ERM | -Enterprise Risk Management | -
| ESPP | -NVIDIA Corporation Amended and Restated 2012 Employee Stock Purchase Plan | -
| EVP | -Executive Vice President | -
| Exchange Act | -Securities Exchange Act of 1934, as amended | -
| Fiscal 20__ | -The Company’s fiscal year ended on the last Sunday in January of the stated year | -
| Form 10-K | -The Company’s Annual Report on Form 10-K for Fiscal 2026 filed with the SEC on February 25, 2026 | -
| GAAP | -Generally accepted accounting principles in the United States | -
| GHG | -Greenhouse gas | -
| Internal Revenue | -U.S. Internal Revenue Code of 1986, as amended | -
| Code | -- |
| Lead Director | -Lead independent director | -
| Meeting | -Annual Meeting of Stockholders | -
| MY PSUs | -Multi-year PSUs based on 3-year TSR relative to the S&P 500 with a three-year performance metric, vesting | -
| - | after three years | -
| Nasdaq | -The Nasdaq Stock Market LLC | -
| NCGC | -Nominating and Corporate Governance Committee of the Board | -
| NEOs | -Named Executive Officers consisting of our CEO, our CFO, and our other three most highly compensated | -
| - | executive officers as of the end of Fiscal 2026 | -
| Non-GAAP Operating | -GAAP operating income, as the Company reports in its SEC filings, excluding stock-based compensation | -
| Income | -expense, acquisition-related and other costs, and other. Please see Reconciliation of Non-GAAP Financial | -
| - | Measures in our CD&A for a reconciliation between the non-GAAP financial measures and GAAP results | -
| Notice | -Notice of Internet Availability of Proxy Materials | -
| NVIDIA, Company, | -NVIDIA Corporation, a Delaware corporation | -
| we, us, our | -- |
| NYSE | -New York Stock Exchange | -
| PSU | -Performance stock unit | -
| PwC | -PricewaterhouseCoopers LLP | -
| RSU | -Restricted stock unit | -
| S&P 500 | -Standard & Poor’s 500 Composite Index | -
| SEC | -U.S. Securities and Exchange Commission | -
| Section 162(m) | -Section 162(m) of the Internal Revenue Code | -
| Securities Act | -Securities Act of 1933, as amended | -
| Stretch | -Performance goal necessary to earn the maximum award under the Variable Cash Plan and for the maximum | -
| Compensation Plan | -numbers of SY PSUs and MY PSUs to become eligible to vest | -
| SY PSUs | -PSUs based on annual Non-GAAP Operating Income performance with a single-year performance metric, | -
| - | vesting over four years | -
| Threshold | -Minimum performance goal necessary to earn an award under the Variable Cash Plan and for SY PSUs and MY | -
| - | PSUs to become eligible to vest | -
| TSR | -Total shareholder return | -
| Variable Cash Plan | -The Company’s variable cash compensation plan | -
| - | Fiscal 2026 Results | -- |
| Revenue | -Gross Margin Operating Income | -Diluted Earnings Per | -
| - | - | Share | -
| $215.9 billion | -71.1% $130.4 billion | -$4.90 | -
| up 65% year on year | -down 3.9 points year on year up 60% year on year | -up 67% year on year | -
| Fiscal 2026 Reportable Segments | -
| Our two reportable segments are “Compute & Networking” and “Graphics”: | -
| Compute & Networking Graphics Total | -
| $193.5 billion (1) $22.5 billion (1) $215.9 billion | -
| Revenue | -
| up 67% year on year up 57% year on year up 65% year on year | -
| Operating $130.1 billion $9.2 billion $139.3 billion | -
| Income (2) up 57% year on year up 80% year on year up 58% year on year | -
| (1)This figure has been rounded to the nearest tenth of a billion. Due to rounding, the sum of the figures does not equal the total as presented. | -
| (2)Segment operating income differs from consolidated operating income as certain expenses are not allocated to either Compute & Networking or | -
| - | - | - | - | - | Effect of | -
| - | - | Board | -Vote Required | -Effect of | -Broker Non- | -
| Matter | -Page | -Recommends | -for Approval | -Abstentions | -Votes | -
| Management Proposals: | -- | - | - | - | - |
| - | - | FOR each | -- | - | - |
| 1 Election of Ten Directors | -14 | -director | -More FOR than AGAINST | -None | -None | -
| - | - | nominee | -votes | -- | - |
| - | - | - | Majority of shares present, | -- | - |
| 2 Advisory Approval of Our Executive Compensation | -37 | -FOR | -in person or represented by proxy, and entitled to | -Against | -None | -
| - | - | - | vote on this matter | -- | - |
| Ratification of the Selection | -- | - | - | - | - |
| of PwC as Our Independent | -- | - | Majority of shares present, | -- | - |
| 3 Registered Public | -58 | -FOR | -in person or represented | -- | - |
| Accounting Firm for Fiscal | -- | - | by proxy, and entitled to | -Against | -N/A* | -
| 2027 | -- | - | vote on this matter | -- | - |
| Stockholder Proposals: | -- | - | - | - | - |
| - | - | - | Majority of shares present, | -- | - |
| Simple Majority Vote 4 | -61 | -AGAINST | -in person or represented | -- | - |
| Standard | -- | - | by proxy, and entitled to | -Against | -None | -
| - | - | - | vote on this matter | -- | - |
| Report on Faith-Based | -- | - | Majority of shares present, | -- | - |
| 5 Community Resource | -63 | -AGAINST | -in person or represented by proxy, and entitled to | -Against | -None | -
| Groups | -- | - | vote on this matter | -- | - |
| - | - | - | Majority of shares present, | -- | - |
| Report on Workforce Civil 6 NoneLiberties | -65 | -AGAINST | -in person or represented by proxy, and entitled to | -Against | -- |
| - | - | - | vote on this matter | -- | - |
| - | - | - | Majority of shares present, | -- | - |
| Greenhouse Gas Emissions 7 | -67 | -AGAINST | -in person or represented | -- | - |
| Disclosure | -- | - | by proxy, and entitled to | -Against | -None | -
| - | - | - | vote on this matter | -- | - |
| - | - | Director | -- | Financial | -Committee | -Public Company | -
| Name | -Age | -Since | -Independent | -Expert (1) | -Membership | -Boards | -
| Tench Coxe | -68 | -1993 | -ü | -- | AC, CC | -- |
| John O. Dabiri | -46 | -2020 | -ü | -- | CC, NCGC | -- |
| Jen-Hsun Huang | -63 | -1993 | -- | - | - | - |
| Dawn Hudson | -68 | -2013 | -ü | -ü | -CC Chairperson | -- |
| Harvey C. Jones | -73 | -1993 | -ü | -ü | -AC, NCGC | -- |
| Melissa B. Lora | -63 | -2023 | -ü | -ü | -AC, NCGC | -1 | -
| Stephen C. Neal | -- | - | - | - | - | - |
| - | 77 | -2019 | -- | - | NCGC Chairperson | -- |
| (Lead Director) | -- | - | ü | -- | - | - |
| A. Brooke Seawell | -78 | -1997 | -ü | -ü | -AC Chairperson | -1 | -
| Aarti Shah | -61 | -2020 | -ü | -- | AC, CC | -1 | -
| Mark A. Stevens | -66 | -2008 (2) | -ü | -- | CC, NCGC | -- |
| - | - | PERFORMANCE GOALS | -- |
| - | Variable Cash Plan | -SY PSUs | -MY PSUs | -
| - | Fiscal 2026 Revenue Opportunity % of Target Payout as a | -Fiscal 2026 Non- GAAP Operating Income (1) Target Opportunity Shares Eligible to Vest as a % of | -Fiscal 2024 to 20263-Year Relative TSR Target OpportunityShares Eligible to Vest as a % of | -
| Threshold | -$100.0 billion 50% | -$46.0 billion 50% | -25th percentile 25% | -
| Base Compensation | -- | - | - |
| Plan | -$130.0 billion 100% | -$71.0 billion 100% | -50th percentile 100% | -
| Compensation Plan | -$160.0 billion (2) 200% | -$96.0 billion (2) | -Other NEOs 200% | -- | 75th percentile Other NEOs 200% | -
| - | PERFORMANCE ACHIEVEMENT AND PAYOUTS | -- | - | - | - |
| - | Variable Cash Plan | -SY PSUs | -- | - | MY PSUs | -
| Performance | -- | - | - | - | - |
| Achievement for | -$215.9 billion | -$137.3 billion | -- | - | 100th percentile | -
| Period Ended Fiscal | -revenue | -Non-GAAP Operating Income (1) | -- | - | 3-year TSR relative to S&P 500 | -
| 2026 (3) | -- | - | - | - | (1,055%) | -
| Payout as % of Target Opportunity | -200% | -CEO 150% Other NEOs 200% | -- | - | CEO 150%Other NEOs 200% | -
| Proposal | -- | - | Effect of | -Broker | -
| Number | -Proposal Description | -Vote Required for Approval | -Abstentions | -Non-Votes | -
| 1 | -Election of ten directors | -More FOR than AGAINST votes | -None | -None | -
| 2 | -Advisory approval of our executive compensation | -Majority of shares present, in person or represented by proxy, and entitled to vote on this matter | -Against | -None | -
| - | Ratification of the selection of PwC | -Majority of shares present, in | -- | - |
| 3 | -as our independent registered public | -person or represented by proxy, | -Against | -N/A* | -
| - | accounting firm for Fiscal 2027 | -and entitled to vote on this matter | -- | - |
| 4 | -Stockholder Proposal: Simple Majority Vote Standard | -Majority of shares present, in person or represented by proxy, and entitled to vote on this matter | -Against | -None | -
| - | Stockholder Proposal: Report on | -Majority of shares present, in | -- | - |
| 5 | -Faith-Based Community Resource | -person or represented by proxy, | -Against | -None | -
| - | Groups | -and entitled to vote on this matter | -- | - |
| 6 | -Stockholder Proposal: Report on Workforce Civil Liberties | -Majority of shares present, in person or represented by proxy, and entitled to vote on this matter | -Against | -None | -
| 7 | -Stockholder Proposal: Greenhouse Gas Emissions Disclosure | -Majority of shares present, in person or represented by proxy, and entitled to vote on this matter | -Against | -None | -
| - | - | - | - | - | - | - | Other Public | -
| - | - | Director | -- | - | Financial | -Committee | -Company | -
| Name | -Age | -Since Occupation | -Independent | -- | Expert (1) | -Membership | -Boards | -
| Tench Coxe | -68 | -1993 Former Managing Director, Sutter Hill Ventures | -ü | -- | - | AC, CC | -- |
| - | - | Centennial Professor of | -- | - | - | - | - |
| John O. Dabiri | -46 | -2020 Aeronautics and Mechanical Engineering, California Institute | -ü | -- | - | CC, NCGC | -- |
| - | - | of Technology | -- | - | - | - | - |
| Jen-Hsun Huang | -63 | -1993 President & CEO, NVIDIA Corporation | -- | - | - | - | - |
| - | - | Former Chief Marketing Officer, | -- | - | - | - | - |
| Dawn Hudson | -68 | -2013 National Football League & Former CEO Pepsi-Cola North | -ü | -- | ü | -CC Chairperson | -- |
| - | - | America | -- | - | - | - | - |
| Harvey C. Jones | -73 | -1993 Managing Partner, Square Wave Ventures | -ü | -- | ü | -AC, NCGC | -- |
| Melissa B. Lora | -63 | -2023 Former President, Taco Bell International | -ü | -- | ü | -AC, NCGC | -1 | -
| Stephen C. Neal | -- | - | - | - | - | - | - |
| ü(Lead Director) | -77 | -2019 Chairman Emeritus & Senior Counsel, Cooley LLP | -- | - | - | NCGC Chairperson | -- |
| A. Brooke Seawell | -78 | -1997 Venture Partner, New Enterprise Associates | -ü | -- | ü | -AC Chairperson | -1 | -
| - | - | Former Senior Vice President & | -- | - | - | - | - |
| Aarti Shah | -61 | -2020 Chief Information and Digital | -ü | -- | - | AC, CC | -1 | -
| - | - | Officer, Eli Lilly and Company | -- | - | - | - | - |
| Mark A. Stevens | -66 | -2008 (2) Managing Partner, S-Cubed Capital | -ü | -- | - | CC, NCGC | -- |
| Name | -Fees Earned or Paid in Cash ($) | -Stock Awards ($) (1) | -Total ($) | -
| Robert K. Burgess (2) | -63,750 | -278,809 | -342,559 | -
| Tench Coxe | -85,000 | -278,809 | -363,809 | -
| John O. Dabiri | -85,000 | -278,809 | -363,809 | -
| Persis S. Drell | -85,000 | -278,809 | -363,809 | -
| Dawn Hudson | -85,000 | -278,809 | -363,809 | -
| Harvey C. Jones | -85,000 | -278,809 | -363,809 | -
| Melissa B. Lora | -85,000 | -278,809 | -363,809 | -
| Stephen C. Neal | -85,000 | -278,809 | -363,809 | -
| Ellen Ochoa (3) | -42,500 | -278,809 | -321,309 | -
| A. Brooke Seawell | -85,000 | -278,809 | -363,809 | -
| Aarti Shah | -85,000 | -278,809 | -363,809 | -
| Mark A. Stevens | -85,000 | -278,809 | -363,809 | -
| Name | -RSUs | -Name | -RSUs | -
| Robert K. Burgess (1) | -— | -Melissa B. Lora (3) | -1,880 | -
| Tench Coxe | -900 | -Stephen C. Neal | -900 | -
| John O. Dabiri | -900 | -Ellen Ochoa (4) | -— | -
| Persis S. Drell (2) | -— | -A. Brooke Seawell | -900 | -
| Dawn Hudson | -900 | -Aarti Shah | -900 | -
| Harvey C. Jones | -900 | -Mark A. Stevens | -900 | -
| - | - | - | - | Total Shares | -- |
| - | - | - | Shares Issuable | -Beneficially | -- |
| - | Name of Beneficial Owner | -Shares Owned | -Within 60 Days | -Owned | -Percent | -
| NEOs: | -- | - | - | - | - |
| Jen-Hsun Huang | -- | 870,604,104 (1) | -— | -870,604,104 | -3.58% | -
| Colette M. Kress | -- | 4,443,523 (2) | -— | -4,443,523 | -* | -
| Ajay K. Puri | -- | 3,266,897 (3) | -— | -3,266,897 | -* | -
| Debora Shoquist | -- | 1,580,729 (4) | -— | -1,580,729 | -* | -
| Timothy S. Teter | -- | 2,687,197 (5) | -— | -2,687,197 | -* | -
| Directors, not including Mr. Huang: | -- | - | - | - | - |
| Tench Coxe | -- | 30,555,240 (6) | -— | -30,555,240 | -* | -
| John O. Dabiri | -- | 13,888 | -900 | -14,788 | -* | -
| Dawn Hudson | -- | 367,987 | -900 | -368,887 | -* | -
| Harvey C. Jones | -- | 7,002,787 (7) | -900 | -7,003,687 | -* | -
| Melissa B. Lora | -- | 899 (8) | -900 | -1,799 | -* | -
| Stephen C. Neal | -- | 183,967 (9) | -900 | -184,867 | -* | -
| A. Brooke Seawell | -- | 2,505,707 (10) | -900 | -2,506,607 | -* | -
| Aarti Shah | -- | 25,620 (11) | -— | -25,620 | -* | -
| Mark A. Stevens | -- | 34,068,672 (12) | -900 | -34,069,572 | -* | -
| Directors and executive officers as a group (14 persons) | -- | 957,307,217 (13) | -6,300 | -957,313,517 | -3.94% | -
| 5% Stockholders: | -- | - | - | - | - |
| BlackRock, Inc. | -- | 1,805,935,550 (14) | -— | -1,805,935,550 | -7.43% | -
| Vanguard Capital Management | -- | 1,777,408,252 (15) | -— | -1,777,408,252 | -7.31% | -
| - | - | Fiscal 2026 Non-GAAP | -3-Year TSR Relative to S&P 500 | -
| - | Fiscal 2026 Revenue | -Operating Income (1) | -(Fiscal 2024 to 2026) (2) | -
| Stretch Compensation Plan Goal | -$160.0 billion (3) | -$96.0 billion (3) | -75th percentile | -
| Performance Achievement for | -- | - | - |
| Period Ended Fiscal 2026 | -$215.9 billion | -$137.3 billion | -100th Percentile (1,055%) | -
| Alphabet Inc. (GOOG) | -Meta Platforms, Inc. (META) | -
| Amazon.com, Inc. (AMZN) | -Microsoft Corporation (MSFT) | -
| Apple Inc. (AAPL) | -Netflix, Inc. (NFLX) | -
| Broadcom Inc. (AVGO) | -Oracle Corporation (ORCL) | -
| Cisco Systems, Inc. (CSCO) | -Qualcomm Incorporated (QCOM) | -
| International Business Machines Corporation (IBM) | -Salesforce, Inc. (CRM) | -
| Intel Corporation (INTC) | -Visa Inc. (V) | -
| - | Fixed | -- | - | - | - | - | - |
| - | Compensation | -- | - | - | At-Risk Compensation | -- | - |
| - | Base Salary | -Variable Cash | -- | SY PSUs | -MY PSUs | -- | RSUs (1) | -
| Form | -Cash | -Cash | -Equity | -- | Equity | -Equity | -- |
| Who | -NEOs | -NEOs | -NEOs | -- | NEOs | -NEOs (except our CEO, | -- |
| Receives | -- | - | - | - | - | whose equity awards | -- |
| - | - | - | - | - | - | are solely PSUs) | -- |
| Performance | -N/A | -Revenue | -Non-GAAP Operating Income | -- | TSR relative to the S&P 500 | -N/A | -- |
| Measure | -- | (determines | -(determines number of shares | -- | (determines number of | -- | - |
| - | - | cash payout) | -eligible to vest) | -- | shares eligible to vest) | -- | - |
| Performance | -N/A | -1 year | -1 year | -- | 3 years | -N/A | -- |
| Period | -- | - | - | - | - | - | - |
| Vesting | -N/A | -N/A | -4 years from grant | -- | 3 years from grant | -4 years from grant | -- |
| Period | -- | - | - | - | - | - | - |
| Vesting | -N/A | -N/A | -If at least Threshold goal achieved, | -- | If at least Threshold goal | -6.25% vests quarterly | -- |
| Terms | -- | - | 25% on approximately the 1-year | -- | achieved, 100% on | -from the grant date (2) | -- |
| - | - | - | anniversary of the grant date; | -- | approximately the 3-year | -- | - |
| - | - | - | 6.25% quarterly thereafter | -- | anniversary of the grant | -- | - |
| Timeframe | -Annual | -Annual | -Long-term | -- | dLoanteg-term | -Long-term | -- |
| Emphasized | -- | - | - | - | - | - | - |
| Purpose | -Compensate | -Reward for | -Align with stockholder interests by | -- | Align with long-term | -Align with stockholder | -- |
| - | for expected | -annual | -linking NEO pay to annual | -- | stockholder interests by | -interests by linking NEO | -- |
| - | day-to-day | -corporate | -operational performance and | -- | linking NEO pay to multi-year | -pay to ongoing stock | -- |
| - | performance | -financial | -ongoing stock price performance | -- | relative shareholder return | -price performance | -- |
| - | - | performance | -during the vesting period | -- | and ongoing stock price | -- | - |
| - | - | - | - | - | performance during the | -- | - |
| - | - | - | - | - | vesting period | -- | - |
| Maximum | -N/A | -200% of | -150% of Mr. Huang’s SY PSU target | -- | 150% of Mr. Huang’s MY PSU | -100% of grant | -- |
| Amount That | -- | target | -opportunity and 200% of our other | -- | target opportunity and 200% | -- | - |
| Can Be | -- | opportunity | -NEOs’ respective SY PSU target | -- | of our other NEOs’ respective | -Ultimate value delivered | -- |
| Earned | -- | under our | -opportunity | -- | MY PSU target opportunity | -depends on stock price | -- |
| - | - | Variable Cash | -- | - | - | on date shares vest | -- |
| - | - | Plan | -Ultimate value delivered depends | -- | Ultimate value delivered | -- | - |
| - | - | - | on stock price on date earned | -- | depends on stock price on | -- | - |
| - | - | Variable Cash Plan | -SY PSUs | -MY PSUs | -
| Metric | -Revenue | -- | Non-GAAP Operating Income | -TSR relative to the S&P 500 | -
| Timeframe | -1 year | -- | 1 year | -3 years | -
| CC’s Rationale for | -Drives value, contributes to | -- | Drives value, contributes to | -Aligns directly with long-term | -
| Metric | -Company’s long-term success | -- | Company’s long-term success | -shareholder value creation | -
| - | Focuses on growth in new and | -- | Reflects our annual revenue | -Provides comparison of our stock | -
| - | existing markets | -- | generation and effective operating | -price performance, including | -
| - | - | - | expense management | -dividends, against a capital market | -
| - | Distinct, separate metric from Non- | -- | - | index in which we compete | -
| - | GAAP Operating Income | -- | Distinct, separate metrics from | -- |
| - | - | - | revenue | -Relative performance goal accounts | -
| - | - | - | - | for macroeconomic factors impacting | -
| - | - | - | - | the market | -
| - | - | PERFORMANCE GOALS | -- | - |
| - | Variable Cash Plan | -SY PSUs | -- | MY PSUs | -
| - | Fiscal 2026 Payout as a % of | -Fiscal 2026 Non- Shares Eligible to Vest as a % of | -Fiscal 2026 to 2028 | -Shares Eligible to Vest as a % of | -
| - | Revenue Opportunity (1) Target | -GAAP Operating Income (2) Opportunity (1) Target | -3-Year Relative TSR (3) | -Target Opportunity (1) | -
| Threshold | -$100.0 billion 50% | -$46.0 billion 50% | -25th percentile | -25% | -
| Base Compensation | -- | - | - | - |
| Plan | -$130.0 billion 100% | -$71.0 billion 100% | -50th percentile | -100% | -
| Stretch Compensation Plan | -$160.0 billion (4) 200% | -$96.0 billion (4) Other NEOs 200% CEO 150% | -75th percentile | -CEO 150% Other NEOs 200% | -
| - | PERFORMANCE ACHIEVEMENT AND PAYOUTS | -
| - | Variable Cash Plan SY PSUs MY PSUs (1) | -
| Performance | -100th percentile | -
| Achievement for Period | -$215.9 billion $137.3 billion | -
| Ended Fiscal 2026 (2) | -revenue Non-GAAP Operating Income (3)3-year TSR relative to S&P 500 (1,055%) | -
| Payout as % of Target Opportunity | -200% Other NEOs 200% (4) CEO 150% Other NEOs 200% (5)CEO 150% | -
| (1) Represents performance achievement and payout of MY PSUs granted in Fiscal 2024, with a performance period measured from the start of Fiscal | -- |
| Jen-Hsun Huang | -- | - | - |
| President & CEO | -Target Pay ($) | -Fiscal 2026 Compensation Actions | -Fiscal 2026 Performance-Based Payouts | -
| Base Salary | -1,500,000 | -Flat with Fiscal 2025 | -- |
| - | - | - | Fiscal 2026 revenue exceeded Stretch Compensation Plan | -
| Variable Cash | -3,000,000 | -Flat with Fiscal 2025 | -goal, resulting in 200% payout under Variable Cash Plan | -
| - | - | - | ($6,000,000) | -
| Cash | -4,500,000 | -Flat with Fiscal 2025 | -- |
| - | - | Up $1.8 million, or 13%, from Fiscal 2025 | -Fiscal 2026 Non-GAAP Operating Income exceeded Stretch | -
| SY PSUs | -15,500,000 | -target, resulting in 119,607 shares target | -Compensation Plan goal, resulting in 150% of target | -
| - | - | opportunity granted in Fiscal 2026 | -opportunity (179,411 shares) becoming eligible to vest | -
| - | - | Up $1.8 million, or 13%, from Fiscal 2025 | -Fiscal 2024 to Fiscal 2026 3-Year Relative TSR for MY PSUs | -
| MY PSUs | -15,500,000 | -target, resulting in 119,607 shares target | -granted in Fiscal 2024 achieved at Stretch Compensation | -
| - | - | opportunity granted in Fiscal 2026 | -Plan level, resulting in 150% of target opportunity (757,360 shares) becoming eligible to vest | -
| Equity | -31,000,000 | -Up $3.5 million, or 13%, from Fiscal 2025 target | -- |
| TOTAL | -35,500,000 | -Up $3.5 million, or 11%, from Fiscal 2025 target | -- |
| EVP & CFO | -Target Pay ($) | -Fiscal 2026 Compensation Actions | -Fiscal 2026 Performance-Based Payouts | -
| Base Salary | -900,000 | -Flat with Fiscal 2025 | -- |
| - | - | - | Fiscal 2026 revenue exceeded Stretch Compensation Plan | -
| Variable Cash | -300,000 | -Flat with Fiscal 2025 | -goal, resulting in 200% payout under Variable Cash Plan | -
| - | - | - | ($600,000) | -
| Cash | -1,200,000 | -Flat with Fiscal 2025 | -- |
| - | - | Up $0.2 million, or 7%, from Fiscal 2025 | -Fiscal 2026 Non-GAAP Operating Income exceeded Stretch | -
| SY PSUs | -3,699,807 | -target, resulting in 28,550 shares target | -Compensation Plan goal, resulting in 200% of target | -
| - | - | opportunity granted in Fiscal 2026 | -opportunity (57,100 shares) becoming eligible to vest | -
| - | - | Up $0.2 million, or 7%, from Fiscal 2025 | -Fiscal 2024 to Fiscal 2026 3-Year Relative TSR for MY PSUs | -
| MY PSUs | -3,699,807 | -target, resulting in 28,550 shares target | -granted in Fiscal 2024 achieved at Stretch Compensation | -
| - | - | opportunity granted in Fiscal 2026 | -Plan level, resulting in 200% of target opportunity (49,560 shares) becoming eligible to vest | -
| - | - | Up $0.5 million, or 7%, from Fiscal 2025, | -- |
| RSUs | -7,400,386 | -resulting in 57,106 shares granted in Fiscal | -- |
| - | - | 2026 | -- |
| Equity | -14,800,000 | -Up $1.0 million, or 7%, from Fiscal 2025 target | -- |
| TOTAL | -16,000,000 | -Up $1.0 million, or 7%, from Fiscal 2025 target | -- |
| Ajay K. Puri | -- | - | - |
| EVP, Worldwide Field | -- | - | - |
| Operations | -Target Pay ($) | -Fiscal 2026 Compensation Actions | -Fiscal 2026 Performance-Based Payouts | -
| Base Salary | -950,000 | -Flat with Fiscal 2025 | -- |
| - | - | - | Fiscal 2026 revenue exceeded Stretch Compensation Plan | -
| Variable Cash | -650,000 | -Flat with Fiscal 2025 | -goal, resulting in 200% payout under Variable Cash Plan | -
| - | - | - | ($1,300,000) | -
| Cash | -1,600,000 | -Flat with Fiscal 2025 | -- |
| - | - | Up $0.3 million, or 7%, from Fiscal 2025 | -Fiscal 2026 Non-GAAP Operating Income exceeded Stretch | -
| SY PSUs | -3,600,000 | -target, resulting in 27,779 shares target | -Compensation Plan goal, resulting in 200% of target | -
| - | - | opportunity granted in Fiscal 2026 | -opportunity (55,558 shares) becoming eligible to vest | -
| - | - | Up $0.3 million, or 7%, from Fiscal 2025 | -Fiscal 2024 to Fiscal 2026 3-Year Relative TSR for MY PSUs | -
| MY PSUs | -3,600,000 | -target, resulting in 27,779 shares target | -granted in Fiscal 2024 achieved at Stretch Compensation | -
| - | - | opportunity granted in Fiscal 2026 | -Plan level, resulting in 200% of target opportunity (47,720 shares) becoming eligible to vest | -
| - | - | Up $0.5 million, or 7%, from Fiscal 2025, | -- |
| RSUs | -7,200,000 | -resulting in 55,559 shares granted in Fiscal | -- |
| - | - | 2026 | -- |
| Equity | -14,400,000 | -Up $1.0 million, or 7%, from Fiscal 2025 | -- |
| Debora Shoquist | -- | - | - |
| EVP, Operations | -Target Pay ($) | -Fiscal 2026 Compensation Actions | -Fiscal 2026 Performance-Based Payouts | -
| Base Salary | -850,000 | -Flat with Fiscal 2025 | -- |
| - | - | - | Fiscal 2026 revenue exceeded Stretch Compensation Plan | -
| Variable Cash | -250,000 | -Flat with Fiscal 2025 | -goal, resulting in 200% payout under Variable Cash Plan | -
| - | - | - | ($500,000) | -
| Cash | -1,100,000 | -Flat with Fiscal 2025 | -- |
| - | - | Up $0.6 million, or 20%, from Fiscal 2025 | -Fiscal 2026 Non-GAAP Operating Income exceeded Stretch | -
| SY PSUs | -3,725,000 | -target, resulting in 28,744 shares target | -Compensation Plan goal, resulting in 200% of target | -
| - | - | opportunity granted in Fiscal 2026 | -opportunity (57,488 shares) becoming eligible to vest | -
| - | - | Up $0.6 million, or 20%, from Fiscal 2025 | -Fiscal 2024 to Fiscal 2026 3-Year Relative TSR for MY PSUs | -
| MY PSUs | -3,725,000 | -target, resulting in 28,744 shares target | -granted in Fiscal 2024 achieved at Stretch Compensation | -
| - | - | opportunity granted in Fiscal 2026 | -Plan level, resulting in 200% of target opportunity (40,840 shares) becoming eligible to vest | -
| - | - | Up $1.3 million, or 20%, from Fiscal 2025, | -- |
| RSUs | -7,450,000 | -resulting in 57,489 shares granted in Fiscal | -- |
| - | - | 2025 | -- |
| Equity | -14,900,000 | -Up $2.5 million, or 20%, from Fiscal 2025 target | -- |
| TOTAL | -16,000,000 | -Up $2.5 million, or 19%, from Fiscal 2025 target | -- |
| Timothy S. Teter | -- | - | - |
| EVP, General Counsel | -- | - | - |
| & Secretary | -Target Pay ($) | -Fiscal 2026 Compensation Actions | -Fiscal 2026 Performance-Based Payouts | -
| Base Salary | -850,000 | -Flat with Fiscal 2025 | -- |
| - | - | - | Fiscal 2026 revenue exceeded Stretch Compensation Plan | -
| Variable Cash | -250,000 | -Flat with Fiscal 2025 | -goal, resulting in 200% payout under Variable Cash Plan | -
| - | - | - | ($500,000) | -
| Cash | -1,100,000 | -Flat with Fiscal 2025 | -- |
| - | - | Up $0.6 million, or 20%, from Fiscal 2025 | -Fiscal 2026 Non-GAAP Operating Income exceeded Stretch | -
| SY PSUs | -3,725,000 | -target, resulting in 28,744 shares target | -Compensation Plan goal, resulting in 200% of target | -
| - | - | opportunity granted in Fiscal 2026 | -opportunity (57,488 shares) becoming eligible to vest | -
| - | - | Up $0.6 million, or 20%, from Fiscal 2025 | -Fiscal 2024 to Fiscal 2026 3-Year Relative TSR for MY PSUs | -
| MY PSUs | -3,725,000 | -target, resulting in 28,744 shares target | -granted in Fiscal 2024 achieved at Stretch Compensation | -
| - | - | opportunity granted in Fiscal 2026 | -Plan level, resulting in 200% of target opportunity (40,840 shares) becoming eligible to vest | -
| - | - | Up $1.3 million, or 20%, from Fiscal 2025, | -- |
| RSUs | -7,450,000 | -resulting in 57,489 shares granted in Fiscal | -- |
| - | - | 2025 | -- |
| Equity | -14,900,000 | -Up $2.5 million, or 20%, from Fiscal 2025 target | -- |
| TOTAL | -16,000,000 | -Up $2.5 million, or 19%, from Fiscal 2025 | -- |
| A reconciliation between our GAAP operating income and non-GAAP operating income is as follows (in millions): | -- |
| Fiscal 2026 Fiscal 2025 | -- |
| GAAP operating income $130,387 | -$81,453 | -
| Stock-based compensation expense 6,386 | -4,737 | -
| Acquisition-related and other costs 471 | -602 | -
| Other 56 | -(3) | -
| Non-GAAP Operating Income $137,300 | -$86,789 | -
| - | - | - | Stock | -Non-Equity Incentive | -All Other | -- |
| Name and Principal | -Fiscal | -Salary | -Awards | -Plan Compensation | -Compensation | -Total | -
| Position | -Year | -($) | -($) (1) | -($) (2) | -($) | -($) (3) | -
| Jen-Hsun Huang | -2026 | -1,497,627 | -24,800,511 | -6,000,000 | -4,045,691 (4) | -36,343,830 | -
| President and CEO | -- | - | - | - | - | - |
| - | 2025 | -1,486,199 | -38,811,306 | -6,000,000 | -3,568,746 | -49,866,251 | -
| - | 2024 | -996,514 | -26,676,415 | -4,000,000 | -2,494,973 | -34,167,902 | -
| Colette M. Kress | -2026 | -898,577 | -12,825,872 | -600,000 | -16,402 (5) | -14,340,850 | -
| EVP and CFO | -- | - | - | - | - | - |
| - | 2025 | -893,739 | -19,849,891 | -600,000 | -18,902 | -21,362,532 | -
| - | 2024 | -896,863 | -11,756,027 | -600,000 | -13,902 | -13,266,792 | -
| Ajay K. Puri | -2026 | -948,497 | -12,478,989 | -1,300,000 | -49,840 (5) | -14,777,327 | -
| EVP, Worldwide Field | -- | - | - | - | - | - |
| Operations | -2025 | -943,391 | -19,277,046 | -1,300,000 | -70,460 | -21,590,897 | -
| - | 2024 | -946,689 | -11,320,353 | -1,300,000 | -48,408 | -13,615,450 | -
| Debora Shoquist | -2026 | -848,656 | -12,912,487 | -500,000 | -33,567 (5) | -14,294,710 | -
| EVP, Operations | -- | - | - | - | - | - |
| - | 2025 | -844,087 | -17,838,832 | -500,000 | -34,984 | -19,217,903 | -
| - | 2024 | -847,037 | -9,687,599 | -500,000 | -24,229 | -11,058,865 | -
| Timothy S. Teter | -2026 | -848,656 | -12,912,487 | -500,000 | -15,240 (5) | -14,276,382 | -
| EVP, General Counsel and | -- | - | - | - | - | - |
| Secretary | -2025 | -844,087 | -17,838,832 | -500,000 | -18,902 | -19,201,821 | -
| - | 2024 | -847,037 | -9,687,599 | -500,000 | -13,902 | -11,048,538 | -
| to the grant date fair value of the SY PSUs and MY PSUs, the value of stock awards would be: | -- | - |
| Jen-Hsun Huang Colette M. Kress Ajay K. Puri | -Debora Shoquist | -Timothy S. Teter | -
| Fiscal SY PSU MY PSU SY PSU MY PSU SY PSU MY PSU | -SY PSU MY PSU | -SY PSU MY PSU | -
| Year ($) ($) ($) ($) ($) ($) | -($) ($) | -($) ($) | -
| 2026 19,166,424 18,034,343 6,099,993 7,350,483 5,935,261 7,151,981 | -6,141,443 7,400,430 | -6,141,443 7,400,430 | -
| 2025 25,046,748 33,170,211 8,377,781 14,564,690 8,136,366 14,144,993 | -7,529,332 13,089,669 | -7,529,332 13,089,669 | -
| 2024 23,130,937 22,666,270 15,613,188 1,937,350 15,034,811 1,865,423 | -12,866,300 1,596,476 | -12,866,300 1,596,476 | -
| - | - | - | Estimated Possible Payouts Under | -Estimated Future Payouts Under | -- | - |
| - | - | - | Non-Equity Incentive Plan Awards (1) | -Equity Incentive Plan Awards (2) | -All Other Stock | -Grant Date | -
| - | - | - | - | - | Awards: Number | -Fair Value | -
| - | Type of | -Grant | -ThresholdT argetM aximum | -ThresholdTa rgetMaximum | -of Shares of Stock | -of Stock | -
| Name | -Award | -Date | -($) ($) ($) | -(#) (#) (#) | -or Units (#) (3) | -Awards ($) (4) | -
| Jen-Hsun | -SY PSU | -3/10/25 | -— | -59,804 119,607 179,411 | -— | -12,777,616 | -
| Huang | -- | - | - | - | - | - |
| - | MY PSU | -3/10/25 | -— | -29,902 119,607 179,411 | -— | -12,022,896 | -
| - | Variable | -- | - | - | - | - |
| - | Cash Plan | -3/3/25 | -1,500,000 3,000,000 6,000,000 | -— | -— | -— | -
| Colette M. | -SY PSU | -3/10/25 | -— | -14,275 28,550 57,100 | -— | -3,049,997 | -
| Kress | -- | - | - | - | - | - |
| - | MY PSU | -3/10/25 | -— | -7,138 28,550 57,100 | -— | -3,675,242 | -
| - | RSU | -3/10/25 | -— | -— | -57,106 | -6,100,634 | -
| - | Variable | -- | - | - | - | - |
| - | Cash Plan | -3/3/25 | -150,000 300,000 600,000 | -— | -— | -— | -
| Ajay K. | -SY PSU | -3/10/25 | -— | -13,890 27,779 55,558 | -— | -2,967,631 | -
| Puri | -- | - | - | - | - | - |
| - | MY PSU | -3/10/25 | -— | -6,945 27,779 55,558 | -— | -3,575,991 | -
| - | RSU | -3/10/25 | -— | -— | -55,559 | -5,935,368 | -
| - | Variable | -- | - | - | - | - |
| - | Cash Plan | -3/3/25 | -325,000 650,000 1,300,000 | -— | -— | -— | -
| Debora | -SY PSU | -3/10/25 | -— | -14,372 28,744 57,488 | -— | -3,070,722 | -
| Shoquist | -- | - | - | - | - | - |
| - | MY PSU | -3/10/25 | -— | -7,186 28,744 57,488 | -— | -3,700,215 | -
| - | RSU | -3/10/25 | -— | -— | -57,489 | -6,141,550 | -
| - | Variable | -- | - | - | - | - |
| - | Cash Plan | -3/3/25 | -125,000 250,000 500,000 | -— | -— | -— | -
| Timothy S. | -SY PSU | -3/10/25 | -— | -14,372 28,744 57,488 | -— | -3,070,722 | -
| Teter | -- | - | - | - | - | - |
| - | MY PSU | -3/10/25 | -— | -7,186 28,744 57,488 | -— | -3,700,215 | -
| - | RSU | -3/10/25 | -— | -— | -57,489 | -6,141,550 | -
| - | Variable | -- | - | - | - | - |
| - | Cash Plan | -3/3/25 | -125,000 250,000 500,000 | -— | -— | -— | -
| - | Number of | -- | - | Equity Incentive Plan | -
| - | Units of Stock | -Market Value of Units of | -Equity Incentive Plan Awards: | -Awards: Market Value of | -
| - | That Have | -Stock That Have Not | -Number of Unearned Shares | -Unearned Shares That | -
| Name | -Not Vested (#) | -Vested ($) (1) | -That Have Not Vested (#) | -Have Not Vested ($) (1) | -
| Jen-Hsun Huang | -315,570 (2) | -59,223,022 | -— | -— | -
| - | 757,360 (3) | -142,133,751 | -— | -— | -
| - | 161,085 (4) | -30,230,822 | -— | -— | -
| - | 179,411 (5) | -33,670,062 | -— | -— | -
| - | — | -— | -286,350 (6) | -53,739,305 | -
| - | — | -— | -179,411 (7) | -33,670,062 | -
| Colette M. Kress | -10,970 (8) | -2,058,740 | -— | -— | -
| - | 61,970 (9) | -11,629,910 | -— | -— | -
| - | 213,010 (2) | -39,975,587 | -— | -— | -
| - | 49,560 (3) | -9,300,925 | -— | -— | -
| - | 53,890 (10) | -10,113,536 | -— | -— | -
| - | 53,880 (4) | -10,111,660 | -— | -— | -
| - | 46,399 (11) | -8,707,700 | -— | -— | -
| - | 57,100 (5) | -10,715,957 | -— | -— | -
| - | — | -— | -95,780 (6) | -17,975,033 | -
| - | — | -— | -57,100 (7) | -10,715,957 | -
| Ajay K. Puri | -10,560 (8) | -1,981,795 | -— | -— | -
| - | 59,670 (9) | -11,198,269 | -— | -— | -
| - | 205,120 (2) | -38,494,870 | -— | -— | -
| - | 47,720 (3) | -8,955,612 | -— | -— | -
| - | 52,330 (10) | -9,820,771 | -— | -— | -
| - | 52,340 (4) | -9,822,648 | -— | -— | -
| - | 45,142 (11) | -8,471,799 | -— | -— | -
| - | 55,558 (5) | -10,426,570 | -— | -— | -
| - | — | -— | -93,020 (6) | -17,457,063 | -
| - | — | -— | -55,558 (7) | -10,426,570 | -
| Debora Shoquist | -9,040 (8) | -1,696,537 | -— | -— | -
| - | 51,070 (9) | -9,584,307 | -— | -— | -
| - | 175,540 (2) | -32,943,592 | -— | -— | -
| - | 40,840 (3) | -7,664,443 | -— | -— | -
| - | 48,420 (10) | -9,086,981 | -— | -— | -
| - | 48,420 (4) | -9,086,981 | -— | -— | -
| - | 46,710 (11) | -8,766,066 | -— | -— | -
| - | 57,488 (5) | -10,788,773 | -— | -— | -
| - | — | -— | -86,080 (6) | -16,154,634 | -
| - | — | -— | -57,488 (7) | -10,788,773 | -
| Timothy S. Teter | -9,040 (8) | -1,696,537 | -— | -— | -
| - | 51,070 (9) | -9,584,307 | -— | -— | -
| - | 175,540 (2) | -32,943,592 | -— | -— | -
| - | 40,840 (3) | -7,664,443 | -— | -— | -
| - | 48,420 (10) | -9,086,981 | -— | -— | -
| - | 48,420 (4) | -9,086,981 | -— | -— | -
| - | 46,710 (11) | -8,766,066 | -— | -— | -
| - | 57,488 (5) | -10,788,773 | -— | -— | -
| - | — | -— | -86,080 (6) | -16,154,634 | -
| - | Name Number of Shares Acquired on Vesting (#) (1) | -Value Realized on Vesting ($) (2) | -
| Jen-Hsun Huang | -1,113,555 (3) | -141,311,217 | -
| Colette M. Kress | -442,087 (4) | -63,881,560 | -
| Ajay K. Puri | -425,837 (5) | -61,550,468 | -
| Debora Shoquist | -368,879 (6) | -53,412,792 | -
| Timothy S. Teter | -368,879 (7) | -53,412,792 | -
| (1) Represents the gross number of shares acquired on vesting. Shares were withheld from these amounts to pay taxes due upon vesting. | -- | - |
| Name | -Unvested RSUs and PSUs at January 25, 2026 (#) (1) | -Total Estimated Benefit ($) (1) | -
| Jen-Hsun Huang | -1,411,679 | -264,929,798 | -
| Colette M. Kress | -569,889 | -106,951,069 | -
| Ajay K. Puri | -551,090 | -103,423,060 | -
| Debora Shoquist | -500,148 | -93,862,775 | -
| Timothy S. Teter | -500,148 | -93,862,775 | -
| - | Estimated SY PSUs Granted in | -Value of Estimated SY PSUs | -- | - |
| - | Fiscal 2026 at Base | -Granted in Fiscal 2026 at Base | -Actual SY PSUs | -Value of Actual SY PSUs | -
| - | Compensation Plan | -Compensation Plan Performance | -Granted in Fiscal 2026 | -Granted in Fiscal 2026 | -
| Name | -Performance (#) | -($) | -Eligible to Vest (#) | -Eligible to Vest ($) | -
| Jen-Hsun Huang | -119,607 | -22,446,646 | -179,411 | -33,670,062 | -
| Colette M. Kress | -28,550 | -5,357,979 | -57,100 | -10,715,957 | -
| Ajay K. Puri | -27,779 | -5,213,285 | -55,558 | -10,426,570 | -
| Debora Shoquist | -28,744 | -5,394,386 | -57,488 | -10,788,773 | -
| - | Estimated MY PSUs Granted in | -Value of Estimated MY PSUs | -- | - |
| - | Fiscal 2024 at Base | -Granted in Fiscal 2024 at Base | -Actual MY PSUs | -Value of Actual MY PSUs | -
| - | Compensation Plan | -Compensation Plan Performance | -Granted in Fiscal 2024 | -Granted in Fiscal 2024 | -
| Name | -Performance (#) | -($) | -Eligible to Vest (#) | -Eligible to Vest ($) | -
| Jen-Hsun Huang | -504,910 | -94,756,460 | -757,360 | -142,133,751 | -
| Colette M. Kress | -24,780 | -4,650,463 | -49,560 | -9,300,925 | -
| Ajay K. Puri | -23,860 | -4,477,806 | -47,720 | -8,955,612 | -
| Debora Shoquist | -20,420 | -3,832,221 | -40,840 | -7,664,443 | -
| - | - | - | - | - | Value of Initial Fixed $100 | -- | - |
| - | - | - | - | - | Investment Based on (7): | -- | - |
| - | - | - | Average Summary | -Average | -Peer Group | -- | Non-GAAP | -
| - | Summary | -Compensation | -Compensation | -Compensation | -Total Total | -- | Operating | -
| - | Compensation | -Actually Paid | -Table Total for | -Actually Paid to | -Shareholder Shareholder | -Net Income | -Income | -
| Fiscal | -Table Total for CEO | -to CEO | -Non-CEO NEOs | -Non-CEO NEOs | -Return Return | -(in millions) | -(in millions) | -
| Year | -($) (1) (2) | -($) (1) (3) | -($) (4) (5) | -($) (4) (6) | -($) ($) (8) | -($) | -($) (9) | -
| 2026 | -36,343,830 | -162,180,936 | -14,422,317 | -57,721,552 | -1,445.67 198.10 | -120,067 | -137,300 | -
| 2025 | -49,866,251 | -344,188,027 | -20,343,288 | -125,583,913 | -1,100.69 168.46 | -72,880 | -86,789 | -
| 2024 | -34,167,902 | -234,132,305 | -12,247,411 | -85,558,057 | -470.88 134.78 | -29,760 | -37,134 | -
| 2023 | -21,356,924 | -(4,118,947) | -9,941,838 | -(1,364,661) | -157.05 94.13 | -4,368 | -9,040 | -
| 2022 | -23,737,661 | -105,543,768 | -8,910,802 | -38,453,071 | -175.98 111.83 | -9,752 | -12,690 | -
| - | - | Reconciliation of Summary Compensation Table Total Compensation for CEO to CAP | -- |
| - | - | Equity Award Adjustments | -- |
| - | - | (Deduct): Add: Add/(Deduct): Add/(Deduct): | -- |
| - | - | Value of Equity Year End Fair Value Year Over Year Change in Fair | -- |
| - | Summary | -Awards Reported of Awards Granted Change in Fair Value of Awards | -- |
| - | Compensation | -in Summary During the Year Value of Granted in Prior Total Equity | -Compensation | -
| - | Table Total | -Compensation which were Unvested Outstanding and Years which Vested Award | -Actually Paid | -
| scal | -for CEO | -Table at Year End Unvested Awards During the Year Adjustments | -to CEO | -
| ear | -($) | -($) (a) ($) (b) ($) (b) ($) (b) ($) (b) (c) | -($) | -
| - | - | (Deduct): | -Add: | -Add/(Deduct): | -Add: | -Add/(Deduct): | -- | - |
| - | - | - | Year End Fair | -Year Over | -Vesting Date | -Change in Fair | -- | - |
| - | Average | -Value of | -Value of | -Year Change | -Fair Value of | -Value of | -- | - |
| - | Summary | -Equity Awards | -Awards | -in Fair Value | -Awards | -Awards | -- | Average | -
| - | Compensation | -Reported in | -Granted During | -of | -Granted and | -Granted in Prior | -- | Compensation | -
| - | Table Total | -Summary | -the Year which | -Outstanding | -Vested | -Years which | -Total Equity | -Actually Paid | -
| - | for Non-CEO | -Compensation | -were Unvested | -and Unvested | -During the | -Vested During | -Award | -to Non-CEO | -
| Fiscal | -NEOs | -Table | -at Year End | -Awards | -Year | -the Year | -Adjustments | -NEOs | -
| Year | -($) | -($) (a) | -($) (b) | -($) (b) | -($) (b) | -($) (b) | -($) (b) (c) | -($) | -
| 2026 | -14,422,317 | -(12,782,459) | -27,759,180 | -25,940,053 | -1,776,820 | -605,640 | -56,081,694 | -57,721,552 | -
| Financial Measures | -
| Revenue | -
| Non-GAAP Operating Income | -
| 3-Year TSR relative to the S&P 500 | -
| - | - | Fiscal 2026 | -- | Fiscal 2025 | -
| Audit Fees (1) | -$ | -10,166,400 | -$ | -8,067,106 | -
| Audit Related Fees (2) | -- | 1,716,820 | -- | 724,806 | -
| Tax Fees (3) | -- | 1,076,103 | -- | 856,439 | -
| All Other Fees (4) | -- | 401,999 | -- | 354,000 | -
| Total Fees | -$ | -13,361,322 | -$ | -10,002,351 | -
| - | Number of securities to be | -Weighted-average exercise | -Number of securities remaining | -
| - | issued upon exercise of | -price of outstanding | -available for future issuance under | -
| - | outstanding options, | -options, warrants, | -equity compensation plans (excluding | -
| Plan Category | -warrants, and rights (a) | -and rights (b) | -securities reflected in column (a)) (c) | -
| Equity compensation plans | -- | - | - |
| approved by security holders (1) | -192,391,765 | -— | -3,551,257,925 (2) | -
| Equity compensation plans not | -- | - | - |
| approved by security holders | -— | -— | -— | -
| Total | -192,391,765 | -- | 3,551,257,925 | -
| Name | -Age | -Position | -
| Jen-Hsun Huang | -63 | -President and Chief Executive Officer | -
| Colette M. Kress | -58 | -Executive Vice President and Chief Financial Officer | -
| Ajay K. Puri | -71 | -Executive Vice President, Worldwide Field Operations | -
| Debora Shoquist | -71 | -Executive Vice President, Operations | -
| Timothy S. Teter | -59 | -Executive Vice President and General Counsel | -
| - | - | GAAP | -- | - | - | - |
| ($ in millions, except earnings per | -- | - | - | - | - | - |
| share) | -Q1 FY27 | -Q4 FY26 | -Q1 FY26 | -Q/Q | -- | Y/Y | -
| Revenue | -$81,615 | -$68,127 | -$44,062 | -20 % | -- | 85 % | -
| Gross margin | -74.9 % | -75.0 % | -60.5 % | -(0.1) pts | -- | 14.4 pts | -
| Operating expenses | -$7,621 | -$6,794 | -$5,030 | -12 % | -- | 52 % | -
| Operating income | -$53,536 | -$44,299 | -$21,638 | -21 % | -- | 147 % | -
| Net income | -$58,321 | -$42,960 | -$18,775 | -36 % | -- | 211 % | -
| Diluted earnings per share | -$2.39 | -$1.76 | -$0.76 | -36 % | -- | 214 % | -
| ($ in millions, except earnings per | -- | - | - | - | - | - |
| share) | -Q1 FY27 Q4 FY26 | -Q1 FY26 | -- | Q/Q | -- | Y/Y | -
| Revenue | -$81,615 $68,127 | -$44,062 | -- | 20 % | -- | 85 % | -
| Gross margin | -75.0 % 75.1 % | -60.8 % | -- | (0.1) pts | -- | 14.2 pts | -
| Operating expenses | -$7,449 $6,666 | -$4,993 | -- | 12 % | -- | 49 % | -
| Operating income | -$53,783 $44,474 | -$21,801 | -- | 21 % | -- | 147 % | -
| Net income | -$45,548 $38,969 | -$19,094 | -- | 17 % | -- | 139 % | -
| Diluted earnings per share | -$1.87 $1.59 | -$0.78 | -- | 18 % | -- | 140 % | -
| - | Revenue by Reportable Segments | -- | - | - | - | - |
| ($ in millions) | -Q1 FY27 | -Q4 FY26 | -Q1 FY26 | -Q/Q | -- | Y/Y | -- |
| Compute & Networking | -$74,550 | -$61,651 | -$39,589 | -- | 21 % | -- | 88 % | -
| Graphics | -7,065 | -6,476 | -4,473 | -- | 9 % | -- | 58 % | -
| Total | -$81,615 | -$68,127 | -$44,062 | -- | 20 % | -- | 85 % | -
| - | Q1 FY27 | -YoY % | -Q1 FY26 | -
| Revenue | -$81.6 | -85% | -$44.1 | -
| Gross Margin % | -75.0% | -+14.2 pts | -60.8% | -
| Operating Expenses | -$7.4 | -49% | -$5.0 | -
| Operating Income | -$53.8 | -147% | -$21.8 | -
| Net Income | -$45.5 | -139% | -$19.1 | -
| Diluted EPS | -$1.87 | -140% | -$0.78 | -
| - | Q2 FY27 | -- |
| Revenue | -$91.0 billion* | -+ / - 2% | -
| Gross Margin % | -75.0% | -+ / - 50 bps | -
| Operating Expenses | -$8.3 billion | -Approximately | -
| Tax Impact of Q1 FY27 Non-GAAP | -Acquisition-Related GAAPand Other Costs (A) | -Other (B) | -Adjustments | -- | - |
| Gross margin ($ in million) $61,232 | -(47) | -(28) | -— | -- | $61,157 | -
| Gross margin % 75.0% | -(0.1) | -— | -— | -- | 74.9% | -
| Operating expense ($ in million) $7,449 | -172 | -— | -— | -- | $7,621 | -
| Operating income ($ in million) $53,783 | -(219) | -(28) | -— | -- | $53,536 | -
| Net income ($ in million) $45,548 | -(219) | -15,882 | -(2,890) | -- | $58,321 | -
| Diluted shares (millions) 24,391 | -— | -— | -— | -- | 24,391 | -
| Diluted EPS $1.87 | -(0.01) | -0.65 | -(0.12) | -- | $2.39 | -
| Tax Impact of Q1 FY26 Non-GAAP | -Acquisition-Related GAAPand Other Costs (A) | -Other (B) | -Adjustments | -- | - |
| Gross margin ($ in million) $26,794 | -(123) | -(3) | -— | -- | $26,668 | -
| Gross margin % 60.8% | -(0.3) | -— | -— | -- | 60.5% | -
| Operating expense ($ in million) $4,993 | -37 | -— | -— | -- | $5,030 | -
| Operating income ($ in million) $21,801 | -(160) | -(3) | -— | -- | $21,638 | -
| Net income ($ in million) $19,094 | -(160) | -(179) | -20 | -- | $18,775 | -
| Diluted shares (millions) 24,611 | -— | -— | -— | -- | 24,611 | -
| Diluted EPS $0.78 | -(0.01) | -(0.01) | -— | -- | $0.76 | -
| ($ in Millions) | -Q2 FY27 Outlook | -
| Non-GAAP gross margin | -75.0% | -
| Impact of acquisition-related costs and other costs | -(0.1%) | -
| GAAP gross margin | -74.9% | -
| Non-GAAP operating expenses | -$8,300 | -
| Acquisition-related costs and other costs | -200 | -
| GAAP operating expenses | -$8,500 | -
| - | - | Purchases Related to | -Principal Payments on | -- |
| - | - | Property and Equipment | -Property and Equipment | -Net Cash Provided by | -
| ($ in Millions) | -Free Cash Flow | -and Intangible Assets | -and Intangible Assets | -Operating Activities | -
| Q1 FY2027 | -$48,554 | -(1,757) | -(33) | -$50,344 | -
| Q1 FY 2026 | -$26,135 | -(1,227) | -(52) | -$27,414 | -
| - | Q1 FY27 | -YoY % | -Q1 FY26 | -
| Revenue | -$81.6 | -85% | -$44.1 | -
| Gross Margin % | -74.9% | -+14.4 pts | -60.5% | -
| Operating Expenses | -$7.6 | -52% | -$5.0 | -
| Operating Income | -$53.5 | -147% | -$21.6 | -
| Net Income | -$58.3 | -211% | -$18.8 | -
| Diluted EPS | -$2.39 | -214% | -$0.76 | -
| - | - | - | - | Apr 26, 2026 | -- | - | - | - | Jan 25, 2026 | -- | - |
| - | - | Gross | -- | - | - | - | Gross | -- | - | - | - |
| - | - | Carrying | -- | Accumulated | -- | Net Carrying | -Carrying | -- | Accumulated | -- | Net Carrying | -
| - | - | Amount | -- | Amortization | -- | Amount | -Amount | -- | Amortization | -- | Amount | -
| - | - | - | - | - | - | (In millions) | -- | - | - | - | - |
| Acquisition-related intangible assets | -$ | -5,658 | -$ | -(2,759) | -$ | -2,899 | -$ 5,656 | -$ | -(2,580) | -$ | -3,076 | -
| Patents and licensed technology | -- | 525 | -- | (304) | -- | 221 | -528 | -- | (298) | -- | 230 | -
| Total intangible assets | -$ | -6,183 | -$ | -(3,063) | -$ | -3,120 | -$ 6,184 | -$ | -(2,878) | -$ | -3,306 | -
| - | - | Future Amortization Expense | -- |
| - | - | (In millions) | -- |
| Fiscal Year: | -- | - | - |
| 2027 (excluding the first quarter of fiscal year 2027) | -$ | -- | 689.0 | -
| 2028 | -- | - | 754.0 | -
| 2029 | -- | - | 610.0 | -
| 2030 | -- | - | 516.0 | -
| 2031 | -- | - | 468.0 | -
| 2032 and thereafter | -- | - | 83.0 | -
| - | - | - | - | - | - | - | - | Apr 26, 2026 | -- | - | - | - | - | - |
| - | - | - | - | - | - | - | - | - | - | - | Reported as | -- | - | - |
| - | - | - | Cost or | -- | - | - | - | - | - | - | - | Marketable | -- | - |
| - | Pricing | -- | Amortized | -- | Unrealized | -- | Unrealized | -Estimated | -- | Cash | -Marketable | -Equity | -- | Other | -
| - | Category | -- | Cost | -- | Gain | -- | Loss | -Fair Value | -- | Equivalents | -Debt Securities | -Securities | -- | Assets | -
| - | - | - | - | - | - | - | - | (In millions) | -- | - | - | - | - | - |
| Debt securities issued | -- | - | - | - | - | - | - | - | - | - | - | - | - | - |
| by the U.S. Treasury | -Level 2 | -$ | -21,883 | -$ | -43 | -$ | -(8) | -$ 21,918 | -$ | -470 | -$ 21,448 $ | -— | -$ | -— | -
| Corporate debt | -- | - | - | - | - | - | - | - | - | - | - | - | - | - |
| securities | -Level 2 | -- | 15,092 | -- | 48 | -- | (8) | -15,132 | -- | 1,533 | -13,599 | -— | -- | — | -
| Debt securities issued | -- | - | - | - | - | - | - | - | - | - | - | - | - | - |
| by U.S. government | -- | - | - | - | - | - | - | - | - | - | - | - | - | - |
| agencies | -Level 2 | -- | 2,009 | -- | 2 | -- | (1) | -2,010 | -- | — | -2,010 | -— | -- | — | -
| Certificates of deposit | -Level 2 | -- | 132 | -- | — | -- | — | -132 | -- | 132 | -— | -— | -- | — | -
| Foreign government | -- | - | - | - | - | - | - | - | - | - | - | - | - | - |
| bonds | -Level 2 | -- | 40 | -- | 1 | -- | — | -41 | -- | — | -41 | -— | -- | — | -
| Money market funds | -Level 1 | -- | 10,212 | -- | — | -- | — | -10,212 | -- | 10,212 | -— | -— | -- | — | -
| Publicly-held equity | -- | - | - | - | - | - | - | - | - | - | - | - | - | - |
| securities (1) (2) | -Level 1 | -- | - | - | - | - | - | 29,887 | -- | — | -— | -21,023 | -- | 8,864 | -
| Publicly-held equity | -- | - | - | - | - | - | - | - | - | - | - | - | - | - |
| securities (1) (3) | -Level 2 | -- | - | - | - | - | - | 9,214 | -- | — | -— | -9,214 | -- | — | -
| Total | -- | $ | -49,368 | -$ | -94 | -$ | -(17) | -$ 88,546 | -$ | -12,347 | -$ 37,098 $ | -30,237 | -$ | -8,864 | -
| Level 2 | -$ | -21,635 $ | -77 | -$ | -(3) | -$ | -21,709 | -$ | -— | -- | $ 21,709 $ | -— | -$ | -— | -
| Level 2 | -- | 15,410 | -92 | -- | (3) | -- | 15,499 | -- | 345 | -- | 15,154 | -— | -- | — | -
| Level 2 | -- | 2,157 | -4 | -- | — | -- | 2,161 | -- | — | -- | 2,161 | -— | -- | — | -
| Level 2 | -- | 110 | -— | -- | — | -- | 110 | -- | 110 | -- | — | -— | -- | — | -
| Level 2 | -- | 40 | -1 | -- | — | -- | 41 | -- | — | -- | 41 | -— | -- | — | -
| Level 1 | -- | 7,830 | -— | -- | — | -- | 7,830 | -- | 7,830 | -- | — | -— | -- | — | -
| Level 1 | -- | - | - | - | - | - | 17,726 | -- | — | -- | — | -12,886 | -- | 4,840 | -
| - | $ | -47,182 $ | -174 | -$ | -(6) | -$ | -65,076 | -$ | -8,285 | -- | $ 39,065 $ | -12,886 | -$ | -4,840 | -
| uary 25, 2026 included $10.5 billion of investments that are subject to short-term lock-up restrictions on the ability to sell. | -- | - | - | - | - | - | - | - | - | - | - | - | - | - |
| - | Apr 26, 2026 | -Jan 25, 2026 | -
| - | Less than 12 months | -Less than 12 months | -
| - | Estimated Fair Gross Unrealized Estimated Fair | -Gross Unrealized | -
| - | Value Loss | -Value Loss | -
| - | (In millions) | -- |
| Debt securities issued by the U.S. Treasury | -$ 12,238 $ (8) $ | -10,666 $ (3) | -
| Corporate debt securities | -2,658 (8) | -1,332 (3) | -
| Debt securities issued by U.S. government agencies | -1,291 (1) | -1,134 — | -
| Total | -$ 16,187 $ (17) $ | -13,132 $ (6) | -
| - | - | (In millions) | -- |
| Less than one year | -$ | -- | 24,307 | -
| Due in 1 - 5 years | -- | - | 14,926 | -
| Total | -$ | -- | 39,233 | -
| - | - | Three Months Ended | -- |
| - | - | Apr 26, 2026 Apr 27, 2025 | -- |
| - | - | (In millions) | -- |
| Balance at beginning of period | -$ | -22,251 $ | -3,387 | -
| Adjustments related to non-marketable equity securities: | -- | - | - |
| Net additions | -- | 17,899 | -649 | -
| Unrealized gains (1) | -- | 2,603 | -63 | -
| Reclassification (2) | -- | (389) | -(843) | -
| Impairments and unrealized losses | -- | (28) | -(16) | -
| Balance at end of period | -$ | -42,336 $ | -3,240 | -
| - | - | Apr 26, 2026 | -- | Jan 25, 2026 | -
| Inventories: | -- | (In millions) | -- | - |
| Raw materials | -$ | -6,647 | -$ | -3,807 | -
| Work in process | -- | 9,949 | -- | 8,822 | -
| Finished goods | -- | 9,201 | -- | 8,774 | -
| Total inventories (1) | -$ | -25,797 | -$ | -21,403 | -
| - | - | Apr 26, 2026 | -- | Jan 25, 2026 | -- |
| Accrued and Other Current Liabilities: | -- | (In millions) | -- | - | - |
| Taxes payable | -$ | -10,638 | -$ | -- | 2,669 | -
| Customer program accruals | -- | 4,182 | -- | - | 5,318 | -
| Accrued purchase consideration (1) | -- | 3,957 | -- | - | 3,921 | -
| Excess inventory purchase obligations (2) | -- | 3,121 | -- | - | 2,739 | -
| Product warranty | -- | 2,948 | -- | - | 2,807 | -
| Deferred revenue (3) | -- | 1,714 | -- | - | 1,379 | -
| Accrued payroll and related expenses | -- | 1,033 | -- | - | 1,146 | -
| Other | -- | 2,194 | -- | - | 1,373 | -
| - | - | Apr 26, 2026 | -- | Jan 25, 2026 | -- |
| Other Long-Term Liabilities: | -- | - | (In millions) | -- | - |
| Income tax payable (1) | -$ | -- | 4,830 $ | -- | 3,958 | -
| Deferred income tax | -- | - | 1,798 | -- | 1,774 | -
| Deferred revenue (2) | -- | - | 1,403 | -- | 1,193 | -
| Other | -- | - | 737 | -- | 381 | -
| Total other long-term liabilities | -$ | -- | 8,768 $ | -- | 7,306 | -
| The following table shows the changes in short- and long-term deferred revenue during the first quarter of fiscal years 2027 and 2026: | -
| Three Months Ended | -
| Apr 26, 2026 Apr 27, 2025 | -
| (In millions) | -
| Balance at beginning of period $ 2,572 $ 1,813 | -
| Deferred revenue additions (1) 2,530 6,493 | -
| Revenue recognized (2) (1,985) (6,228) | -
| Balance at end of period $ 3,117 $ 2,078 | -
| - | - | Apr 26, 2026 | -- | Jan 25, 2026 | -- |
| - | - | - | (In millions) | -- | - |
| Designated as accounting hedges | -$ | -- | 2,114 $ | -- | 1,765 | -
| - | Expected | -- | - | - | - |
| - | Remaining Term | -Effective | -- | - | - |
| - | (years) | -Interest Rate | -- | Apr 26, 2026 Jan 25, 2026 | -- |
| - | - | - | - | (In millions) | -- |
| 3.20% Notes Due 2026 | -0.4 | -3.31% | -$ | -1,000 $ | -1,000 | -
| 1.55% Notes Due 2028 | -2.1 | -1.64% | -- | 1,250 | -1,250 | -
| 2.85% Notes Due 2030 | -3.9 | -2.93% | -- | 1,500 | -1,500 | -
| 2.00% Notes Due 2031 | -5.1 | -2.09% | -- | 1,250 | -1,250 | -
| 3.50% Notes Due 2040 | -13.9 | -3.54% | -- | 1,000 | -1,000 | -
| 3.50% Notes Due 2050 | -23.9 | -3.54% | -- | 2,000 | -2,000 | -
| 3.70% Notes Due 2060 | -34.0 | -3.73% | -- | 500 | -500 | -
| Unamortized debt discount and issuance costs | -- | - | - | (30) | -(32 | -
| Net carrying amount | -- | - | $ | -8,470 $ | -8,468 | -
| Less short-term portion | -- | - | - | (1,000) | -(999 | -
| - | - | Three Months Ended | -- |
| - | - | Apr 26, 2026 Apr 27, 2025 | -- |
| - | - | (In millions) | -- |
| Balance at beginning of period | -$ | -2,807 $ | -1,290 | -
| Additions | -- | 330 | -870 | -
| Utilization | -- | (189) | -(80 | -
| Balance at end of period | -$ | -2,948 $ | -2,080 | -
| - | - | Compute & | -- | - | - | - | - |
| - | - | Networking | -- | Graphics | -- | Total | -- |
| - | - | - | - | (In millions) | -- | - | - |
| Three Months Ended Apr 26, 2026 | -- | - | - | - | - | - | - |
| Revenue | -$ | -74,550 | -$ | -7,065 | -$ | -- | 81,615 | -
| Other segment items (1) | -- | 21,215 | -- | 4,124 | -- | - | 25,339 | -
| Operating income | -$ | -53,335 | -$ | -2,941 | -$ | -- | 56,276 | -
| Three Months Ended Apr 27, 2025 | -- | - | - | - | - | - | - |
| Revenue | -$ | -39,589 | -$ | -4,473 | -$ | -- | 44,062 | -
| Other segment items (1) | -- | 17,535 | -- | 2,833 | -- | - | 20,368 | -
| Operating income | -$ | -22,054 | -$ | -1,640 | -$ | -- | 23,694 | -
| - | - | Three Months Ended | -
| - | - | Apr 26, 2026 Apr 27, 2025 | -
| - | - | (In millions) | -
| Segment operating income | -$ | -56,276 $ 23,694 | -
| Stock-based compensation expense | -- | (1,928) (1,474) | -
| Unallocated operating expenses | -- | (565) (419) | -
| Acquisition-related and other costs | -- | (247) (163) | -
| Interest income | -- | 540 515 | -
| Interest expense | -- | (102) (63) | -
| Other income (expense), net | -- | 15,929 (180) | -
| Consolidated income before income tax | -$ | -69,903 $ 21,910 | -
| - | - | Three Months Ended | -
| - | - | Apr 26, 2026 Apr 27, 2025 | -
| - | - | (In millions) | -
| Geographic Revenue based upon Customer Headquarters Location: | -- | - |
| United States | -$ | -63,769 $ 25,685 | -
| Taiwan | -- | 12,006 7,648 | -
| China (including Hong Kong) | -- | 4,550 9,659 | -
| Other | -- | 1,290 1,070 | -
| Total revenue | -$ | -81,615 $ 44,062 | -
| Revenue by Market Platform | -- | - |
| Data Center | -$ | -75,246 $ 39,112 | -
| Hyperscale | -- | 37,869 17,599 | -
| AI Clouds, Industrial, & Enterprise | -- | 37,377 21,513 | -
| Edge Computing | -- | 6,369 4,950 | -
| Total revenue | -$ | -81,615 $ 44,062 | -
| - | Operating Lease Obligations | -
| - | (In millions) | -
| Fiscal Year: | -- |
| 2027 (excluding the first quarter of fiscal 2027) | -$ 460 | -
| 2028 | -626 | -
| 2029 | -602 | -
| 2030 | -530 | -
| 2031 | -462 | -
| 2032 and thereafter | -2,924 | -
| Total | -5,604 | -
| Less imputed interest | -1,260 | -
| Present value of net future minimum lease payments | -4,344 | -
| Less short-term operating lease liabilities | -466 | -
| Long-term operating lease liabilities | -$ 3,878 | -
| - | - | Three Months Ended | -- |
| - | - | Apr 26, 2026 Apr 27, 2025 | -- |
| - | - | (In millions) | -- |
| Supplemental cash flows information | -- | - | - |
| Operating cash flow used for operating leases | -$ | -185 $ | -96.0 | -
| Operating lease assets obtained in exchange for lease obligations | -$ | -1,516 $ | -98.0 | -
| First Quarter of Fiscal Year 2027 Summary | -- | - | - | - | - |
| - | - | Three Months Ended | -- | - | - |
| - | - | - | - | Quarter-over-Quarter | -Year-over-Year | -
| - | Apr 26, 2026 | -Jan 25, 2026 Apr 27, 2025 | -- | Change | -Change | -
| - | ($ in millions, except per share data) | -- | - | - | - |
| Revenue $ | -81,615 | -$ 68,127 $ | -44,062 | -20 % | -85 % | -
| Gross margin | -74.9 % | -75.0 % | -60.5 % | -(0.1) pts | -14.4 pts | -
| Operating expenses $ | -7,621 | -$ 6,794 $ | -5,030 | -12 % | -52 % | -
| Operating income $ | -53,536 | -$ 44,299 $ | -21,638 | -21 % | -147 % | -
| Net income $ | -58,321 | -$ 42,960 $ | -18,775 | -36 % | -211 % | -
| Net income per diluted share $ | -2.39 | -$ 1.76 $ | -0.76 | -36 % | -214 % | -
| - | - | - | Three Months Ended | -- | Quarter-over-Quarter | -Year-over-Year | -
| - | - | Apr 26, 2026 | -Jan 25, 2026 | -Apr 27, 2025 | -Change | -Change | -
| - | - | - | ($ in millions) | -- | - | - |
| Revenue by Market Platform (1) | -- | - | - | - | - | - |
| Data Center | -$ | -75,246 | -$ 62,314 $ | -39,112 | -21 % | -92 | -
| Hyperscale | -- | 37,869 | -33,814 | -17,599 | -12 % | -115 | -
| AI Clouds, Industrial, & Enterprise | -- | 37,377 | -28,500 | -21,513 | -31 % | -74 | -
| Edge Computing | -- | 6,369 | -5,813 | -4,950 | -10 % | -29 | -
| Total revenue | -$ | -81,615 | -$ 68,127 $ | -44,062 | -20 % | -85 | -
| - | Three Months Ended | -
| - | Apr 26, 2026 Apr 27, 2025 | -
| Revenue | -100.0 % 100.0 % | -
| Cost of revenue | -25.1 39.5 | -
| Gross profit | -74.9 60.5 | -
| Operating expenses | -- |
| Research and development | -7.7 9.1 | -
| Sales, general and administrative | -1.6 2.4 | -
| Total operating expenses | -9.3 11.5 | -
| Operating income | -65.6 49.0 | -
| Interest income | -0.7 1.2 | -
| Interest expense | -(0.1) (0.1) | -
| Other income (expense), net | -19.5 (0.4) | -
| Total other income, net | -20.1 0.7 | -
| Income before income tax | -85.7 49.7 | -
| Income tax expense | -14.2 7.1 | -
| Net income | -71.5 % 42.6 % | -
| - | - | - | - | Three Months Ended | -- | - | - |
| - | - | Apr 26, 2026 | -- | Apr 27, 2025 Change $ | -%Change | -- | - |
| - | - | - | - | ($ in millions) | -- | - | - |
| Compute & Networking | -$ | -74,550 | -$ | -39,589 $ 34,961 | -- | - | 88 % | -
| Graphics | -- | 7,065 | -- | 4,473 2,592 | -- | - | 58 % | -
| Total | -$ | -81,615 | -$ | -44,062 $ 37,553 | -- | - | 85 % | -
| - | - | - | - | Three Months Ended | -- | - | - |
| - | - | Apr 26, 2026 | -- | Apr 27, 2025 Change $ | -%Change | -- | - |
| - | - | - | - | ($ in millions) | -- | - | - |
| Compute & Networking | -$ | -53,335 | -$ | -22,054 $ 31,281 | -- | - | 142 % | -
| Graphics | -- | 2,941 | -- | 1,640 1,301 | -- | - | 79 % | -
| Total | -$ | -56,276 | -$ | -23,694 $ 32,582 | -- | - | 138 % | -
| Research and development | -$ | -6,321 | -$ | -3,989 $ 2,332 | -- | - | 58 % | -
| Sales, general and administrative | -- | 1,300 | -- | 1,041 259 | -- | - | 25 % | -
| Total operating expenses | -$ | -7,621 | -$ | -5,030 $ 2,591 | -- | - | 52 % | -
| - | - | - | Three Months Ended | -- | - | - |
| - | - | Apr 26, 2026 | -Apr 27, 2025 | -- | $Change | -- |
| - | - | - | ($ in millions) | -- | - | - |
| Interest income | -$ | -540 | -$ 515 | -$ | -- | 25 | -
| Interest expense | -- | (102) | -(63) | -- | - | (39) | -
| Other income (expense), net | -- | 15,929 | -(180) | -- | - | 16,109 | -
| Total other income, net | -$ | -16,367 | -$ 272 | -$ | -- | 16,095 | -
| - | - | Apr 26, 2026 | -- | Jan 25, 2026 | -
| - | - | (In millions) | -- | - |
| Cash and cash equivalents | -$ | -13,237 | -$ | -10,605 | -
| Marketable debt securities | -- | 37,098 | -- | 39,065 | -
| Cash, cash equivalents, and marketable debt securities | -$ | -50,335 | -$ | -49,670 | -
| - | - | Apr 26, 2026 | -- | Apr 27, 2025 | -
| - | - | (In millions) | -- | - |
| Net cash provided by operating activities | -$ | -50,344 | -$ | -27,414 | -
| Net cash used in investing activities | -$ | -(26,429) | -$ | -(5,216) | -
| Net cash used in financing activities | -$ | -(21,283) | -$ | -(15,553) | -
| - | - | Apr 26, 2026 | -- |
| - | - | (In millions) | -- |
| Due in one year | -$ | -- | 1,000 | -
| Due in one to five years | -- | - | 2,750 | -
| Due in five to ten years | -- | - | 1,250 | -
| Due in greater than ten years | -- | - | 3,500 | -
| Unamortized debt discount and issuance costs | -- | - | (30) | -
| Net carrying amount | -$ | -- | 8,470 | -
| Less short-term portion | -- | - | (1,000) | -
| - | - | - | Total Number of Shares | -Approximate Dollar Value | -
| - | Total Number | -- | Purchased as Part of | -of Shares that May Yet B | -
| - | of Shares | -- | Publicly Announced | -Purchased Under the | -
| - | Purchased | -Average Price Paid | -Program | -Program | -
| Period | -(In millions) | -per Share (1) | -(In millions) | -(In billions) | -
| January 26, 2026 - February 22, 2026 | -8.2 | -$ 186.35 | -8.2 | -$ 57.0 | -
| February 23, 2026 - March 22, 2026 | -9.0 | -$ 183.38 | -9.0 | -$ 55.4 | -
| March 23, 2026 - April 26, 2026 | -91.1 | -$ 184.98 | -91.1 | -$ 38.5 | -
| Total | -108.3 | -- | 108.3 | -- |
| Name | -Title of Director or | -Action | -Date | -Total Shares of | -Expiration Date | -
| - | Officer | -- | - | Common Stock to be | -- |
| - | - | - | - | Sold | -- |
| Tench Coxe | -Director | -Adoption | -3/19/2026 | -8,000,000* | -10/30/2027 | -
| Colette M. Kress | -Executive Vice President | -Termination | -4/10/2026 | -500,000** | -N/A | -
| - | and Chief Financial | -- | - | - | - |
| - | Officer | -- | - | - | - |
| - | NVIDIA Corporation and Subsidiaries | -- | - |
| - | Condensed Consolidated Statements of Income | -- | - |
| - | (In millions, except per share data) | -- | - |
| - | (Unaudited) | -- | - |
| - | Three Months Ended | -- | - |
| - | Apr 26, 2026 | -Apr 27, 2025 | -- |
| Revenue | -$ | -81,615 $ | -44,062 | -
| Cost of revenue | -- | 20,458 | -17,394 | -
| Gross profit | -- | 61,157 | -26,668 | -
| Operating expenses | -- | - | - |
| Research and development | -- | 6,321 | -3,989 | -
| Sales, general and administrative | -- | 1,300 | -1,041 | -
| Total operating expenses | -- | 7,621 | -5,030 | -
| Operating income | -- | 53,536 | -21,638 | -
| Interest income | -- | 540 | -515 | -
| Interest expense | -- | (102) | -(63) | -
| Other income (expense), net | -- | 15,929 | -(180) | -
| Total other income, net | -- | 16,367 | -272 | -
| Income before income tax | -- | 69,903 | -21,910 | -
| Income tax expense | -- | 11,582 | -3,135 | -
| Net income | -$ | -58,321 $ | -18,775 | -
| Net income per share: | -- | - | - |
| Basic | -$ | -2.40 $ | -0.77 | -
| Diluted | -$ | -2.39 $ | -0.76 | -
| Weighted average shares used in per share computation: | -- | - | - |
| Basic | -- | 24,286 | -24,441 | -
| Diluted | -- | 24,391 | -24,611 | -
| - | - | Incorporated by Reference | -- |
| Exhibit No. | -Exhibit Description | -Schedule/Form Exhibit | -Filing Date | -
| 10.1+ | -Variable Compensation Plan - Fiscal Year 2027 | -8-K 10.1 | -3/6/2026 | -
| 31.1* | -Certification of Chief Executive Officer as required by Rule 13a-14(a) of the Securities | -- | - |
| - | Exchange Act of 1934 | -- | - |
| 31.2* | -Certification of Chief Financial Officer as required by Rule 13a-14(a) of the Securities | -- | - |
| - | Exchange Act of 1934 | -- | - |
| 32.1#* | -Certification of Chief Executive Officer as required by Rule 13a-14(b) of the Securities | -- | - |
| - | Exchange Act of 1934 | -- | - |
| 32.2#* | -Certification of Chief Financial Officer as required by Rule 13a-14(b) of the Securities | -- | - |
| - | Exchange Act of 1934 | -- | - |
| 101.INS* | -Inline XBRL Instance Document - the instance document does not appear in the InteractiveData File because its XBRL tags are embedded within the Inline XBRL document. | -- | - |
| 101.SCH* | -Inline XBRL Taxonomy Extension Schema Document | -- | - |
| 101.CAL* | -Inline XBRL Taxonomy Extension Calculation Linkbase Document | -- | - |
| 101.DEF* | -Inline XBRL Taxonomy Extension Definition Linkbase Document | -- | - |
| 101.LAB* | -Inline XBRL Taxonomy Extension Labels Linkbase Document | -- | - |
| 101.PRE* | -Inline XBRL Taxonomy Extension Presentation Linkbase Document | -- | - |
| - | Cover Page Interactive Data File - the cover page interactive data file does not appear in | -- | - |
| - | - | Three Months Ended | -- |
| - | - | Apr 26, 2026 Apr 27, 2025 | -- |
| - | - | - | - |
| Net income | -$ | -58,321 $ | -18,775 | -
| Other comprehensive income (loss), net of tax | -- | - | - |
| Available-for-sale securities: | -- | - | - |
| Net change in unrealized gain (loss) | -- | (78) | -139 | -
| Cash flow hedges: | -- | - | - |
| Net change in unrealized gain | -- | 37 | -19 | -
| Other comprehensive income (loss), net of tax | -- | (41) | -158 | -
| - | - | Apr 26, 2026 | -- | - | Jan 25, 2026 | -
| Assets | -- | - | - | - | - |
| Current assets: | -- | - | - | - | - |
| Cash and cash equivalents | -$ | -13,237 | -- | $ | -10,605 | -
| Marketable debt securities | -- | 37,098 | -- | - | 39,065 | -
| Marketable equity securities | -- | 30,237 | -- | - | 12,886 | -
| Accounts receivable, net | -- | 40,710 | -- | - | 38,466 | -
| Inventories | -- | 25,797 | -- | - | 21,403 | -
| Prepaid expenses and other current assets | -- | 3,916 | -- | - | 3,180 | -
| Total current assets | -- | 150,995 | -- | - | 125,605 | -
| Property and equipment, net | -- | 12,403 | -- | - | 10,383 | -
| Operating lease assets | -- | 4,258 | -- | - | 2,867 | -
| Goodwill | -- | 20,894 | -- | - | 20,832 | -
| Intangible assets, net | -- | 3,120 | -- | - | 3,306 | -
| Deferred income tax assets | -- | 11,707 | -- | - | 13,258 | -
| Non-marketable securities | -- | 43,364 | -- | - | 22,251 | -
| Other assets | -- | 12,733 | -- | - | 8,301 | -
| Total assets | -$ | -259,474 | -- | $ | -206,803 | -
| Liabilities and Shareholders’ Equity | -- | - | - | - | - |
| Current liabilities: | -- | - | - | - | - |
| Accounts payable | -$ | -13,097 | -- | $ | -9,812 | -
| Accrued and other current liabilities | -- | 29,787 | -- | - | 21,352 | -
| Short-term debt | -- | 1,000 | -- | - | 999 | -
| Total current liabilities | -- | 43,884 | -- | - | 32,163 | -
| Long-term debt | -- | 7,470 | -- | - | 7,469 | -
| Long-term operating lease liabilities | -- | 3,878 | -- | - | 2,572 | -
| Other long-term liabilities | -- | 8,768 | -- | - | 7,306 | -
| Total liabilities | -- | 64,000 | -- | - | 49,510 | -
| Commitments and contingencies | -- | - | - | - | - |
| Shareholders’ equity: | -- | - | - | - | - |
| Preferred stock | -- | — | -- | - | — | -
| Common stock | -- | 24 | -- | - | 24 | -
| Additional paid-in capital | -- | 10,275 | -- | - | 10,118 | -
| Accumulated other comprehensive income | -- | 137 | -- | - | 178 | -
| Retained earnings | -- | 185,038 | -- | - | 146,973 | -
| Total shareholders’ equity | -- | 195,474 | -- | - | 157,293 | -
| Total liabilities and shareholders’ equity | -$ | -259,474 | -- | $ | -206,803 | -
| - | Common Stock | -- | - | - | - | - | - | - | - |
| - | Outstanding | -Additional | -- | Accumulated Other Comprehensive | -- | - | Retained | -- | TotalShareholders’ | -
| - | Shares Amount | -Paid-in Capital | -- | Income | -- | - | Earnings | -- | Equity | -
| (In millions, except per share data) | -- | - | - | - | - | - | - | - | - |
| Balances as of Jan 25, 2026 | -24,304 $ 24 | -$ 10,118 | -$ | -178 | -- | $ | -146,973 | -$ | -157,293 | -
| Net income | -— — | -— | -- | - | — | -- | 58,321 | -- | 58,321 | -
| Other comprehensive loss | -— — | -— | -- | (41) | -- | - | — | -- | (41) | -
| Issuance of common stock | -37 — | -515 | -- | - | — | -- | — | -- | 515 | -
| Tax withholding related to common stock | -(12) — | -(2,129) | -- | - | — | -- | — | -- | (2,129) | -
| Shares repurchased | -(108) — | -(157) | -- | - | — | -- | (20,013) | -- | (20,170) | -
| Cash dividends declared and paid ($0.01 per common share) | -— — | -— | -- | - | — | -- | (243) | -- | (243) | -
| Stock-based compensation | -— — | -1,928 | -- | - | — | -- | — | -- | 1,928 | -
| Balances as of Apr 26, 2026 | -24,221 $ 24 | -$ 10,275 | -$ | -137 | -- | $ | -185,038 | -$ | -195,474 | -
| Balances as of Jan 26, 2025 | -24,477 $ 24 | -$ 11,237 | -$ | -28 | -- | $ | -68,038 | -$ | -79,327 | -
| Net income | -— — | -— | -- | - | — | -- | 18,775 | -- | 18,775 | -
| Other comprehensive income | -— — | -— | -- | 158 | -- | - | — | -- | 158 | -
| Issuance of common stock | -50 — | -370 | -- | - | — | -- | — | -- | 370 | -
| Tax withholding related to common stock | -(13) — | -(1,532) | -- | - | — | -- | — | -- | (1,532) | -
| Shares repurchased | -(126) — | -(92) | -- | - | — | -- | (14,411) | -- | (14,503) | -
| Cash dividends declared and paid ($0.01 per common share) | -— — | -— | -- | - | — | -- | (244) | -- | (244) | -
| Fair value of partially vested equity awards assumed in connection with | -- | - | - | - | - | - | - | - | - |
| acquisitions | -— — | -22 | -- | - | — | -- | — | -- | 22 | -
| Stock-based compensation | -— — | -1,470 | -- | - | — | -- | — | -- | 1,470 | -
| - | - | Three Months Ended | -
| - | - | Apr 26, 2026 Apr 27, 2025 | -
| Cash flows from operating activities: | -- | - |
| Net income | -$ | -58,321 $ 18,775 | -
| Adjustments to reconcile net income to net cash provided by operating activities: | -- | - |
| Stock-based compensation expense | -- | 1,928 1,474 | -
| Deferred income taxes | -- | 1,584 (2,177) | -
| Depreciation and amortization | -- | 997 611 | -
| (Gains) losses from equity securities, net | -- | (15,936) 175 | -
| Other | -- | (94) (98) | -
| Changes in operating assets and liabilities, net of acquisitions: | -- | - |
| Accounts receivable | -- | (2,243) 933 | -
| Inventories | -- | (4,420) (1,258) | -
| Prepaid expenses and other assets | -- | (983) 560 | -
| Accounts payable | -- | 2,210 941 | -
| Accrued and other current liabilities | -- | 7,763 7,128 | -
| Other long-term liabilities | -- | 1,217 350 | -
| Net cash provided by operating activities | -- | 50,344 27,414 | -
| Cash flows from investing activities: | -- | - |
| Proceeds from maturities of marketable debt securities | -- | 1,946 3,122 | -
| Proceeds from sales of non-marketable securities | -- | 26 — | -
| Proceeds from sales of marketable debt securities | -- | 25 467 | -
| Purchases of non-marketable securities | -- | (18,582) (649) | -
| Purchases of marketable debt and equity securities | -- | (8,000) (6,546) | -
| Purchases related to property and equipment and intangible assets | -- | (1,757) (1,227) | -
| Acquisitions, net of cash acquired | -- | (87) (383) | -
| Net cash used in investing activities | -- | (26,429) (5,216) | -
| Cash flows from financing activities: | -- | - |
| Proceeds related to employee stock plans | -- | 515 370 | -
| Payments related to repurchases of common stock | -- | (19,312) (14,095) | -
| Payments related to employee stock plan taxes | -- | (2,129) (1,532) | -
| Dividends paid | -- | (243) (244) | -
| Principal payments on property and equipment and intangible assets | -- | (33) (52) | -
| Other | -- | (81) — | -
| Net cash used in financing activities | -- | (21,283) (15,553) | -
| Change in cash and cash equivalents | -- | 2,632 6,645 | -
| Cash and cash equivalents at beginning of period | -- | 10,605 8,589 | -
| Cash and cash equivalents at end of period | -$ | -13,237 $ 15,234 | -
| - | - | Three Months Ended | -- |
| - | - | Apr 26, 2026 Apr 27, 2025 | -- |
| - | - | (In millions) | -- |
| Cost of revenue | -$ | -68 $ | -64 | -
| Research and development | -- | 1,459 | -1,063 | -
| Sales, general and administrative | -- | 401 | -347 | -
| Total | -$ | -1,928 $ | -1,474 | -
| - | RSUs, PSUs and Market-based PSUs Outstanding | -
| - | Weighted Average Grant-Date Fair | -
| - | Number of Shares Value Per Share | -
| - | (In millions, except per share data) | -
| Balance as of Jan 25, 2026 | -189 $ 81.51 | -
| Granted | -44 $ 181.73 | -
| Vested | -(31) $ 48.04 | -
| Canceled and forfeited | -(2) $ 95.82 | -
| Balance as of Apr 26, 2026 | -200 $ 108.92 | -
| - | - | Three Months Ended | -- |
| - | - | Apr 26, 2026 Apr 27, 2025 | -- |
| - | - | (In millions, except per share data) | -- |
| Numerator: | -- | - | - |
| Net income | -$ | -58,321 $ | -18,775 | -
| Denominator: | -- | - | - |
| Basic weighted average shares | -- | 24,286 | -24,441 | -
| Dilutive impact of outstanding equity awards | -- | 105 | -170 | -
| Diluted weighted average shares | -- | 24,391 | -24,611 | -
| Net income per share: | -- | - | - |
| Basic (1) | -$ | -2.40 $ | -0.77 | -
| Diluted (2) | -$ | -2.39 $ | -0.76 | -
| Anti-dilutive equity awards excluded from diluted net income per share | -- | 47 | -62 | -
| Table 4: The Transformer generalizes well to English constituency parsing (Results are on S | -
| of WSJ) | -
| Parser Training WSJ 23 F1 | -
| Vinyals & Kaiser el al. (2014) [37] WSJ only, discriminative 88.3 | -
| Petrov et al. (2006) [29] WSJ only, discriminative 90.4 | -
| Zhu et al. (2013) [40] WSJ only, discriminative 90.4 | -
| Dyer et al. (2016) [8] WSJ only, discriminative 91.7 | -
| Transformer (4 layers) WSJ only, discriminative 91.3 | -
| Zhu et al. (2013) [40] semi-supervised 91.3 | -
| Huang & Harper (2009) [14] semi-supervised 91.3 | -
| McClosky et al. (2006) [26] semi-supervised 92.1 | -
| Vinyals & Kaiser el al. (2014) [37] semi-supervised 92.1 | -
| Transformer (4 layers) semi-supervised 92.7 | -
| Luong et al. (2015) [23] multi-task 93.0 | -
| Dyer et al. (2016) [8] generative 93.3 | -
| - | - | - | - | - | - | - | - | - | train | -PPL | -BLEU | -params | -
| - | N | -dmodel dff | -h | -dk | -dv | -Pdrop | -εls | -- | - | - | - | - |
| - | - | - | - | - | - | - | - | - | steps | -(dev) | -(dev) | -×106 | -
| base | -6 | -512 2048 | -8 | -64 | -64 | -0.1 | -0.1 | -- | 100K | -4.92 | -25.8 | -65 | -
| - | - | - | 1 | -512 | -512 | -- | - | - | - | 5.29 | -24.9 | -- |
| - | - | - | 4 | -128 | -128 | -- | - | - | - | 5.00 | -25.5 | -- |
| (A) | -- | - | - | - | - | - | - | - | - | - | - | - |
| - | - | - | 16 | -32 | -32 | -- | - | - | - | 4.91 | -25.8 | -- |
| - | - | - | 32 | -16 | -16 | -- | - | - | - | 5.01 | -25.4 | -- |
| - | - | - | - | 16 | -- | - | - | - | - | 5.16 | -25.1 | -58 | -
| (B) | -- | - | - | - | - | - | - | - | - | - | - | - |
| - | - | - | - | 32 | -- | - | - | - | - | 5.01 | -25.4 | -60 | -
| - | 2 | -- | - | - | - | - | - | - | - | 6.11 | -23.7 | -36 | -
| - | 4 | -- | - | - | - | - | - | - | - | 5.19 | -25.3 | -50 | -
| - | 8 | -- | - | - | - | - | - | - | - | 4.88 | -25.5 | -80 | -
| (C) | -- | 256 | -- | 32 | -32 | -- | - | - | - | 5.75 | -24.5 | -28 | -
| - | - | 1024 | -- | 128 | -128 | -- | - | - | - | 4.66 | -26.0 | -168 | -
| - | - | 1024 | -- | - | - | - | - | - | - | 5.12 | -25.4 | -53 | -
| - | - | 4096 | -- | - | - | - | - | - | - | 4.75 | -26.2 | -90 | -
| - | - | - | - | - | - | 0.0 | -- | - | - | 5.77 | -24.6 | -- |
| - | - | - | - | - | - | 0.2 | -- | - | - | 4.95 | -25.5 | -- |
| (D) | -- | - | - | - | - | - | - | - | - | - | - | - |
| - | - | - | - | - | - | - | 0.0 | -- | - | 4.67 | -25.3 | -- |
| - | - | - | - | - | - | - | 0.2 | -- | - | 5.47 | -25.7 | -- |
| (E) | -- | positional embedding instead of sinusoids | -- | - | - | - | - | - | - | 4.92 | -25.7 | -- |
| big | -6 | -1024 4096 | -16 | -- | - | 0.3 | -- | - | 300K | -4.33 | -26.4 | -213 | -
| Langchain LlamaIndex | -Haystack | -Haystack | -
| (v0.01.13) (v0.10) | -(v1.25) | -(v2.0) | -
| Unstructured Data Formats: Plain Text (HTML, MARKDOWN, TXT), Image (JPEG, PNG), Document (CSV, PDF) | -- | - |
| Chunking Strategies: Fixed-size Chunking | -- | - |
| Embedding Models: OpenAI, Hugging Face, Cohere, AWS Models | -- | - |
| Vector Databases: Elasticsearch, FAISS, Milvus, OpenSearch, Pinecone, Qdrant, Weaviate | -- | - |
| Unstructured Data Formats: JSON, Pre- Unstructured Data Formats: JSON EPUB, HWP, IPYNB, DOCX, PPT, | -Unstructured Data Formats: TIFF, | -Unstructured Data Formats: TIFF, | -
| retrieval PPTX | -BMP, JSON, DOCX | -BMP, DOCX, PPTX, XLSX | -
| Stage Chunking Strategies: Header-based Chunking, Semantic Chunking | -- | - |
| Chunking Strategies: Recursive Chunking Strategies: Hierachical | -- | - |
| Chunking Chunking | -- | - |
| Embedding Models: AI21, Aleph Alpha, Baidu, Google, Azure, Cohere, | -Embedding Models: Anthropic, | -Embedding Models: Azure, | -
| Fastembed, Gradient, Jina, Mistral, Voyage... | -vLLM | -Fastembed, Gradient, Jina, Mistral, Ollama... | -
| Vector Databases: AstraDB, Chroma, Marqo, Neo4j, Pgvector, Azure, | -- | Vector Databases: AstraDB, Chroma, | -
| Baudu, Apache Cassandra, MyScale... | -- | Marqo, Neo4j, Pgvector | -
| Dense Retrieval: Top-k Listing, Similarity Threshold Listing | -- | - |
| Sparse Retrieval: Keyword-based Listing | -- | - |
| Emsemble Retrieval: Hybrid Search, Multi-embedding Search | -- | - |
| Metadata Filtering | -- | - |
| Retrieval Time-weighted Search | -- | - |
| Stage Self-querying/Auto-retrieval | -- | - |
| Multi-querying | -- | - |
| Contextual Compression | -- | - |
| Parent Document | -- | - |
| Recursive Retrieval | -- | - |
| Auto-merging | -- | - |
| Cross-encoder Reranker: Hugging Face Sentence Transformer | -- | - |
| Cross-encoder Reranker: Cohere Rerank | -- | - |
| Long-context Reordering (Reordering most similar documents to context beginning/end to avoid Lost-in-the-Middle issue) | -- | - |
| Post- Cross-encoder Reranker: Flashrank | -- | - |
| retrieval Cross-encoder Reranker: ColBert | -- | - |
| Rerank | -- | - |
| Stage | -- | - |
| Cross-encoder Reranker: Jina | -- | Cross-encoder Reranker: Jina | -
| Rerank | -- | Ranker | -
| Cross-encoder Reranker: LLM | -- | - |
| Rerank | -- | - |
| - | Diversity Ranker | -MetaFieldRanker | -
| Generators: OpenAI, Cohere, AWS, Hugging Face Models | -- | - |
| Prompt Templates (query, retrieved documents, instructions, examples, tone, style, output format) | -- | - |
| Output Parsing (e.g., structured output, syntactically valid output, semantic validation) | -- | - |
| Generator: Anthropic | -- | - |
| Generator: Google | -- | Generator: Google | -
| Generator: Ollama | -- | Generator: Ollama | -
| Generator: Azure | -- | Generator: Azure | -
| Generator: Mistral | -- | Generator: Mistral | -
| Generator: AlephAlpha | -- | - |
| Guardrail: Guardrails.ai | -- | - |
| Guardrail: NVIDIA NeMo | -- | - |
| - | - | ada-002 | -- |
| According to | -18% | -According to the | -The study does not | -
| the study, what | -- | study, 18% of the AI | -provide information | -
| percentage of | -- | systems examined | -on the percentage of | -
| the AI systems | -- | were in the high-risk | -AI systems examined | -
| examined were in | -- | class. | -that were in the high- | -
| the high-risk class? | -- | - | risk class. | -
| What are the three | -The three risk classes | -Prohibited AI | -I'm sorry, but the | -
| risk classes outlined | -outlined in the AI | -systems, High-risk | -context provided | -
| in the AI Regulation, | -Regulation are high-risk, | -AI systems, and | -does not mention | -
| and what are the | -low-risk, and unclear. The | -Low-risk AI systems. | -the three risk classes | -
| main requirements | -main requirements for | -- | outlined in the AI | -
| for each? | -each are not specified in | -- | Regulation or their | -
| - | the provided context. | -- | main requirements. | -
| - | Context | -Context | -Context | -- | - | - | - |
| - | Precision | -Recall | -Relevance | -Faithfulness | -Answer Correctness | -- | Answer Relevance | -
| text-embedding- | -- | - | - | - | - | - | - |
| ada-002 | -0.85 | -0.58 | -0.10 | -0.67 | -0.53 | -- | 0.89 | -
| - | - | T-REx | -- | - | WebQS | -- |
| k | -All | -AC NC | -% | -All | -AC NC | -% | -
| 0 | -34.9 | -– 34.9 | -0.0 | -18.9 | -– 18.9 | -0.0 | -
| 1 | -47.8 | -53.0 44.3 | -40.3 | -19.3 | -17.1 19.9 | -8.5 | -
| 3 | -52.9 | -58.0 29.0 | -82.8 | -26.3 | -26.5 6.6 | -99.3 | -
| 10 | -53.5 | -54.0 22.5 | -98.1 | -26.3 | -26.4 – | -100.0 | -
| mple 7: A total of 500 married couples are poled about salaries: | -
| Wife Husband makes less than 25,000 Husband makes more than 25,000 | -
| Less than $25,000 212 198 | -
| More than $25,000 36 54 | -
| outcome | -1 | -2 | -3 | -
| 1 | -(X = 1, Y = 2) = (1, 2) | -(2, 3) | -(3, 4) | -
| 2 | -(2, 3) | -(2, 4) | -(3, 5) | -
| 3 | -(3, 4) | -(3, 5) | -(3, 6) | -
| X\Y | -2 | -- | 3.0 | -4.0 | -5.0 | -6.0 | -
| 1 | -P (X = 1, Y = 2) = | -1.0 | -0.0 | -0.0 | -0.0 | -0.0 | -
| - | - | 9.0 | -- | - | - | - |
| 2 | -0 | -- | 2.0 | -1.0 | -0.0 | -0.0 | -
| - | - | - | 9.0 | -9.0 | -- | - |
| 3 | -0 | -- | 0.0 | -2.0 | -2.0 | -1.0 | -
| - | - | - | - | 9.0 | -9.0 | -9.0 | -
| x\y | -0.0 | -1.0 | -
| 0 | -0.4 | -0.2 | -
| 1 | -0.1 | -0.3 | -
| X | -- | Y | -0.0 | -2 | -
| - | 0.0 | -- | 0.2 | -.7 . | -
| - | 1.0 | -- | 0.0 | -.1 | -
| State | -Metro | -Status | -
| California | -SF Bay Area | -Safety Driver | -
| Texas | -Austin | -Ramping Unsupervised | -
| - | Dallas | -1H 2026 | -
| - | Houston | -1H 2026 | -
| Arizona | -Phoenix | -1H 2026 | -
| Florida | -Miami | -1H 2026 | -
| - | Orlando | -1H 2026 | -
| - | Tampa | -1H 2026 | -
| Nevada | -Las Vegas | -1H 2026 | -
| In millions of USD or shares as applicable, except per share data | -- | Q4-2024 | -- | Q1-2025 | -- | Q2-2025 | -- | Q3-2025 | -- | Q4-2025 | -
| REVENUES | -- | - | - | - | - | - | - | - | - | - |
| Automotive sales | -- | 18,659 | -- | 12,925 | -- | 15,787 | -- | 20,359 | -- | 16,750 | -
| Automotive regulatory credits | -- | 692 | -- | 595 | -- | 439 | -- | 417 | -- | 542 | -
| Automotive leasing | -- | 447 | -- | 447 | -- | 435 | -- | 429 | -- | 401 | -
| Total automotive revenues | -- | 19,798 | -- | 13,967 | -- | 16,661 | -- | 21,205 | -- | 17,693 | -
| Energy generation and storage | -- | 3,061 | -- | 2,730 | -- | 2,789 | -- | 3,415 | -- | 3,837 | -
| Services and other | -- | 2,848 | -- | 2,638 | -- | 3,046 | -- | 3,475 | -- | 3,371 | -
| Total revenues | -- | 25,707 | -- | 19,335 | -- | 22,496 | -- | 28,095 | -- | 24,901 | -
| COST OF REVENUES | -- | - | - | - | - | - | - | - | - | - |
| Automotive sales | -- | 16,268 | -- | 11,461 | -- | 13,567 | -- | 17,365 | -- | 13,874 | -
| Automotive leasing | -- | 242 | -- | 239 | -- | 228 | -- | 225 | -- | 206 | -
| Total automotive cost of revenues | -- | 16,510 | -- | 11,700 | -- | 13,795 | -- | 17,590 | -- | 14,080 | -
| Energy generation and storage | -- | 2,289 | -- | 1,945 | -- | 1,943 | -- | 2,342 | -- | 2,739 | -
| Services and other | -- | 2,729 | -- | 2,537 | -- | 2,880 | -- | 3,109 | -- | 3,073 | -
| Total cost of revenues | -- | 21,528 | -- | 16,182 | -- | 18,618 | -- | 23,041 | -- | 19,892 | -
| Gross profit | -- | 4,179 | -- | 3,153 | -- | 3,878 | -- | 5,054 | -- | 5,009 | -
| OPERATING EXPENSES | -- | - | - | - | - | - | - | - | - | - |
| Research and development | -- | 1,276 | -- | 1,409 | -- | 1,589 | -- | 1,630 | -- | 1,783 | -
| Selling, general and administrative | -- | 1,313 | -- | 1,251 | -- | 1,366 | -- | 1,562 | -- | 1,655 | -
| Restructuring and other | -- | 7 | -- | 94 | -- | — | -- | 238 | -- | 162 | -
| Total operating expenses | -- | 2,596 | -- | 2,754 | -- | 2,955 | -- | 3,430 | -- | 3,600 | -
| INCOME FROM OPERATIONS | -- | 1,583 | -- | 399 | -- | 923 | -- | 1,624 | -- | 1,409 | -
| Interest income | -- | 442 | -- | 400 | -- | 392 | -- | 439 | -- | 449 | -
| Interest expense | -- | (96) | -- | (91) | -- | (86) | -- | (76) | -- | (85) | -
| Other income (expense), net (1) | -- | 595 | -- | (119) | -- | 320 | -- | (28) | -- | (592) | -
| INCOME BEFORE INCOME TAXES (1) | -- | 2,524 | -- | 589 | -- | 1,549 | -- | 1,959 | -- | 1,181 | -
| Provision for income taxes (1) | -- | 381 | -- | 169 | -- | 359 | -- | 570 | -- | 325 | -
| NET INCOME (1) | -- | 2,143 | -- | 420 | -- | 1,190 | -- | 1,389 | -- | 856 | -
| Net income attributable to noncontrolling interests and redeemable noncontrolling interests in subsidiaries | -- | 15 | -- | 11 | -- | 18 | -- | 16 | -- | 16 | -
| NET INCOME ATTRIBUTABLE TO COMMON STOCKHOLDERS (1) | -- | 2,128 | -- | 409 | -- | 1,172 | -- | 1,373 | -- | 840 | -
| Less: Buy-out of noncontrolling interest | -- | 3 | -- | — | -- | — | -- | — | -- | — | -
| NET INCOME USED IN COMPUTING NET INCOME PER SHARE OF COMMON STOCK (1) | -- | 2,125 | -- | 409 | -- | 1,172 | -- | 1,373 | -- | 840 | -
| Net income per share of common stock attributable to common stockholders | -- | - | - | - | - | - | - | - | - | - |
| Basic (1) | -$ | -0.66 | -$ | -0.13 | -$ | -0.36 | -$ | -0.43 | -$ | -0.26 | -
| Diluted (1) | -$ | -0.60 | -$ | -0.12 | -$ | -0.33 | -$ | -0.39 | -$ | -0.24 | -
| Weighted average shares used in computing net income per share of common stock | -- | - | - | - | - | - | - | - | - | - |
| Basic | -- | 3,213 | -- | 3,218 | -- | 3,223 | -- | 3,227 | -- | 3,231 | -
| Diluted | -- | 3,517 | -- | 3,521 | -- | 3,519 | -- | 3,526 | -- | 3,539 | -
| In millions of USD | -31-Dec-24 | -31-Mar-25 | -30-Jun-25 | -30-Sep-25 | -31-Dec-25 | -
| ASSETS | -- | - | - | - | - |
| Current assets | -- | - | - | - | - |
| Cash, cash equivalents and investments | -36,563 | -36,996 | -36,782 | -41,647 | -44,059 | -
| Accounts receivable, net | -4,418 | -3,782 | -3,838 | -4,703 | -4,576 | -
| Inventory | -12,017 | -13,706 | -14,570 | -12,276 | -12,392 | -
| Prepaid expenses and other current assets | -5,362 | -4,905 | -5,943 | -6,027 | -7,615 | -
| Total current assets | -58,360 | -59,389 | -61,133 | -64,653 | -68,642 | -
| Operating lease vehicles, net | -5,581 | -5,477 | -5,230 | -5,019 | -4,912 | -
| Energy generation and storage systems, net | -4,924 | -4,855 | -4,788 | -4,673 | -4,604 | -
| Property, plant and equipment, net | -35,836 | -37,088 | -38,574 | -39,407 | -40,643 | -
| Operating lease right-of-use assets | -5,160 | -5,330 | -5,633 | -5,783 | -6,027 | -
| Digital assets (2) | -1,076 | -951 | -1,235 | -1,315 | -1,008 | -
| Deferred tax assets (2) | -6,524 | -6,687 | -6,721 | -6,637 | -6,925 | -
| Other non-current assets | -4,609 | -5,334 | -5,253 | -6,248 | -5,045 | -
| Total assets (2) | -122,070 | -125,111 | -128,567 | -133,735 | -137,806 | -
| LIABILITIES AND EQUITY | -- | - | - | - | - |
| Current liabilities | -- | - | - | - | - |
| Accounts payable | -12,474 | -13,471 | -13,212 | -12,819 | -13,371 | -
| Accrued liabilities and other | -10,723 | -10,802 | -11,519 | -12,791 | -13,279 | -
| Deferred revenue | -3,168 | -3,243 | -3,237 | -3,756 | -3,424 | -
| Current portion of debt and finance leases (1) | -2,456 | -2,237 | -2,040 | -1,924 | -1,640 | -
| Total current liabilities | -28,821 | -29,753 | -30,008 | -31,290 | -31,714 | -
| Debt and finance leases, net of current portion (1) | -5,757 | -5,292 | -5,180 | -5,778 | -6,736 | -
| Deferred revenue, net of current portion | -3,317 | -3,610 | -3,764 | -3,746 | -3,631 | -
| Other long-term liabilities | -10,495 | -11,038 | -11,543 | -12,205 | -12,860 | -
| Total liabilities | -48,390 | -49,693 | -50,495 | -53,019 | -54,941 | -
| Redeemable noncontrolling interests in subsidiaries | -63 | -62 | -61 | -59 | -58 | -
| Total stockholders' equity (2) | -72,913 | -74,653 | -77,314 | -79,970 | -82,137 | -
| Noncontrolling interests in subsidiaries | -704 | -703 | -697 | -687 | -670 | -
| Total liabilities and equity (2) | -122,070 | -125,111 | -128,567 | -133,735 | -137,806 | -
| (1) Breakdown of our debt is as follows: | -- | - | - | - | - |
| Non-recourse debt | -7,871 | -7,238 | -6,953 | -7,458 | -8,150 | -
| Recourse debt | -7 | -6 | -3 | -3 | -3 | -
| Days sales outstanding | -14 | -19 | -15 | -14 | -17 | -
| Days payable outstanding | -58 | -72 | -65 | -52 | -61 | -
| Highlights | -3 | -
| Financial Summary | -4 | -
| Operational Summary | -6 | -
| Manufacturing & Hardware | -8 | -
| Supporting Infrastructure | -9 | -
| AI & Software | -10 | -
| Services | -11 | -
| Other Updates | -12 | -
| Outlook | -13 | -
| Photos & Charts | -14 | -
| Key Metrics | -24 | -
| Financial Statements | -27 | -
| Additional Information | -34 | -
| In millions of USD | -Q4-2024 | -Q1-2025 | -Q2-2025 | -Q3-2025 | -Q4-2025 | -
| CASH FLOWS FROM OPERATING ACTIVITIES | -- | - | - | - | - |
| Net income (1) | -2,143 | -420 | -1,190 | -1,389 | -856 | -
| Adjustments to reconcile net income to net cash provided by operating activities: | -- | - | - | - | - |
| Depreciation, amortization and impairment | -1,496 | -1,447 | -1,433 | -1,625 | -1,643 | -
| Stock-based compensation | -579 | -573 | -635 | -663 | -954 | -
| Deferred income taxes (1) | -6 | -(43) | -52 | -225 | -(111) | -
| Digital assets (gain) loss, net (1) | -(347) | -125 | -(284) | -(80) | -307 | -
| Other | -(93) | -188 | -187 | -333 | -378 | -
| Changes in operating assets and liabilities | -1030 | -(554) | -(673) | -2,083 | -(214) | -
| Net cash provided by operating activities | -4,814 | -2,156 | -2,540 | -6,238 | -3,813 | -
| CASH FLOWS FROM INVESTING ACTIVITIES | -- | - | - | - | - |
| Capital expenditures (2) | -(2,780) | -(1,492) | -(2,394) | -(2,248) | -(2,393) | -
| Purchases of investments | -(15,158) | -(6,015) | -(7,485) | -(11,402) | -(12,207) | -
| Proceeds from maturities of investments | -10,335 | -5,856 | -6,935 | -9,295 | -8,072 | -
| Net cash used in investing activities | -(7,603) | -(1,651) | -(2,944) | -(4,355) | -(6,528) | -
| CASH FLOWS FROM FINANCING ACTIVITIES | -- | - | - | - | - |
| Net cash flows from other debt activities | -(108) | -(50) | -(23) | -410 | -963 | -
| Net borrowings (repayments) under vehicle and energy product financing | -677 | -(674) | -(400) | -81 | -(377) | -
| Net cash flows from noncontrolling interests – Solar | -(37) | -(22) | -(14) | -(20) | -(22) | -
| Other | -453 | -414 | -215 | -512 | -146 | -
| Net cash provided by (used in) financing activities | -985 | -(332) | -(222) | -983 | -710 | -
| Effect of exchange rate changes on cash and cash equivalents and restricted cash | -(133) | -40 | -111 | -(17) | -37 | -
| Net (decrease) increase in cash and cash equivalents and restricted cash | -(1,937) | -213 | -(515) | -2,849 | -(1,968) | -
| Cash and cash equivalents and restricted cash at beginning of period | -18,974 | -17,037 | -17,250 | -16,735 | -19,584 | -
| Cash and cash equivalents and restricted cash at end of period | -17,037 | -17,250 | -16,735 | -19,584 | -17,616 | -
| In millions of USD or shares as applicable, except per share data | -Q4-2024 | -Q1-2025 | -Q2-2025 | -Q3-2025 | -Q4-2025 | -
| Net income attributable to common stockholders (GAAP) (1) | -2,128 | -409 | -1,172 | -1,373 | -840 | -
| Stock-based compensation expense, net of tax | -249 | -428 | -443 | -459 | -682 | -
| Digital assets (gain) loss, net of tax (1) | -(270) | -97 | -(222) | -(62) | -239 | -
| Net income attributable to common stockholders (non-GAAP) (1) (2) | -2,107 | -934 | -1,393 | -1,770 | -1,761 | -
| Less: Buy-outs of noncontrolling interests | -3 | -— | -— | -— | -— | -
| Net income used in computing diluted EPS attributable to common stockholders (non-GAAP) (1) (2) | -2,104 | -934 | -1,393 | -1,770 | -1,761 | -
| EPS attributable to common stockholders, diluted (GAAP) (1) | -0.60 | -0.12 | -0.33 | -0.39 | -0.24 | -
| Stock-based compensation expense, net of tax, per share | -0.08 | -0.12 | -0.13 | -0.13 | -0.19 | -
| Digital assets (gain) loss, net of tax, per share (1) | -(0.08) | -0.03 | -(0.06) | -(0.02) | -0.07 | -
| EPS attributable to common stockholders, diluted (non-GAAP) (1) (2) | -0.60 | -0.27 | -0.40 | -0.50 | -0.50 | -
| Shares used in EPS calculation, diluted (GAAP and non-GAAP) | -3,517 | -3,521 | -3,519 | -3,526 | -3,539 | -
| Net income attributable to common stockholders (GAAP) (1) | -2,128 | -409 | -1,172 | -1,373 | -840 | -
| Interest expense | -96 | -91 | -86 | -76 | -85 | -
| Provision for income taxes (1) | -381 | -169 | -359 | -570 | -325 | -
| Depreciation, amortization and impairment | -1,496 | -1,447 | -1,433 | -1,625 | -1,643 | -
| Stock-based compensation expense | -579 | -573 | -635 | -663 | -954 | -
| Digital assets (gain) loss, net (1) | -(347) | -125 | -(284) | -(80) | -307 | -
| Adjusted EBITDA (non-GAAP) (1) (3) | -4,333 | -2,814 | -3,401 | -4,227 | -4,154 | -
| Total revenues | -25,707 | -19,335 | -22,496 | -28,095 | -24,901 | -
| Adjusted EBITDA margin (non-GAAP) (1) (3) | -16.9% | -14.6% | -15.1% | -15.0% | -16.7% | -
| Automotive gross margin (GAAP) | -16.6% | -16.2% | -17.2% | -17.0% | -20.4% | -
| Less: Total regulatory credit revenue recognized | -3.0% | -3.7% | -2.2% | -1.6% | -2.5% | -
| Automotive gross margin excluding regulatory credit sales (non-GAAP) | -13.6% | -12.5% | -15.0% | -15.4% | -17.9% | -
| In millions of USD or shares as applicable, except per share data | -2021 | -2022 | -2023 | -2024 | -2025 | -
| Net income attributable to common stockholders (GAAP) | -5,519 | -12,556 | -14,997 | -7,091 | -3,794 | -
| Stock-based compensation expense, net of tax | -2,121 | -1,560 | -1,812 | -1,328 | -2,012 | -
| Digital assets loss (gain), net of tax | -79 | -160 | -— | -(459) | -52 | -
| Release of valuation allowance on deferred tax assets | -— | -— | -(5,927) | -— | -— | -
| Net income attributable to common stockholders (non-GAAP) (1) | -7,719 | -14,276 | -10,882 | -7,960 | -5,858 | -
| Less: Buy-outs of noncontrolling interests | -(5) | -(27) | -(2) | -(39) | -— | -
| Less: Dilutive convertible debt | -(9) | -(1) | -— | -— | -— | -
| Net income used in computing diluted EPS attributable to common stockholders (non-GAAP) (1) | -7,733 | -14,304 | -10,884 | -7,999 | -5,858 | -
| EPS attributable to common stockholders, diluted (GAAP) | -1.63 | -3.62 | -4.30 | -2.04 | -1.08 | -
| Stock-based compensation expense, net of tax, per share | -0.63 | -0.45 | -0.52 | -0.38 | -0.57 | -
| Digital assets loss (gain), net of tax, per share | -0.02 | -0.05 | -— | -(0.13) | -0.01 | -
| Release of valuation allowance on deferred tax assets | -— | -— | -(1.70) | -— | -— | -
| EPS attributable to common stockholders, diluted (non-GAAP) (1) | -2.28 | -4.12 | -3.12 | -2.29 | -1.66 | -
| Shares used in EPS calculation, diluted (GAAP and non-GAAP) | -3,386 | -3,475 | -3,485 | -3,498 | -3,528 | -
| Net income attributable to common stockholders (GAAP) | -5,519 | -12,556 | -14,997 | -7,091 | -3,794 | -
| Interest expense | -371 | -191 | -156 | -350 | -338 | -
| Provision for (benefit from) income taxes | -699 | -1132 | -(5,001) | -1,837 | -1,423 | -
| Depreciation, amortization and impairment | -2,911 | -3,747 | -4,667 | -5,368 | -6,148 | -
| Stock-based compensation expense | -2,121 | -1,560 | -1,812 | -1,999 | -2,825 | -
| Digital assets loss (gain), net | -101 | -204 | -— | -(589) | -68 | -
| Adjusted EBITDA (non-GAAP) (2) | -11,722 | -19,390 | -16,631 | -16,056 | -14,596 | -
| Total revenues | -53,823 | -81,462 | -96,773 | -97,690 | -94,827 | -
| Adjusted EBITDA margin (non-GAAP) (2) | -21.8% | -23.8% | -17.2% | -16.4% | -15.4% | -
| Automotive gross margin (GAAP) | -29.3% | -28.5% | -19.4% | -18.4% | -17.8% | -
| Less: Total regulatory credit revenue recognized | -2.3% | -1.8% | -1.7% | -3.0% | -2.4% | -
| Automotive gross margin excluding regulatory credit sales (non-GAAP) | -27.0% | -26.7% | -17.7% | -15.4% | -15.4% | -
| In millions of USD | -2Q-2022 | -3Q-2022 | -4Q-2022 | -1Q-2023 | -2Q-2023 | -3Q-2023 | -4Q-2023 | -1Q-2024 | -2Q-2024 | -3Q-2024 | -4Q-2024 | -1Q-2025 | -2Q-2025 | -3Q-2025 | -4Q-2025 | -
| Net cash provided by operating activities (GAAP) | -2,351 | -5,100 | -3,278 | -2,513 | -3,065 | -3,308 | -4,370 | -242 | -3,612 | -6,255 | -4,814 | -2,156 | -2,540 | -6,238 | -3,813 | -
| Capital expenditures (1) | -(1,730) | -(1,803) | -(1,858) | -(2,073) | -(2,060) | -(2,459) | -(2,307) | -(2,777) | -(2,272) | -(3,513) | -(2,780) | -(1,492) | -(2,394) | -(2,248) | -(2,393) | -
| Free cash flow (non-GAAP) (1) | -621 | -3,297 | -1,420 | -440 | -1,005 | -849 | -2,063 | -(2,535) | -1,340 | -2,742 | -2,034 | -664 | -146 | -3,990 | -1,420 | -
| In millions of USD | -2Q-2022 | -3Q-2022 | -4Q-2022 | -1Q-2023 | -2Q-2023 | -3Q-2023 | -4Q-2023 | -1Q-2024 | -2Q-2024 | -3Q-2024 | -4Q-2024 | -1Q-2025 | -2Q-2025 | -3Q-2025 | -4Q-2025 | -
| Net income attributable to common stockholders (GAAP) (2) | -2,259 | -3,292 | -3,687 | -2,513 | -2,703 | -1,853 | -7,928 | -1,390 | -1,400 | -2,173 | -2,128 | -409 | -1,172 | -1,373 | -840 | -
| Interest expense | -44 | -53 | -33 | -29 | -28 | -38 | -61 | -76 | -86 | -92 | -96 | -91 | -86 | -76 | -85 | -
| Provision for (benefit from) income taxes (2) | -205 | -305 | -276 | -261 | -323 | -167 | -(5,752) | -483 | -371 | -602 | -381 | -169 | -359 | -570 | -325 | -
| Depreciation, amortization and impairment | -922 | -956 | -989 | -1,046 | -1,154 | -1,235 | -1,232 | -1,246 | -1,278 | -1,348 | -1,496 | -1,447 | -1,433 | -1,625 | -1,643 | -
| Stock-based compensation expense | -361 | -362 | -419 | -418 | -445 | -465 | -484 | -524 | -439 | -457 | -579 | -573 | -635 | -663 | -954 | -
| Digital assets loss (gain), net (2) | -170 | -— | -34 | -— | -— | -— | -— | -(335) | -100 | -(7) | -(347) | -125 | -(284) | -(80) | -307 | -
| Adjusted EBITDA (non-GAAP) (2) (3) | -3,961 | -4,968 | -5,438 | -4,267 | -4,653 | -3,758 | -3,953 | -3,384 | -3,674 | -4,665 | -4,333 | -2,814 | -3,401 | -4,227 | -4,154 | -
| In millions of USD | -1Q-2023 | -2Q-2023 | -3Q-2023 | -4Q-2023 | -1Q-2024 | -2Q-2024 | -3Q-2024 | -4Q-2024 | -1Q-2025 | -2Q-2025 | -3Q-2025 | -4Q-2025 | -
| Net cash provided by operating activities – TTM (GAAP) | -13,242 | -13,956 | -12,164 | -13,256 | -10,985 | -11,532 | -14,479 | -14,923 | -16,837 | -15,765 | -15,748 | -14,747 | -
| Capital expenditures – TTM (1) | -(7,464) | -(7,794) | -(8,450) | -(8,899) | -(9,603) | -(9,815) | -(10,869) | -(11,342) | -(10,057) | -(10,179) | -(8,914) | -(8,527) | -
| Free cash flow – TTM (non-GAAP) (1) | -5,778 | -6,162 | -3,714 | -4,357 | -1,382 | -1,717 | -3,610 | -3,581 | -6,780 | -5,586 | -6,834 | -6,220 | -
| In millions of USD | -1Q-2023 | -2Q-2023 | -3Q-2023 | -4Q-2023 | -1Q-2024 | -2Q-2024 | -3Q-2024 | -4Q-2024 | -1Q-2025 | -2Q-2025 | -3Q-2025 | -4Q-2025 | -
| Net income attributable to common stockholders – TTM (GAAP) (2) | -11,751 | -12,195 | -10,756 | -14,997 | -13,874 | -12,571 | -12,891 | -7,091 | -6,110 | -5,882 | -5,082 | -3,794 | -
| Interest expense – TTM | -159 | -143 | -128 | -156 | -203 | -261 | -315 | -350 | -365 | -365 | -349 | -338 | -
| Provision for (benefit from) income taxes – TTM (2) | -1,047 | -1,165 | -1,027 | -(5,001) | -(4,779) | -(4,731) | -(4,296) | -1,837 | -1,523 | -1,511 | -1,479 | -1,423 | -
| Depreciation, amortization and impairment – TTM | -3,913 | -4,145 | -4,424 | -4,667 | -4,867 | -4,991 | -5,104 | -5,368 | -5,569 | -5,724 | -6,001 | -6,148 | -
| Stock-based compensation expense – TTM | -1,560 | -1,644 | -1,747 | -1,812 | -1,918 | -1,912 | -1,904 | -1,999 | -2,048 | -2,244 | -2,450 | -2,825 | -
| Digital assets loss (gain), net – TTM (2) | -204 | -34 | -34 | -— | -(335) | -(235) | -(242) | -(589) | -(129) | -(513) | -(586) | -68 | -
| Adjusted EBITDA – TTM (non-GAAP) (2) (3) | -18,634 | -19,326 | -18,116 | -16,631 | -15,748 | -14,769 | -15,676 | -16,056 | -15,486 | -15,213 | -14,775 | -14,596 | -
| ($ in millions, except percentages and per share data) | -Q4-2024 | -Q1-2025 | -Q2-2025 | -Q3-2025 | -Q4-2025 | -YoY | -
| Total automotive revenues | -19,798 | -13,967 | -16,661 | -21,205 | -17,693 | --11% | -
| Energy generation and storage revenue | -3,061 | -2,730 | -2,789 | -3,415 | -3,837 | -25% | -
| Services and other revenue | -2,848 | -2,638 | -3,046 | -3,475 | -3,371 | -18% | -
| Total revenues | -25,707 | -19,335 | -22,496 | -28,095 | -24,901 | --3% | -
| Total gross profit | -4,179 | -3,153 | -3,878 | -5,054 | -5,009 | -20% | -
| Total GAAP gross margin | -16.3% | -16.3% | -17.2% | -18.0% | -20.1% | -386 bp | -
| Operating expenses | -2,596 | -2,754 | -2,955 | -3,430 | -3,600 | -39% | -
| Income from operations | -1,583 | -399 | -923 | -1,624 | -1,409 | --11% | -
| Operating margin | -6.2% | -2.1% | -4.1% | -5.8% | -5.7% | --50 bp | -
| Adjusted EBITDA (1) (2) | -4,333 | -2,814 | -3,401 | -4,227 | -4,154 | --4% | -
| Adjusted EBITDA margin (1) (2) | -16.9% | -14.6% | -15.1% | -15.0% | -16.7% | --17 bp | -
| Net income attributable to common stockholders (GAAP) (1) | -2,128 | -409 | -1,172 | -1,373 | -840 | --61% | -
| Net income attributable to common stockholders (non-GAAP) (1) (3) | -2,107 | -934 | -1,393 | -1,770 | -1,761 | --16% | -
| EPS attributable to common stockholders, diluted (GAAP) (1) | -0.60 | -0.12 | -0.33 | -0.39 | -0.24 | --60% | -
| EPS attributable to common stockholders, diluted (non-GAAP) (1) (3) | -0.60 | -0.27 | -0.40 | -0.50 | -0.50 | --17% | -
| Net cash provided by operating activities | -4,814 | -2,156 | -2,540 | -6,238 | -3,813 | --21% | -
| Capital expenditures (4) | -(2,780) | -(1,492) | -(2,394) | -(2,248) | -(2,393) | --14% | -
| Free cash flow (4) | -2,034 | -664 | -146 | -3,990 | -1,420 | --30% | -
| Cash, cash equivalents and investments | -36,563 | -36,996 | -36,782 | -41,647 | -44,059 | -21% | -
| ($ in millions, except percentages and per share data) | -2021 | -2022 | -2023 | -2024 | -2025 | -YoY | -
| Total automotive revenues | -47,232 | -71,462 | -82,419 | -77,070 | -69,526 | --10% | -
| Energy generation and storage revenue | -2,789 | -3,909 | -6,035 | -10,086 | -12,771 | -27% | -
| Services and other revenue | -3,802 | -6,091 | -8,319 | -10,534 | -12,530 | -19% | -
| Total revenues | -53,823 | -81,462 | -96,773 | -97,690 | -94,827 | --3% | -
| Total gross profit | -13,606 | -20,853 | -17,660 | -17,450 | -17,094 | --2% | -
| Total GAAP gross margin | -25.3% | -25.6% | -18.2% | -17.9% | -18.0% | -16 bp | -
| Operating expenses | -7,083 | -7,197 | -8,769 | -10,374 | -12,739 | -23% | -
| Income from operations | -6,523 | -13,656 | -8,891 | -7,076 | -4,355 | --38% | -
| Operating margin | -12.1% | -16.8% | -9.2% | -7.2% | -4.6% | --265 bp | -
| Adjusted EBITDA (1) | -11,722 | -19,390 | -16,631 | -16,056 | -14,596 | --9% | -
| Adjusted EBITDA margin (1) | -21.8% | -23.8% | -17.2% | -16.4% | -15.4% | --104 bp | -
| Net income attributable to common stockholders (GAAP) | -5,519 | -12,556 | -14,997 | -7,091 | -3,794 | --46% | -
| Net income attributable to common stockholders (non-GAAP) (2) | -7,719 | -14,276 | -10,882 | -7,960 | -5,858 | --26% | -
| EPS attributable to common stockholders, diluted (GAAP) | -1.63 | -3.62 | -4.30 | -2.04 | -1.08 | --47% | -
| EPS attributable to common stockholders, diluted (non-GAAP) (2) | -2.28 | -4.12 | -3.12 | -2.29 | -1.66 | --28% | -
| Net cash provided by operating activities | -11,497 | -14,724 | -13,256 | -14,923 | -14,747 | --1% | -
| Capital expenditures (3) | -(6,514) | -(7,163) | -(8,899) | -(11,342) | -(8,527) | --25% | -
| Free cash flow (3) | -4,983 | -7,561 | -4,357 | -3,581 | -6,220 | -74% | -
| Cash, cash equivalents and investments | -17,707 | -22,185 | -29,094 | -36,563 | -44,059 | -21% | -
| - | Q4-2024 | -Q1-2025 | -Q2-2025 | -Q3-2025 | -Q4-2025 | -YoY | -- |
| Model 3/Y production | -436,718 | -345,454 | -396,835 | -435,826 | -422,652 | -- | -3% | -
| Other models production | -22,727 | -17,161 | -13,409 | -11,624 | -11,706 | -- | -48% | -
| Total production | -459,445 | -362,615 | -410,244 | -447,450 | -434,358 | -- | -5% | -
| Model 3/Y deliveries | -471,930 | -323,800 | -373,728 | -481,166 | -406,585 | -- | -14% | -
| Other models deliveries | -23,640 | -12,881 | -10,394 | -15,933 | -11,642 | -- | -51% | -
| Total deliveries | -495,570 | -336,681 | -384,122 | -497,099 | -418,227 | -- | -16% | -
| of which subject to operating lease accounting | -26,962 | -13,721 | -6,670 | -10,230 | -10,996 | -- | -59% | -
| Cumulative deliveries(1) (all-time; mil) | -7.3 | -7.6 | -8.0 | -8.5 | -8.9 | -- | 22% | -
| Active FSD Subscriptions(2) (mil) | -0.8 | -0.8 | -0.9 | -1.0 | -1.1 | -- | 38% | -
| Total end of quarter operating lease (new vehicle) count(3) | -180,523 | -179,930 | -172,882 | -167,163 | -163,075 | -- | -10% | -
| Global vehicle inventory (days of supply)(4) | -12 | -22 | -24 | -10 | -15 | -- | 25% | -
| Storage deployed (GWh) | -11.0 | -10.4 | -9.6 | -12.5 | -14.2 | -- | 29% | -
| Tesla locations | -1,359 | -1,390 | -1,454 | -1,498 | -1,553 | -- | 14% | -
| Supercharger stations | -6,975 | -7,131 | -7,377 | -7,753 | -8,182 | -- | 17% | -
| Supercharger connectors | -65,495 | -67,316 | -70,228 | -73,817 | -77,682 | -- | 19% | -
| - | 2021 | -2022 | -2023 | -2024 | -2025 | -YoY | -- |
| Model 3/Y production | -906,032 | -1,298,434 | -1,775,159 | -1,679,338 | -1,600,767 | -- | -5% | -
| Other models production | -24,390 | -71,177 | -70,826 | -94,105 | -53,900 | -- | -43% | -
| Total production | -930,422 | -1,369,611 | -1,845,985 | -1,773,443 | -1,654,667 | -- | -7% | -
| Model 3/Y deliveries | -911,242 | -1,247,146 | -1,739,707 | -1,704,093 | -1,585,279 | -- | -7% | -
| Other models deliveries | -24,980 | -66,705 | -68,874 | -85,133 | -50,850 | -- | -40% | -
| Total deliveries | -936,222 | -1,313,851 | -1,808,581 | -1,789,226 | -1,636,129 | -- | -9% | -
| of which subject to operating lease accounting | -60,912 | -47,582 | -72,226 | -60,003 | -41,617 | -- | -31% | -
| Cumulative deliveries(1) (all-time; mil) | -2.3 | -3.7 | -5.5 | -7.3 | -8.9 | -- | 22% | -
| Active FSD Subscriptions(2) (mil) | -0.4 | -0.5 | -0.6 | -0.8 | -1.1 | -- | 38% | -
| Total end of year operating lease (new vehicle) count | -120,342 | -140,667 | -176,564 | -180,523 | -163,075 | -- | -10% | -
| Global vehicle inventory (days of supply)(3) | -6 | -16 | -16 | -13 | -15 | -- | 15% | -
| Storage deployed (GWh) | -4.0 | -6.5 | -14.7 | -31.4 | -46.7 | -- | 49% | -
| Tesla locations | -644 | -963 | -1,208 | -1,359 | -1,553 | -- | 14% | -
| Supercharger stations | -3,476 | -4,678 | -5,952 | -6,975 | -8,182 | -- | 17% | -
| Supercharger connectors | -31,498 | -42,419 | -54,892 | -65,495 | -77,682 | -- | 19% | -
| - | - | Installed Annual Manufacturing Capacity | -- |
| Region | -Product | -Capacity | -Status | -
| - | - | Automotive | -- |
| California | -Model 3 / Model Y | ->550,000 | -Production | -
| - | Model S / Model X | -100,000 | -Production | -
| Shanghai | -Model 3 / Model Y | ->950,000 | -Production | -
| Berlin | -Model Y | ->375,000 | -Production | -
| Texas | -Model Y | ->250,000 | -Production | -
| - | Cybertruck | ->125,000 | -Production | -
| - | Cybercab | -- | -Tooling | -
| Nevada | -Tesla Semi | -- | -Tooling | -
| TBD | -Roadster | -- | -Design development | -
| - | - | Energy Generation and Storage | -- |
| California | -Megapack | -40 GWh | -Production | -
| Nevada | -Powerwall | ->6 GWh | -Production | -
| Shanghai | -Megapack | -40 GWh | -Production | -
| Texas | -Megapack | -- | -Construction | -
| - | - | Robotics | -- |
| California | -Optimus | -- | -Construction | -
| Texas | -Cortex 1 | ->100k H100e | -Production | -
| - | Cortex 2 | -- | -Construction | -
| - | - | Battery Manufacturing | -- |
| Nevada | -LFP | -7 GWh | -Early Ramp | -
| Texas | -4680 | -40 GWh | -Production | -
| - | Cathode Materials | -10 GWh | -Early Ramp | -
| - | Lithium Refining | -30 GWh | -Early Ramp | -
| metric |
| metric |
| metric |
| metric |
| metric |
Full evidence_text ({len(evidence_text)} chars)
\n\n') + md.append(f'Full evidence preview ({len(evidence_text)} chars)
\n\n') md.append(_fence(evidence_text)) md.append('\n| Metric | Value |
| Flow |
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/shared-demo-rollout.md b/docs/shared-demo-rollout.md
index 6985ddca9..97a6cbfa8 100644
--- a/docs/shared-demo-rollout.md
+++ b/docs/shared-demo-rollout.md
@@ -37,6 +37,48 @@ archive. API job deletion requests for these revisions return 409. This checkout
has no general job deletion/cancellation API; ordinary jobs remain retained
processing records, and DELETE remains unsupported for them.
+## Public revision structure
+
+`GET /api/v1/demo/sources/{demo_source_id}/structure` returns the complete
+published section outline without loading chunk bodies or result archives.
+It requires no authentication and follows the same active-source and complete
+revision checks as the other public demo reads.
+
+Pass `job_result_id` to pin the outline to the same revision as subsequent chunk
+and asset requests. Omitting it selects the current complete revision. Responses
+use `Cache-Control: no-store`.
+
+```json
+{
+ "demo_source_id": "example-source",
+ "canonical_document_id": "ddoc_example",
+ "job_result_id": "published-revision-id",
+ "sections": [
+ {
+ "section_id": "sec_parent",
+ "parent_section_id": null,
+ "section_path": "Operations",
+ "section_title": "Operations",
+ "section_level": 1,
+ "sort_order": 0
+ }
+ ]
+}
+```
+
+Sections follow persisted `sort_order`, with `section_id` as a deterministic tie
+breaker. Build the tree from `parent_section_id`; do not infer parentage from
+title splitting or alphabetically reorder siblings. Structural parents are
+included even when they own no chunk. This is the published section tree;
+TOC-only entries never persisted during parsing/publication are not restored by
+this read endpoint. Unknown sources or unavailable pinned revisions return 404;
+known sources without a complete revision retain the existing preparing error.
+
+The HTTP/PostgreSQL shared-demo contract suite passes all ten tests, including
+revision-pinned structure reads, structural parents, persisted sibling order,
+preparing/error behavior, and guards against chunk or artifact downloads.
+Ruff and Pyright pass for the changed API modules.
+
## Backup gate
Use the authoritative originals in `knowhere-storage-staging`, not public URLs.
diff --git a/docs/source-content-deduplication-review.md b/docs/source-content-deduplication-review.md
new file mode 100644
index 000000000..9aff23b4b
--- /dev/null
+++ b/docs/source-content-deduplication-review.md
@@ -0,0 +1,58 @@
+# Source content deduplication review and ablations
+
+Reviewed on 2026-10-10 against `5264697481567b76abf8abcf463573018847701c`, including the uncommitted implementation and new files. The specification is the agreed conversation: compare original bytes within one user and namespace, reject unchanged updates, use current active revisions and in-progress reservations, and perform no historical backfill.
+
+## Standards
+
+The review found one concrete migration defect: a valid, ready index with the expected name but incorrect columns or predicate was retained. Two real PostgreSQL contracts reproduced the defect under ordinary and caller-owned transactions. The migration now validates the table, nonunique B-tree definition, column order and expression, predicate, validity, and readiness before retaining an index. Twelve cases pass, including retention of the correct index without rebuilding it and replacement of indexes whose JSON keys differ in case or contain a cast-like suffix. Definition comparison preserves JSON string literals rather than normalizing their case or stripping cast-like text from them.
+
+No remaining blocker was found. Optional improvements include a direct interrupted-index recovery contract, concurrent index removal during ordinary downgrade, and a precise fingerprint return type. Canonical index-definition formatting is verified on the local PostgreSQL version; a future formatting change could cause an unnecessary rebuild.
+
+## Spec
+
+No blocking behavior mismatch was found. Publication and the terminal job transition commit together, accepted fingerprints survive ordinary metadata updates, and completed task redelivery exits before admission.
+
+The review identified a lost export contract. It is restored for two same-named XLSX files differing only in ZIP comments: both succeed, retain full document and ZIP chunks, and produce identical parsed chunk identifiers. The duplicate worker contract now enables billing and verifies that the duplicate leaves account balance unchanged, has no result, and creates an `ALREADY_EXISTS` webhook outbox event and dispatch request. The dispatch is captured locally; external webhook delivery is not exercised.
+
+Exact byte equality remains the agreed boundary. Re-exported files with changed container metadata can pass even when their visible content is identical. An unchanged source is also rejected when only parsing options change. Existing unhashed sources remain outside admission.
+
+## Component ablations
+
+Every variant ran the same 14 admission contracts against an isolated real PostgreSQL fixture and local source files. Mutations were test-scoped patches in separate processes; production code was not replaced with ablated implementations. All runs below had zero setup errors. Failures in the altered variants are intentional evidence that the contracts detect the removed behavior.
+
+| Variant | Passed | Failed | Observed failure |
+| --- | ---: | ---: | --- |
+| Unchanged implementation | 14 | 0 | Agreed behavior holds |
+| Use file size instead of hashing bytes | 12 | 2 | Different bytes of equal length are falsely rejected |
+| Omit fingerprint persistence | 5 | 9 | Later duplicates are accepted and durable fingerprints are unavailable |
+| Remove advisory transaction lock | 13 | 1 | Both concurrent claims are admitted |
+| Check published documents only | 12 | 2 | Unpublished reservations and the publication transition are missed |
+| Split the union into two separate reads | 13 | 1 | Publication between the snapshots allows a duplicate |
+
+The concurrency contract pauses the first transaction after its empty lookup and starts the second claim before releasing it. With the lock present, PostgreSQL reports the second transaction waiting for its advisory lock. Without the lock, the second claim can finish against the empty state. The publication contract commits publication after the first lookup executes, exposing the gap in separate statement snapshots.
+
+## Index ablation and skew experiment
+
+The experiment used the actual ORM union query and the ordinary runtime database role, with planner defaults enabled. The first dataset contained 5,000 active current document revisions with distinct hashes and one incoming job. The last dataset additionally contained 2,000 running jobs with the requested hash in other namespaces. Every query correctly returned no duplicate in the incoming namespace.
+
+| Local workload | SQL execution time | Shared buffer hits | Query-plan evidence |
+| --- | ---: | ---: | --- |
+| Hash index, absent hash | 0.093 ms | 6 | Published branch uses user/hash index; no revision joins execute |
+| Same dataset, hash index removed | 37.883 ms | 30,210 | Visits 5,000 documents and performs 5,000 result/job lookups |
+| Hash index, same hash in 2,000 other namespaces | 6.948 ms | 4,177 | Published branch probes 2,000 candidate results; processing branch filters 2,001 jobs |
+
+These are single local `EXPLAIN (ANALYZE, BUFFERS)` probes with zero shared disk reads, not production latency measurements or a five-million-document benchmark. SQL execution time excludes download, hashing, pool acquisition, network round trips, and lock waits. Buffer counts and visited rows provide the stronger evidence.
+
+The index is necessary, but matching hash multiplicity still matters because namespace and lifecycle state are later filters. The earlier 5–20 ms planning estimate assumes few matching user/hash rows and is not a worst-case guarantee. We keep the current design for this change; a workload dominated by repeated content across namespaces would justify revisiting index scope and the published-candidate query. Terminal and archived history were not measured by this skew experiment.
+
+## Reproduction and validation
+
+Local experiment artifacts are in `/tmp/knowhere-source-content-ablation/`: `source_content_ablation.py`, `run_matrix.py`, per-variant logs and JUnit reports, `results.json`, `test_query_plan_experiment.py`, and the complete `query-plans.json`.
+
+The matrix can be repeated with `python3 /tmp/knowhere-source-content-ablation/run_matrix.py`; it uses the existing uv environment, applies one mutation per process, and runs the admission contract file. Local PostgreSQL sockets must be permitted. The index experiment loads `contract.conftest` as a pytest plugin, executes its temporary experiment file, and drops/recreates the hash index only in the isolated fixture database.
+
+The strengthened worker suite passes all 33 contracts, and the API and migration suite passes all 61 contracts. The final expanded index migration check passes all 12 cases; this check overlaps the broader migration suite and is not an additional 12 distinct contracts. Ruff, Pyright (production paths, changed API contracts, and the new migration), and `git diff --check` pass. URL transport and real external webhook delivery remain outside these local contracts.
+
+Before PR publication, the change was rebased onto `main` at `65c0445a` and revalidated: all 33 worker contracts and all 65 API/migration contracts pass, including the expanded migration cases. Ruff, Pyright, and the diff whitespace check also pass on that base.
+
+Standards: one confirmed defect, fixed; optional operational and typing suggestions remain. Spec: no blocking mismatch; export, billing, webhook, and concurrency coverage strengthened.
diff --git a/docs/spacex-hierarchy-fix.md b/docs/spacex-hierarchy-fix.md
index 62eca2ad0..3ba737dbe 100644
--- a/docs/spacex-hierarchy-fix.md
+++ b/docs/spacex-hierarchy-fix.md
@@ -50,3 +50,86 @@ reproduced the loop before this change and finishes in four turns afterward.
Both real reader launch-comparison queries finished with precise page ranges.
See [the validation report](shared-demo-validation-20261003.md) for timings and
the exact verification boundary.
+
+## Preserve the document prefix before anchored chapters
+
+A separate production result omitted the pages before the first anchored
+chapter: Meta's nine-page release contained only pages 5–9, and SpaceX's
+407-page filing contained only pages 20–407. Resolving a TOC correctly did not
+guarantee complete document coverage: only the resolved section ranges were
+sent to rendering, tagging, and node assembly.
+
+The document prefix is every physical page before the first recognized chapter,
+including printed TOC pages. It belongs directly to the existing document root.
+Its chunk path is the filename itself; no `filename/Root` chapter is inserted,
+and existing chapter paths and ranges stay unchanged. Publication already maps
+a filename-only chunk to its canonical `Root` section. Navigation retains its
+existing root-body projection at the filename path.
+
+The prefix has explicit `document_prefix` evidence so an isolated prefix scope
+does not expand into the full-document Root fallback. It receives ordinary
+rendering, page tagging, and full-page citation assets, but does not undergo
+chapter-title refinement or single-child collapse. Prefix TOCs are retained
+through production and staged replay; TOC policy inside chapters is unchanged.
+The source evidence and level zero survive hierarchy artifact round trips.
+
+This repair covers opening pages only. It does not fill arbitrary middle or
+trailing gaps, regenerate existing production results, or change no-TOC
+full-document fallback behavior. The historical full-provider validation above
+is separate from the prefix-repair validation.
+
+### Prefix-repair verification on 2026-10-22
+
+Validation ran in an isolated Linux ARM64 environment, based on `main` commit
+`2ed1889626f63240bd0894ec0c24b7a7c5217dfb`.
+
+The new output contract failed for both missing-prefix examples before the
+repair; the first-page chapter and no-TOC fallback controls already passed.
+A separate staged-artifact contract reproduced the loss of level zero on
+reload before its repair. The final focused run passed **102 contracts**:
+
+```sh
+.venv/bin/pytest apps/worker/tests/contract/test_page_memory* \
+ apps/worker/tests/contract/test_profile_skeleton_anchor_wiring_contract.py -q
+```
+
+The full Worker contract suite also passed **405 contracts**, including the
+database contracts that reload application modules between environments:
+
+```sh
+.venv/bin/pytest apps/worker/tests/contract -q
+```
+
+This includes direct-root text and full-page citation assets, TOC retention in
+the prefix, unchanged chapter TOC policy, first-page chapters, no-TOC fallback,
+filename-only publication/navigation projection, and staged artifact reload.
+Ruff passed on the page-memory modules, changed stage scripts, and contracts;
+Pyright passed on the five changed application modules with zero errors and
+warnings.
+
+Captured production anatomy was also replayed against the actual originals:
+
+| Document | Real root-body output | Citation assets | Coverage evidence |
+| --- | --- | --- | --- |
+| Meta Q1 2026 Exhibit 99.1 | Filename path, physical pages 1–4, 11,265 text characters | Four real full-page PNGs | All nine pages assembled; five existing chapter paths retained |
+| SpaceX S-1 | Filename path, physical pages 1–19, 24,086 text characters; printed TOC page 17 retained | Nineteen real full-page PNGs | New prefix plus 683 unchanged original body chunks covers all 407 pages |
+
+The replay used real PDF rasterization, node assembly, and ZIP chunk-schema
+conversion. It reused captured chapter anatomy and substituted page-tag
+responses; it did not call model providers or publish a document revision.
+SpaceX rendered only the missing prefix and reused the original body results,
+rather than rerunning all 407 pages. Thus this is captured-profile seam
+verification, not a fresh full-provider parse or production deployment.
+
+### Existing demo revisions after deployment
+
+Deploying the Worker repair does not regenerate existing parsed revisions.
+After confirming the deployed Worker includes this change, reparse the known
+affected Meta release and SpaceX filing through the maintainer demo ingestion
+flow. Audit the remaining READY demos for missing opening pages before
+selecting additional sources. The restoration helper supports source selection
+and `--reparse-ready`; keep the previous revision available while an update runs.
+
+Validate physical-page coverage, prefix TOC retention, filename-only root-body
+paths, and page-citation assets on each new revision. Confirm that downstream
+readers consume the new revision after publication.
diff --git a/docs/vlm-usage-points.md b/docs/vlm-usage-points.md
new file mode 100644
index 000000000..157565ed5
--- /dev/null
+++ b/docs/vlm-usage-points.md
@@ -0,0 +1,77 @@
+# VLM Usage Points
+
+Inventory of live places that send **page or image pixels** to a vision model.
+Text-only LLM calls are listed at the bottom so they are not mistaken for VLM.
+
+Checked against the worker parse path and retrieval attach path. Re-trace before treating a new call as compliant.
+
+## Config
+
+| Knob | Role |
+|---|---|
+| `IMAGE_MODEL` | One vision model for parse. Official id: `deepseek-flash` (DeepSeek-V4.1-Flash, native multimodal). Routes through `DS_KEY` / `DS_URL`. |
+| `ASSET_MODEL` | Optional override for page-memory chart/table bbox only. Empty follows `IMAGE_MODEL`. Job metadata `page_memory_config.asset_model` still wins when set. |
+| Request `llm_config.vision` | Per-request override at call time. Not a server env switch. |
+
+`IMAGE_MODEL_MAX` is gone. Staging worker env may still pin an older name; local worker `.env` is what a local parse reads. Restart the worker after changing the env.
+
+Already-created jobs that baked a concrete `asset_model` keep that pin.
+
+## Shared PROFILE (PDF / PPTX, both parse tracks)
+
+Runs inside document profile before page-memory or chunk parse.
+
+| # | What it does | When it fires | Model |
+|---|---|---|---|
+| 1 | Coarse classify (scan / atlas / slides / generic) | Sample up to 10 pages | `IMAGE_MODEL` |
+| 2 | Confirm TOC start pages | Text scan found candidates | `IMAGE_MODEL` |
+| 3 | Extract TOC entries | After confirm | `IMAGE_MODEL` |
+| 4 | Calibrate: walk forward to find where a TOC title first starts | Printed TOC beat the outline; used to compute printed→physical offset | `IMAGE_MODEL` |
+| 5 | Calibrate: confirm the guessed page (usually one page) | Offset already computed; yes/no. If no, bisect then run 4 again | `IMAGE_MODEL` |
+| 6 | Null-page locate: grep first, then confirm the start page | TOC entry has no printed page | `IMAGE_MODEL` |
+
+If the PDF outline wins coverage, 4–6 are skipped.
+
+### PROFILE 4–6 in one example
+
+Cover + TOC occupy physical pages 1–3. Printed TOC says `1. Overview … 1`, `2. Method … 5`, `Appendix A` (no page).
+
+- **4** asks “Does `1. Overview` start on this page?” from after the TOC. Finds physical page 4 → offset +3.
+- **5** asks “Does `2. Method` start on page 8?” If yes, apply +3 to the rest. If no, find where the offset breaks.
+- **6** searches text for `Appendix A`, then asks which of those pages is the real section start. A text hit is not enough.
+
+## Page-memory track (API v2 `.pdf` / `.pptx`)
+
+| # | What it does | When it fires | Model |
+|---|---|---|---|
+| 7 | Detect outline titles on fat leaves | Default: leaf ≥ 4 pages | `IMAGE_MODEL` |
+| 8 | Per-page summary / entities | Almost every in-scope page; skip-tagged pages do not call | `IMAGE_MODEL` |
+| 9 | Node summary | Section spans pages, or one page hosts several nodes. Single exclusive page reuses 8 | `IMAGE_MODEL` |
+| 10 | Box figures/tables | Default on | `ASSET_MODEL` or `IMAGE_MODEL` |
+| 11 | Summarize cropped assets | Default **off** | same as 10 when enabled |
+
+## Text / chunk track (API v1, and non PDF/PPTX)
+
+| # | What it does | When it fires | Model |
+|---|---|---|---|
+| 12 | Atlas page info | Coarse routing is atlas **and** chunk track. Page-memory ignores atlas routing | `IMAGE_MODEL` |
+| 13 | Embedded image description | DOCX / Markdown (including PDF→Markdown) when image summary is on (default on) | `IMAGE_MODEL` |
+| 14 | Standalone image upload | Classify type; text-like images also transcribe | `IMAGE_MODEL` |
+
+Table / body summaries on this track are text LLM, not VLM.
+
+## Retrieval (after parse)
+
+| # | What it does | When it fires | Model |
+|---|---|---|---|
+| 15 | Attach HTTPS image URLs to the agent | Agentic retrieval on, and a tool returned a public image | Retrieval harness model, **not** `IMAGE_MODEL`. Cursor attaches HTTPS images. Own harness only attaches when the model name contains `vision`. |
+
+## Not VLM
+
+- Scanned-page text: local RapidOCR
+- TOC source choose, cross-page table continuity, title-tree refine, Excel/DOCX table summary: text LLM
+- Archived map-nav image filter: not on the live path
+
+## Debug
+
+Staged page-memory / text-track scripts reuse the same production calls. They are not extra VLM products.
diff --git a/packages/shared-python/shared/core/exceptions/webhook_exceptions.py b/packages/shared-python/shared/core/exceptions/webhook_exceptions.py
index 9e90c9224..2ca14dfbf 100644
--- a/packages/shared-python/shared/core/exceptions/webhook_exceptions.py
+++ b/packages/shared-python/shared/core/exceptions/webhook_exceptions.py
@@ -38,8 +38,8 @@ def __init__(
internal_message=internal_message,
user_message=user_message,
http_status_code=400,
+ details=details,
)
- self.details = details
class WebhookDeliveryException(WebhookException):
diff --git a/packages/shared-python/shared/models/database/job.py b/packages/shared-python/shared/models/database/job.py
index 8a4fb6bf3..d4d4831bc 100644
--- a/packages/shared-python/shared/models/database/job.py
+++ b/packages/shared-python/shared/models/database/job.py
@@ -126,6 +126,12 @@ class Job(Base):
# Indexes
__table_args__ = (
+ Index(
+ "idx_jobs_user_source_content_hash",
+ "user_id",
+ text("(job_metadata ->> 'source_content_sha256')"),
+ postgresql_where=text("job_metadata ->> 'source_content_sha256' IS NOT NULL"),
+ ),
Index("idx_job_status", "status"),
Index("idx_job_type", "job_type"),
Index("idx_job_created_at", "created_at"),
diff --git a/packages/shared-python/shared/models/schemas/job_metadata.py b/packages/shared-python/shared/models/schemas/job_metadata.py
index ec7d23454..9b5c7d930 100644
--- a/packages/shared-python/shared/models/schemas/job_metadata.py
+++ b/packages/shared-python/shared/models/schemas/job_metadata.py
@@ -49,6 +49,12 @@ class JobMetadataBase(BaseModel):
# Source-file fields.
source_type: Optional[str] = Field(None, description="Source type")
source_file_name: Optional[str] = Field(None, description="Source file name")
+ source_content_sha256: Optional[str] = Field(
+ None, pattern=r"^[0-9a-f]{64}$", description="SHA-256 of the original source bytes"
+ )
+ source_size_bytes: Optional[int] = Field(
+ None, ge=0, description="Original source file size in bytes"
+ )
source_url: Optional[str] = Field(None, description="Source URL")
file_url: Optional[str] = Field(None, description="File URL")
diff --git a/packages/shared-python/shared/services/chunks/chunk_connections.py b/packages/shared-python/shared/services/chunks/chunk_connections.py
index dcfa865ec..e8bc0d3d2 100644
--- a/packages/shared-python/shared/services/chunks/chunk_connections.py
+++ b/packages/shared-python/shared/services/chunks/chunk_connections.py
@@ -3,7 +3,7 @@
from __future__ import annotations
from collections.abc import Mapping, Sequence
-from typing import Any, TypeAlias, TypedDict
+from typing import Any, Final, TypeAlias, TypedDict
from shared.utils.chunk_refs import ChunkRefSpan, extract_chunk_ref_spans
@@ -13,14 +13,27 @@ class PositionPayload(TypedDict):
end: int
+RELATION_EMBEDS: Final = "embeds"
+RELATION_EMBEDDED_BY: Final = "embedded_by"
+RELATION_RELATED: Final = "related"
+# Reserved for future producers; no code path emits these yet.
+RELATION_CROSS_DOC_ENTITY: Final = "cross_doc_entity"
+RELATION_INTRA_DOC_REF: Final = "intra_doc_ref"
+
+# Relations whose targets are expanded when hydrating or deduplicating a
+# body chunk's connected assets. Reverse and future relations are excluded so
+# they stay purely additive for existing consumers.
+FORWARD_RELATIONS: Final = frozenset({RELATION_EMBEDS, RELATION_RELATED})
+
+_ASSET_CHUNK_TYPES: Final = frozenset({"image", "table"})
+
+
class ConnectionPayload(TypedDict, total=False):
target: str
+ target_document_id: str
relation: str
ref: str
position: PositionPayload
- score: float
- keywords: list[str]
- same_as_owner: str
RelationshipRef: TypeAlias = str | ChunkRefSpan
@@ -97,7 +110,7 @@ def convert_refs_to_embed_connections(
connection: ConnectionPayload = {
"target": target_id,
- "relation": "embeds",
+ "relation": RELATION_EMBEDS,
"ref": ref_text,
}
if isinstance(start, int) and isinstance(end, int):
@@ -129,20 +142,14 @@ def normalize_connect_to_targets(
normalized_item: ConnectionPayload = {
"target": normalized_target,
- "relation": str(item.get("relation") or "related"),
+ "relation": str(item.get("relation") or RELATION_RELATED),
}
- score = item.get("score")
- if isinstance(score, (int, float)):
- normalized_item["score"] = float(score)
- keywords = item.get("keywords")
- if isinstance(keywords, list):
- normalized_item["keywords"] = [str(keyword) for keyword in keywords]
+ target_document_id = item.get("target_document_id")
+ if target_document_id:
+ normalized_item["target_document_id"] = str(target_document_id)
ref = item.get("ref")
if ref:
normalized_item["ref"] = str(ref)
- same_as_owner = item.get("same_as_owner")
- if same_as_owner:
- normalized_item["same_as_owner"] = str(same_as_owner)
position = item.get("position")
if isinstance(position, dict):
start = position.get("start")
@@ -158,9 +165,7 @@ def normalize_connect_to_targets(
normalized.append(
{
"target": normalized_target,
- "relation": "related",
- "score": 1.0,
- "keywords": [],
+ "relation": RELATION_RELATED,
}
)
return normalized
@@ -197,6 +202,37 @@ def merge_connections(
return merged
+def attach_embedded_by_connections(chunks: Sequence[Mapping[str, Any]]) -> None:
+ """Give every embedded image/table an ``embedded_by`` edge to its owner.
+
+ Mutates each asset chunk's ``metadata["connect_to"]`` in place. ``chunks``
+ must already carry their final forward ``embeds`` edges, with targets
+ normalized to chunk ids.
+ """
+ assets_by_chunk_id: dict[str, list[Mapping[str, Any]]] = {}
+ for chunk in chunks:
+ if chunk.get("type") in _ASSET_CHUNK_TYPES:
+ assets_by_chunk_id.setdefault(str(chunk["chunk_id"]), []).append(chunk)
+
+ for owner in chunks:
+ owner_id = str(owner["chunk_id"])
+ for connection in owner["metadata"].get("connect_to") or []:
+ if (
+ not isinstance(connection, dict)
+ or connection.get("relation") != RELATION_EMBEDS
+ ):
+ continue
+ target_id = str(connection.get("target") or "")
+ if target_id == owner_id:
+ continue
+ for asset in assets_by_chunk_id.get(target_id, ()):
+ asset_metadata = asset["metadata"]
+ asset_metadata["connect_to"] = merge_connections(
+ asset_metadata.get("connect_to") or [],
+ [{"target": owner_id, "relation": RELATION_EMBEDDED_BY}],
+ )
+
+
def _parse_type_relationship_refs(type_value: object) -> list[str]:
if not isinstance(type_value, str) or "\n" not in type_value:
return []
@@ -206,10 +242,10 @@ def _parse_type_relationship_refs(type_value: object) -> list[str]:
def _get_connection_key(item: ConnectionValue) -> ConnectionKey:
if not isinstance(item, dict):
- return ("", "related", "")
+ return ("", RELATION_RELATED, "")
return (
str(item.get("target") or ""),
- str(item.get("relation") or "related"),
+ str(item.get("relation") or RELATION_RELATED),
str(item.get("ref") or ""),
)
diff --git a/packages/shared-python/shared/services/chunks/dataframe_chunk_converter.py b/packages/shared-python/shared/services/chunks/dataframe_chunk_converter.py
index e5ad3931f..4968b213b 100644
--- a/packages/shared-python/shared/services/chunks/dataframe_chunk_converter.py
+++ b/packages/shared-python/shared/services/chunks/dataframe_chunk_converter.py
@@ -12,8 +12,10 @@
from loguru import logger
from shared.services.chunks.chunk_connections import (
+ RELATION_RELATED,
ConnectionValue,
RelationshipRef,
+ attach_embedded_by_connections,
build_resource_target_map,
convert_refs_to_embed_connections,
merge_connections,
@@ -42,12 +44,12 @@ def iterrows(self) -> Iterable[tuple[object, _ParserRow]]: ...
class ChunkMetadata(TypedDict, total=False):
+ body_text_preview: str
keywords: list[str]
entities: list[dict[str, str]]
asset_title: str
summary: str
length: int
- tokens: list[str]
connect_to: list[ConnectionValue]
page_nums: list[int]
file_path: str
@@ -136,26 +138,6 @@ def _safe_parse_entities(value: object) -> list[dict[str, str]]:
return entities
-def _safe_parse_tokens(value: object) -> list[str]:
- if _is_missing(value):
- return []
- token_text = str(value).strip()
- if not token_text:
- return []
- if token_text.startswith("[") and token_text.endswith("]"):
- inner_text = token_text[1:-1].strip()
- if (inner_text.startswith("'") and inner_text.endswith("'")) or (
- inner_text.startswith('"') and inner_text.endswith('"')
- ):
- inner_text = inner_text[1:-1]
- token_text = inner_text
- if ";" in token_text:
- return [token.strip() for token in token_text.split(";") if token.strip()]
- if "->" in token_text:
- return [token.strip() for token in token_text.split("->") if token.strip()]
- return []
-
-
def _normalize_resource_ref(ref: RelationshipRef) -> str:
if isinstance(ref, dict):
ref_text = str(ref.get("ref") or "").strip()
@@ -203,9 +185,7 @@ def _parse_connect_to(value: object) -> list[ConnectionValue]:
return [
{
"target": connects_text,
- "relation": "related",
- "score": 1.0,
- "keywords": [],
+ "relation": RELATION_RELATED,
}
]
@@ -324,8 +304,6 @@ def dataframe_to_chunks(df: _ParserDataFrame | None) -> list[Dict[str, JsonValue
asset_title = str(row.get("asset_title", "") or "").strip()
if asset_title:
metadata["asset_title"] = asset_title
- if chunk_type != "page":
- metadata["tokens"] = _safe_parse_tokens(row.get("tokens"))
_merge_extra_metadata(metadata, _parse_extra_metadata(row.get("extra_metadata")))
if chunk_type == "image":
@@ -384,6 +362,7 @@ def dataframe_to_chunks(df: _ParserDataFrame | None) -> list[Dict[str, JsonValue
resource_target_map,
),
)
+ attach_embedded_by_connections(chunks)
logger.debug(f"DataFrame conversion completed: chunk count={len(chunks)}")
return cast(list[Dict[str, JsonValue]], chunks)
diff --git a/packages/shared-python/shared/services/retrieval/agent_explore/__init__.py b/packages/shared-python/shared/services/retrieval/agent_explore/__init__.py
index d313f765d..206ed702c 100644
--- a/packages/shared-python/shared/services/retrieval/agent_explore/__init__.py
+++ b/packages/shared-python/shared/services/retrieval/agent_explore/__init__.py
@@ -1,8 +1,9 @@
"""In-process tool-calling agentic retrieval route.
-Default agentic path when ``use_agentic`` is unset or true. Runs the
-``agent_tools`` corpus registry through an LLM tool-calling loop. Map-nav is
-archived under ``deprecated/mapnav/`` and is not a live route.
+Agentic path when ``use_agentic`` is true, or when it is unset and the query
+router selects agent. Runs the ``agent_tools`` corpus registry through an LLM
+tool-calling loop. Map-nav is archived under ``deprecated/mapnav/`` and is
+not a live route.
Which provider runs that loop (Cursor SDK or OpenAI-compatible) is the
``AGENT_EXPLORE_HARNESS`` switch resolved via ``resolve_harness()``.
diff --git a/packages/shared-python/shared/services/retrieval/agent_explore/bridge.py b/packages/shared-python/shared/services/retrieval/agent_explore/bridge.py
index 6c773c1c8..4a506c2b1 100644
--- a/packages/shared-python/shared/services/retrieval/agent_explore/bridge.py
+++ b/packages/shared-python/shared/services/retrieval/agent_explore/bridge.py
@@ -7,8 +7,10 @@
from __future__ import annotations
-from typing import Any
-
+from shared.services.retrieval.agent_explore.evidence_pool import (
+ Candidate,
+ pool_trace_records,
+)
from shared.services.retrieval.agent_explore.types import AgentStep
from shared.services.retrieval.trace import DecisionTraceStep
@@ -28,53 +30,49 @@ def build_decision_trace(steps: list[AgentStep]) -> list[DecisionTraceStep]:
observation: dict[str, object] = {"observation_text": observation_text}
if step.ref_status is not None:
observation["ref_status"] = step.ref_status
+ if step.candidates is not None:
+ observation["candidates"] = step.candidates
+ decision: dict[str, object] = {
+ "action": step.tool_name or "no_tool_call",
+ "args": step.tool_args,
+ "round_index": step.round_index,
+ }
+ result: dict[str, object] = {
+ "status": "error" if step.error else "ok",
+ "error": step.error,
+ }
+ if step.picked is not None:
+ result["picked"] = step.picked
+ if step.pick_rejected is not None:
+ result["pick_rejected"] = step.pick_rejected
trace_steps.append(
DecisionTraceStep(
step_index=step.step_index,
agent="agent_explore",
phase=phase,
observation=observation,
- decision={
- "action": step.tool_name or "no_tool_call",
- "args": step.tool_args,
- },
- result={
- "status": "error" if step.error else "ok",
- "error": step.error,
- },
- budget={
- "tokens_used_delta": step.tokens_used_delta,
- "tokens_used_total": step.tokens_used_total,
- },
+ decision=decision,
+ result=result,
+ budget={},
elapsed_ms=step.elapsed_ms,
)
)
return trace_steps
-def attach_ref_provenance(
+def attach_evidence_pool(
steps: list[DecisionTraceStep],
- *,
- agent_selected_refs: list[dict[str, Any]] | None,
- fallback_refs: list[dict[str, Any]],
- resolved_refs: list[dict[str, Any]],
- dropped_refs: list[dict[str, Any]],
+ pool: list[Candidate],
) -> list[DecisionTraceStep]:
- """Write ref provenance onto the existing finish TRACE step.
+ """Write the evidence pool onto the existing finish TRACE step.
- Reuses ``DecisionTraceStep.result``. If the episode never called finish,
- append one finish step so the same public TRACE shape still holds the
- four lists.
+ If the episode never called finish, append one finish step so the same
+ public TRACE shape still holds the pool.
"""
- provenance = {
- "agent_selected_refs": agent_selected_refs,
- "fallback_refs": fallback_refs,
- "resolved_refs": resolved_refs,
- "dropped_refs": dropped_refs,
- }
+ records = pool_trace_records(pool)
for step in reversed(steps):
if step.phase == "finish":
- step.result = {**step.result, **provenance}
+ step.result = {**step.result, "evidence_pool": records}
return steps
steps.append(
DecisionTraceStep(
@@ -82,8 +80,8 @@ def attach_ref_provenance(
agent="agent_explore",
phase="finish",
observation={"observation_text": "finish was not called"},
- decision={"action": "finish", "args": {"refs": None}},
- result={"status": "ok", "error": None, **provenance},
+ decision={"action": "finish", "args": {}},
+ result={"status": "ok", "error": None, "evidence_pool": records},
)
)
return steps
diff --git a/packages/shared-python/shared/services/retrieval/agent_explore/budget.py b/packages/shared-python/shared/services/retrieval/agent_explore/budget.py
index 47a0c6067..652f559d2 100644
--- a/packages/shared-python/shared/services/retrieval/agent_explore/budget.py
+++ b/packages/shared-python/shared/services/retrieval/agent_explore/budget.py
@@ -2,17 +2,13 @@
Standalone from ``nav/nav_token_budget.py`` on purpose — this package must
have no runtime dependency on ``nav/`` (see ``config.py``'s module
-docstring). Re-reads the same ``RETRIEVAL_NAV_TOKEN_LIMIT`` env var the plan
-calls for, so operators keep one token-limit knob across both agentic
-routes, but the counting mechanism is a fresh, request-scoped object (this
-episode runs as one async function, not a separate thread with recursive
-calls), not the nav contextvar machinery ``nav_token_budget`` needed for its
-own call shape.
+docstring). Exploration is limited by steps; the wall clock is a
+service-level guard. Tokens are not limited: ``tokens_used`` only records the
+episode total.
"""
from __future__ import annotations
-import os
import time
from dataclasses import dataclass, field
from typing import Any
@@ -22,26 +18,13 @@
AGENT_EXPLORE_WALL_CLOCK_SECONDS,
)
-_ENV_TOKEN_LIMIT = "RETRIEVAL_NAV_TOKEN_LIMIT"
-_DEFAULT_TOKEN_LIMIT = 100_000
-
-StopReason = str # one of: "token_limit" | "max_steps" | "wall_clock"
-
-
-def resolve_token_limit() -> int:
- """Always a positive limit: env override, else the shared default."""
- try:
- limit = int(os.environ.get(_ENV_TOKEN_LIMIT, "").strip())
- except ValueError:
- limit = 0
- return limit if limit > 0 else _DEFAULT_TOKEN_LIMIT
+StopReason = str # one of: "max_steps" | "wall_clock"
@dataclass
class EpisodeBudget:
- """Tracks one episode's LLM-token / step / wall-clock spend."""
+ """Tracks one episode's step / wall-clock spend and its token total."""
- token_limit: int = field(default_factory=resolve_token_limit)
max_steps: int = AGENT_EXPLORE_MAX_STEPS
wall_clock_seconds: float = AGENT_EXPLORE_WALL_CLOCK_SECONDS
tokens_used: int = 0
@@ -59,22 +42,13 @@ def record_usage(self, usage: dict[str, Any] | None) -> None:
def record_step(self) -> None:
self.steps_used += 1
+ def remaining_seconds(self) -> float:
+ return self.wall_clock_seconds - (time.monotonic() - self._started_at)
+
def exhausted(self) -> StopReason | None:
"""Return which budget dimension is exceeded, if any, else None."""
- if self.tokens_used >= self.token_limit:
- return "token_limit"
if self.steps_used >= self.max_steps:
return "max_steps"
- if time.monotonic() - self._started_at >= self.wall_clock_seconds:
+ if self.remaining_seconds() <= 0:
return "wall_clock"
return None
-
- def snapshot(self) -> dict[str, Any]:
- return {
- "token_limit": self.token_limit,
- "tokens_used": self.tokens_used,
- "max_steps": self.max_steps,
- "steps_used": self.steps_used,
- "wall_clock_seconds": self.wall_clock_seconds,
- "elapsed_seconds": round(time.monotonic() - self._started_at, 3),
- }
diff --git a/packages/shared-python/shared/services/retrieval/agent_explore/config.py b/packages/shared-python/shared/services/retrieval/agent_explore/config.py
index 258dfca1c..4cb318acb 100644
--- a/packages/shared-python/shared/services/retrieval/agent_explore/config.py
+++ b/packages/shared-python/shared/services/retrieval/agent_explore/config.py
@@ -8,8 +8,6 @@
from __future__ import annotations
-from shared.services.retrieval.agent_tools.registry import REF_ADDRESS_ONE_OF, REF_ADDRESS_RULE
-
AGENT_EXPLORE_MODEL = "deepseek-v4-flash"
# Model for AGENT_EXPLORE_HARNESS=cursor_sdk (harness/cursor_harness.py) —
@@ -22,11 +20,11 @@
AGENT_EXPLORE_CURSOR_MODEL = "composer-2.5"
# One LLM turn = one round-trip that may contain several parallel tool calls
-# (see episode.py).
-AGENT_EXPLORE_MAX_STEPS = 12
+# (see episode.py). Both harnesses count one explore turn as one step.
+AGENT_EXPLORE_MAX_STEPS = 15
# Wall-clock ceiling for the whole episode (LLM round-trips + tool
-# dispatch), independent of the token budget. New constant, not tuned yet.
+# dispatch). A service-level guard, never shown to the model.
AGENT_EXPLORE_WALL_CLOCK_SECONDS = 180.0
# Max tokens requested per LLM completion turn (thinking disabled — see
@@ -38,104 +36,43 @@
FINISH_TOOL_SCHEMA: dict[str, object] = {
"type": "object",
"properties": {
- "refs": {
- "type": "array",
- "description": (
- "Final cited evidence, in priority order. Each item "
- "identifies one section or chunk you have already looked at "
- "via corpus.read, corpus.assets, or corpus.query_table."
- ),
- "items": {
- "type": "object",
- "properties": {
- "document_id": {
- "type": "string",
- "description": "Document that owns the cited section or chunk.",
- },
- "section_path": {
- "type": "string",
- "description": "Cited section. Omit when chunk_id is set.",
- },
- "chunk_id": {
- "type": "string",
- "description": "Cited chunk. Omit when section_path is set.",
- },
- },
- "required": ["document_id"],
- "oneOf": REF_ADDRESS_ONE_OF,
- "additionalProperties": False,
- "description": REF_ADDRESS_RULE,
- },
- },
"notes": {
"type": "string",
"description": (
- "Optional short note on why these refs answer the query, "
- "or why none were found."
+ "Optional short note for the answer writer, or why nothing "
+ "was found."
),
},
},
- "required": ["refs"],
+ "required": [],
"additionalProperties": False,
}
FINISH_TOOL_DESCRIPTION = (
- "Call this when you have gathered enough evidence to answer the query, "
- "or when you are certain the corpus does not contain an answer. This "
- "ends the exploration — do not answer in plain text; the final answer "
- "is synthesized downstream from the refs you cite here."
+ "End the exploration now. The evidence pool becomes the final evidence."
)
-# Appended after the verbatim CORPUS_SCHEMA.md text (schema_doc.py) to form
-# this harness's system prompt. Kept out of CORPUS_SCHEMA.md itself because
-# the finish-tool loop contract is agent_explore-specific, not something the
-# MCP-facing harnesses (Cursor/Codex/Claude) need — see that file's own
-# "single source... do not duplicate" header.
-LOOP_CONTRACT_SUFFIX = f"""
+# Harness-level tool, not in agent_tools.REGISTRY, so MCP never exposes it.
+PICK_TOOL_NAME = "corpus.pick"
----
-
-## Exploration loop contract
-
-You are exploring this corpus autonomously to answer one query. Tool
-names in this prompt are the registered names (`corpus.read`). This
-function-calling loop exposes the same tools with `.` replaced by `_`
-(`corpus_read`); use that underscore form when calling. Logs keep the
-dotted name.
-
-Use the tools above to navigate; you may call several tools in one turn
-when they are independent. If a call's arguments depend on another
-call's result, do not issue them in the same turn. In particular: do
-not call `corpus.grep` in the same turn as `corpus.recall`,
-`corpus.read`, `corpus.list_documents`, `corpus.outline`,
-`corpus.node_filter`, or `corpus.assets` unless `pattern` / `patterns`
-is already known — those calls produce the term; a grep with no term is
-an empty call. Wait for the result, then grep. `corpus.list_documents`
-enumerates the entire namespace: use it only if the user explicitly
-asks to list or inventory the corpus's documents, never as the starting
-step for a content question. When you have enough evidence, call
-`{FINISH_TOOL_NAME}`
-with the `refs` you want cited as the answer — do not write the final answer
-as plain text yourself, it is synthesized downstream from your cited refs.
-If you exhaust your tool budget without a confident answer, call
-`{FINISH_TOOL_NAME}` with your best-effort `refs` (or an empty list plus a
-`notes` explanation of why nothing was found) rather than continuing to
-call other tools.
-
-`refs` is REQUIRED and must not be omitted or left empty if you called
-`corpus.read`, `corpus.assets`, or `corpus.query_table` even once during
-this exploration: copy the `document_id` and `chunk_id`/`section_path` of
-every section/chunk you looked at that supports your answer into `refs`
-before calling `{FINISH_TOOL_NAME}`. Calling `{FINISH_TOOL_NAME}` with no
-`refs` after having already read relevant content discards that evidence.
+PICK_TOOL_SCHEMA: dict[str, object] = {
+ "type": "object",
+ "properties": {
+ "pick": {
+ "type": "array",
+ "items": {"type": "string", "pattern": r"^(R\d+\.\d+|O\d+)$"},
+ "uniqueItems": True,
+ "description": (
+ "Ids from your latest corpus.read / corpus.outline results to "
+ "keep. Pass an empty list to keep none."
+ ),
+ },
+ },
+ "required": ["pick"],
+ "additionalProperties": False,
+}
-Before calling `{FINISH_TOOL_NAME}`, if you have not called `corpus.read`,
-`corpus.assets`, or `corpus.query_table` even once this exploration, you
-have not actually verified anything yet — a search tool returning
-candidates is not the same as having read them. In that case, either read
-your best candidate section first, or — only if you have positively
-confirmed there is nothing to read (e.g. a structural check came back
-with zero matching sections) — say so explicitly in `notes`. Repeatedly
-rephrasing the same search instead of reading a candidate you already
-found is not a substitute for reading it.
-"""
+PICK_TOOL_DESCRIPTION = (
+ "Pick which of your latest corpus.read / corpus.outline results join the "
+ "evidence pool. Body text you read but do not pick cannot be read again."
+)
diff --git a/packages/shared-python/shared/services/retrieval/agent_explore/dispatch.py b/packages/shared-python/shared/services/retrieval/agent_explore/dispatch.py
index f002472bd..febf2da20 100644
--- a/packages/shared-python/shared/services/retrieval/agent_explore/dispatch.py
+++ b/packages/shared-python/shared/services/retrieval/agent_explore/dispatch.py
@@ -20,14 +20,21 @@
from shared.services.retrieval.document_scope import DocumentScope
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
from contextlib import AbstractAsyncContextManager
from typing import Any
from sqlalchemy.ext.asyncio import AsyncSession
from shared.services.retrieval.corpus_revision_context import CorpusRevisionContext
-from shared.services.retrieval.agent_tools import REGISTRY, ToolBudget, ToolContext, ToolResult
+from shared.services.retrieval.agent_tools import (
+ REGISTRY,
+ Decision,
+ ReadableAddresses,
+ ToolBudget,
+ ToolContext,
+ ToolResult,
+)
DbFactory = Callable[[], AbstractAsyncContextManager[AsyncSession]]
@@ -42,6 +49,8 @@ async def dispatch_tool_call(
document_scope: DocumentScope = DocumentScope(),
budget: ToolBudget | None = None,
query: str = "",
+ readable: ReadableAddresses | None = None,
+ decided: Mapping[tuple[str, str], Decision] | None = None,
) -> ToolResult:
"""Run one ``REGISTRY`` tool call against a fresh, call-scoped DB session.
@@ -52,7 +61,8 @@ async def dispatch_tool_call(
into the (call-scoped, already-closed) ``ToolContext``. ``query`` is the
end user's original query for this episode (see ``ToolContext.query``'s
docstring) — both harnesses' ``run_episode`` already receive it, so this
- is a pass-through, not a new source of truth.
+ is a pass-through, not a new source of truth. ``readable``/``decided`` are
+ the episode's ``corpus.read`` gates, passed through unchanged.
"""
try:
async with db_factory() as db:
@@ -65,6 +75,8 @@ async def dispatch_tool_call(
budget=budget or ToolBudget(),
document_scope=document_scope.narrow(list(pins)) if pins is not None else document_scope,
query=query,
+ readable=readable,
+ decided=decided,
)
return await REGISTRY.dispatch(name, tool_ctx, args)
except Exception as exc: # noqa: BLE001 - one broken tool must not kill the episode
diff --git a/packages/shared-python/shared/services/retrieval/agent_explore/evidence_pool.py b/packages/shared-python/shared/services/retrieval/agent_explore/evidence_pool.py
new file mode 100644
index 000000000..b13a53161
--- /dev/null
+++ b/packages/shared-python/shared/services/retrieval/agent_explore/evidence_pool.py
@@ -0,0 +1,404 @@
+"""Per-round addresses, pick ids, and the episode evidence pool.
+
+Results of one round become usable only when the next round begins: their
+addresses become readable, and their pick ids open a pick phase.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any, Literal
+
+from shared.services.retrieval.agent_explore.budget import EpisodeBudget
+from shared.services.retrieval.agent_tools import Decision, ReadableAddresses, ToolResult
+from shared.services.retrieval.hydration.evidence_compose import group_evidence_units
+from shared.services.retrieval.hydration.row_utils import (
+ iter_connected_target_ids,
+ normalize_chunk_type,
+)
+from shared.services.retrieval.settings import ASSET_CHUNK_TYPES
+
+
+@dataclass(frozen=True)
+class Candidate:
+ handle: str
+ kind: Literal["read", "outline"]
+ document_id: str
+ source_file_name: str
+ section_path: str | None = None
+ chunk_type: str | None = None
+ chunk_ids: tuple[str, ...] = ()
+ summary: str = ""
+ extra_sections: int = 0
+ outline_lines: tuple[str, ...] = ()
+
+
+@dataclass
+class PickOutcome:
+ added: list[str] = field(default_factory=list)
+ rejected: list[dict[str, str]] = field(default_factory=list)
+
+
+class EvidencePool:
+ def __init__(self) -> None:
+ self.entries: list[Candidate] = []
+ self.round_index = 0
+ self.pick_phase = False
+ self._read_calls = 0
+ self._outline_calls = 0
+ self._chunk_keys: set[tuple[str, str]] = set()
+ self._seen_active: set[tuple[str, str]] = set()
+ self._seen_staged: set[tuple[str, str]] = set()
+ self._batch: dict[str, Candidate] = {}
+ self._batch_staged: dict[str, Candidate] = {}
+ self._batch_round = 0
+ self._decided: dict[tuple[str, str], Decision] = {}
+ self._queried_tables: dict[tuple[str, str], str] = {}
+
+ def begin_round(self) -> None:
+ self.round_index += 1
+ self._seen_active |= self._seen_staged
+ self._seen_staged = set()
+ if self._batch_staged:
+ self._batch.update(self._batch_staged)
+ self._batch_staged = {}
+ self._batch_round = self.round_index - 1
+ self.pick_phase = bool(self._batch)
+
+ def issue(self, tool_name: str, result: ToolResult) -> list[Candidate]:
+ if result.error:
+ return []
+ self._collect_seen(result)
+ self._record_queried_table(tool_name, result)
+ if tool_name == "corpus.read":
+ return self._issue_read(result)
+ if tool_name == "corpus.outline":
+ return self._issue_outline(result)
+ return []
+
+ def apply_pick(self, handles: list[str]) -> PickOutcome:
+ outcome = PickOutcome()
+ seen: set[str] = set()
+ for handle in handles:
+ if handle in seen:
+ continue
+ seen.add(handle)
+ candidate = self._batch.get(handle)
+ if candidate is None:
+ outcome.rejected.append({"handle": handle, "reason": "unknown id"})
+ continue
+ if candidate.kind == "read" and self._all_chunks_in_pool(candidate):
+ outcome.rejected.append({"handle": handle, "reason": "already in pool"})
+ continue
+ self.entries.append(candidate)
+ for chunk_id in candidate.chunk_ids:
+ self._chunk_keys.add((candidate.document_id, chunk_id))
+ outcome.added.append(handle)
+ picked = set(outcome.added)
+ for candidate in self._batch.values():
+ if candidate.kind != "read":
+ continue
+ picked_handle = candidate.handle if candidate.handle in picked else None
+ for chunk_id in candidate.chunk_ids:
+ self._decided[(candidate.document_id, chunk_id)] = Decision(
+ read_round=self._batch_round,
+ picked_handle=picked_handle,
+ handle=candidate.handle,
+ )
+ self._batch = {}
+ self.pick_phase = False
+ return outcome
+
+ def readable(self) -> ReadableAddresses:
+ return frozenset(self._seen_active)
+
+ def decided(self) -> Mapping[tuple[str, str], Decision]:
+ return MappingProxyType(dict(self._decided))
+
+ def queried_tables(self) -> Mapping[tuple[str, str], str]:
+ return MappingProxyType(self._queried_tables)
+
+ def render_candidates(self, candidates: list[Candidate]) -> str:
+ if not candidates:
+ return ""
+ if len(candidates) == 1 and candidates[0].kind == "outline":
+ return f"[pick id for this result: {candidates[0].handle} = this outline]"
+ parts: list[str] = []
+ for candidate in candidates:
+ label = candidate.section_path or candidate.handle
+ parts.append(f"{candidate.handle} = {label}")
+ return f"[pick ids for this result: {', '.join(parts)}]"
+
+ def render_pool(self) -> str:
+ if not self.entries:
+ return "evidence pool: empty"
+ lines = [f"evidence pool ({len(self.entries)}):"]
+ for candidate in self.entries:
+ if candidate.kind == "outline":
+ lines.extend(candidate.outline_lines)
+ continue
+ path = candidate.section_path or ""
+ kind = candidate.chunk_type or "text"
+ lines.append(
+ f" [{candidate.handle}] {candidate.source_file_name} / {path} [{kind}]"
+ )
+ if candidate.summary:
+ lines.append(f" summary: {candidate.summary}")
+ return "\n".join(lines)
+
+ def chunk_refs(self) -> list[dict[str, str]]:
+ return pool_chunk_refs(self.entries)
+
+ def _all_chunks_in_pool(self, candidate: Candidate) -> bool:
+ if not candidate.chunk_ids:
+ return False
+ return all(
+ (candidate.document_id, chunk_id) in self._chunk_keys
+ for chunk_id in candidate.chunk_ids
+ )
+
+ def _record_queried_table(self, tool_name: str, result: ToolResult) -> None:
+ if tool_name != "corpus.query_table":
+ return
+ document_id = str(result.payload.get("document_id") or "").strip()
+ chunk_id = str(result.payload.get("chunk_id") or "").strip()
+ table_html = result.payload.get("table_html")
+ if not document_id or not chunk_id or not isinstance(table_html, str):
+ return
+ self._queried_tables[(document_id, chunk_id)] = table_html
+
+ def _collect_seen(self, result: ToolResult) -> None:
+ for key in ("rows", "chunks"):
+ rows = result.payload.get(key)
+ if not isinstance(rows, list):
+ continue
+ for row in rows:
+ if not isinstance(row, dict):
+ continue
+ document_id = str(row.get("document_id") or "")
+ if not document_id:
+ continue
+ section_path = str(row.get("section_path") or "").strip()
+ if section_path:
+ self._seen_staged.add((document_id, section_path))
+ chunk_ids = [
+ row.get("chunk_id"),
+ *(row.get("mounted_chunk_ids") or []),
+ *iter_connected_target_ids(row),
+ ]
+ for chunk_id in chunk_ids:
+ if chunk_id:
+ self._seen_staged.add((document_id, str(chunk_id)))
+
+ def _issue_read(self, result: ToolResult) -> list[Candidate]:
+ self._read_calls += 1
+ statuses = result.payload.get("refs")
+ chunks = result.payload.get("chunks")
+ if not isinstance(statuses, list):
+ return []
+ chunk_rows = chunks if isinstance(chunks, list) else []
+ rows_by_id = {
+ str(row.get("chunk_id") or ""): row
+ for row in chunk_rows
+ if isinstance(row, dict) and row.get("chunk_id")
+ }
+ issued: list[Candidate] = []
+ for index, entry in enumerate(statuses, start=1):
+ if not isinstance(entry, dict) or entry.get("status") != "ok":
+ continue
+ chunk_ids = tuple(
+ str(item) for item in (entry.get("chunk_ids") or []) if str(item)
+ )
+ first = rows_by_id.get(chunk_ids[0]) if chunk_ids else None
+ document_id = str(entry.get("document_id") or "")
+ section_path = str(entry.get("section_path") or "").strip() or None
+ if first and not section_path:
+ section_path = str(first.get("section_path") or "").strip() or None
+ chunk_type = normalize_chunk_type((first or {}).get("chunk_type"))
+ summary = _read_summary(first, chunk_type)
+ candidate = Candidate(
+ handle=f"R{self._read_calls}.{index}",
+ kind="read",
+ document_id=document_id,
+ source_file_name=str((first or {}).get("source_file_name") or ""),
+ section_path=section_path,
+ chunk_type=chunk_type or None,
+ chunk_ids=chunk_ids,
+ summary=summary,
+ extra_sections=max(len(chunk_ids) - 1, 0),
+ )
+ issued.append(candidate)
+ self._batch_staged[candidate.handle] = candidate
+ return issued
+
+ def _issue_outline(self, result: ToolResult) -> list[Candidate]:
+ self._outline_calls += 1
+ rows = result.payload.get("rows")
+ details = result.payload.get("details")
+ if not isinstance(rows, list) or not rows:
+ return []
+ documents = details.get("documents") if isinstance(details, dict) else None
+ names: Mapping[str, Any] = documents if isinstance(documents, dict) else {}
+ handle = f"O{self._outline_calls}"
+ first = rows[0] if isinstance(rows[0], dict) else {}
+ document_id = str(first.get("document_id") or "")
+ source_file_name = str(names.get(document_id) or first.get("title") or "")
+ lines = _outline_title_tree(rows, names, handle=handle)
+ candidate = Candidate(
+ handle=handle,
+ kind="outline",
+ document_id=document_id,
+ source_file_name=source_file_name,
+ outline_lines=tuple(lines),
+ )
+ self._batch_staged[candidate.handle] = candidate
+ return [candidate]
+
+
+def render_budget(budget: EpisodeBudget) -> str:
+ return f"budget: steps {budget.steps_used}/{budget.max_steps}"
+
+
+def render_pick_outcome(outcome: PickOutcome) -> str:
+ text = f"picked: {', '.join(outcome.added) or 'none'}"
+ if outcome.rejected:
+ rejected = ", ".join(
+ f"{item['handle']} ({item['reason']})" for item in outcome.rejected
+ )
+ text += f"; rejected: {rejected}"
+ return text
+
+
+def render_trace_line(
+ index: int,
+ wire_name: str,
+ args: dict[str, Any],
+ status: str,
+) -> str:
+ encoded = json.dumps(args, ensure_ascii=False, default=str)
+ return f"{index}. {wire_name} {encoded} -> {status}"
+
+
+def pool_chunk_refs(entries: list[Candidate]) -> list[dict[str, str]]:
+ refs: list[dict[str, str]] = []
+ for candidate in entries:
+ if candidate.kind != "read":
+ continue
+ for chunk_id in candidate.chunk_ids:
+ refs.append({"document_id": candidate.document_id, "chunk_id": chunk_id})
+ return refs
+
+
+def compose_pool_evidence(
+ entries: list[Candidate],
+ assembled_rows: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+ rows_by_id = {
+ str(row.get("chunk_id") or ""): row
+ for row in assembled_rows
+ if row.get("chunk_id")
+ }
+ units: list[dict[str, Any]] = []
+ for candidate in entries:
+ if candidate.kind == "outline":
+ text = "\n".join(candidate.outline_lines)
+ if not text:
+ continue
+ units.append(
+ {
+ "document_id": candidate.document_id,
+ "source_file_name": candidate.source_file_name,
+ "section_path": "",
+ "sort_order": None,
+ "parts": [{"type": "text", "text": text}],
+ "kind": "outline",
+ }
+ )
+ continue
+ chunk_rows = sorted(
+ (rows_by_id[chunk_id] for chunk_id in candidate.chunk_ids if chunk_id in rows_by_id),
+ key=lambda row: row["sort_order"],
+ )
+ parts = [part for row in chunk_rows for part in row["composed"]]
+ if not parts:
+ continue
+ units.append(
+ {
+ "document_id": candidate.document_id,
+ "source_file_name": candidate.source_file_name,
+ "section_path": candidate.section_path or "",
+ "sort_order": chunk_rows[0]["sort_order"],
+ "parts": parts,
+ "kind": "read",
+ }
+ )
+ return group_evidence_units(units)
+
+
+def pool_trace_records(entries: list[Candidate]) -> list[dict[str, Any]]:
+ records: list[dict[str, Any]] = []
+ for candidate in entries:
+ records.append(
+ {
+ "handle": candidate.handle,
+ "kind": candidate.kind,
+ "document_id": candidate.document_id,
+ "section_path": candidate.section_path,
+ "chunk_ids": list(candidate.chunk_ids),
+ }
+ )
+ return records
+
+
+def trace_status(result: ToolResult) -> str:
+ if result.error:
+ return f"failed: {result.error}"
+ statuses = result.payload.get("refs")
+ if isinstance(statuses, list):
+ failures: list[str] = []
+ for index, entry in enumerate(statuses, start=1):
+ if isinstance(entry, dict) and entry.get("status") == "failed":
+ reason = str(entry.get("reason") or "failed")
+ failures.append(f"ref {index} failed: {reason}")
+ if failures:
+ return "partial: " + "; ".join(failures)
+ return "ok"
+
+
+def _read_summary(row: dict[str, Any] | None, chunk_type: str) -> str:
+ if not row:
+ return ""
+ if chunk_type in ASSET_CHUNK_TYPES:
+ metadata = row.get("chunk_metadata") or {}
+ if isinstance(metadata, dict):
+ return str(metadata.get("summary") or "").strip()
+ return ""
+ return str(row.get("section_summary") or "").strip()
+
+
+def _outline_title_tree(
+ rows: list[Any], names: Mapping[str, Any], *, handle: str
+) -> list[str]:
+ lines: list[str] = []
+ current_doc = ""
+ first_doc = True
+ for row in rows:
+ if not isinstance(row, dict):
+ continue
+ document_id = str(row.get("document_id") or "")
+ if document_id != current_doc:
+ current_doc = document_id
+ file_name = str(names.get(document_id) or row.get("title") or document_id)
+ if first_doc:
+ lines.append(f" [{handle}] {file_name}")
+ first_doc = False
+ else:
+ lines.append(f" {file_name}")
+ title = str(row.get("title") or "").strip()
+ if title:
+ depth = int(row.get("depth") or 0)
+ lines.append(f"{' ' * (depth + 1)}{title}")
+ return lines
diff --git a/packages/shared-python/shared/services/retrieval/agent_explore/harness/cursor_harness.py b/packages/shared-python/shared/services/retrieval/agent_explore/harness/cursor_harness.py
index ba2a3b4bd..591dba905 100644
--- a/packages/shared-python/shared/services/retrieval/agent_explore/harness/cursor_harness.py
+++ b/packages/shared-python/shared/services/retrieval/agent_explore/harness/cursor_harness.py
@@ -14,50 +14,35 @@
guarded import in ``_require_cursor_sdk`` raises a clear error at episode
start if ``cursor-sdk`` isn't installed.
-Architectural difference from ``openai_harness.py`` that budget enforcement
-has to work around: this harness does not control the LLM turn loop.
-``agent.send(...)`` + ``await run.wait()`` hands the *entire* multi-turn
-tool-calling loop to the Cursor SDK; the host process only sees (a)
-``execute`` callbacks for each ``corpus.*``/``finish`` tool call — run
-synchronously off the SDK's own thread and bridged back onto this event
-loop via ``asyncio.run_coroutine_threadsafe`` (mirrors the PoC's
-``_dispatch_sync``) — and (b) the terminal ``RunResult`` once ``wait()``
-returns. There is no per-turn hook to inspect budget mid-turn and force
-``tool_choice`` the way ``openai_harness.py`` does. Each budget dimension is
-therefore enforced (or explicitly not) differently here:
-
-- **``max_steps``**: a plain counter (``budget.steps_used``, incremented once
- per ``corpus.*`` dispatch — ``finish`` does not count, it ends the episode
- on its own) checked in ``_dispatch_sync`` *before* dispatching. Once the
- counter reaches ``budget.max_steps``, further ``corpus.*`` calls are not
- forwarded to ``REGISTRY`` at all — the callback returns a fixed
- "budget exhausted, call finish now" string instead. This is a real,
- synchronous cutoff (unlike the two dimensions below): no reliance on
- cancelling the SDK run from a background task.
-- **``wall_clock``**: ``asyncio.wait_for(run.wait(), timeout=budget.wall_clock_seconds)``,
- per the plan. On timeout, best-effort ``await run.cancel()`` (own short
- timeout, so a hung cancel RPC can't hang this call forever) so the
- underlying agent run actually stops server-side instead of merely being
- abandoned by this process, then the episode result is built from whatever
- ``finish``/tool-trajectory refs were captured before the timeout.
-- **``token_limit``**: **not actively enforced mid-run.** Verified by reading
- the installed ``cursor-sdk`` package's source
- (``cursor_sdk._run_base._RunBase.usage``, 2026-09) that cumulative token
- usage is incrementally accumulated from ``SDKUsageMessage`` stream events
- as ``run.wait()`` consumes them, and exposed as a live ``run.usage``
- property — so a mid-run cutoff (e.g. a polling task calling
- ``run.cancel()``) is *plausible*. It was **not** exercised against a real
- ``CURSOR_API_KEY`` run in this change (no key available in the
- implementation environment), so building an active cutoff on top of an
- unverified live-update assumption was judged higher-risk than shipping.
- ``EpisodeBudget.exhausted()``'s ``token_limit`` dimension is therefore left
- unchecked here by design; ``budget.tokens_used`` is only populated
- *post-hoc* from the terminal ``RunResult.usage`` for observability
- (``EpisodeResult.tokens_used``), after the episode has already finished.
- If ``eval-cursor-harness`` confirms ``run.usage`` does update live against
- a real key, promoting this to an active cutoff (mirroring the
- ``max_steps``/``wall_clock`` pattern above) is straightforward follow-up
- work — deliberately not done speculatively here.
+This harness does not control the LLM turn loop. ``agent.send(...)`` +
+``await run.wait()`` hands the multi-turn tool-calling loop to the Cursor
+SDK. The host process only sees ``execute`` callbacks, ``on_delta`` updates
+(driven by ``run.wait()``), and the terminal ``RunResult``.
+
+Rounds: calls the model issues in one turn share one ``model_call_id``,
+carried by the ``tool-call-started`` update. That update and the tool
+callback arrive almost together, so each callback first waits for its own
+tag (at most the remaining wall clock; without it the call fails with
+``round tag missing``, unexecuted and uncounted). A new ``model_call_id``
+begins a new pool round.
+
+Pick phase: the Cursor tool list is fixed when the agent is created, so a
+round after a successful read or outline accepts only ``corpus_pick``; every
+other call (including ``finish``) is rejected at once, unexecuted and
+uncounted. ``corpus_pick`` itself never counts as a step.
+
+Budget dimensions:
+
+- **``max_steps``**: one explore round (shared ``model_call_id``) is one
+ step, matching the OpenAI harness. Checked when a new explore round
+ starts. Once ``budget.steps_used`` reaches ``budget.max_steps``, further
+ explore rounds are not forwarded; the callback returns a fixed exhausted
+ message plus pool and budget. Same-round sibling ``corpus.*`` calls share
+ that one step and still dispatch.
+- **``wall_clock``**: ``asyncio.wait_for(run.wait(), timeout=budget.wall_clock_seconds)``.
+ On timeout, best-effort ``await run.cancel()``.
+- **tokens**: not limited; ``budget.tokens_used`` is only the episode total
+ from the terminal ``RunResult.usage``.
"""
from __future__ import annotations
@@ -78,43 +63,52 @@
FINISH_TOOL_DESCRIPTION,
FINISH_TOOL_NAME,
FINISH_TOOL_SCHEMA,
- LOOP_CONTRACT_SUFFIX,
+ PICK_TOOL_DESCRIPTION,
+ PICK_TOOL_NAME,
+ PICK_TOOL_SCHEMA,
)
from shared.services.retrieval.agent_explore.dispatch import DbFactory, dispatch_tool_call
+from shared.services.retrieval.agent_explore.evidence_pool import (
+ EvidencePool,
+ render_budget,
+ render_pick_outcome,
+)
+from shared.services.retrieval.agent_explore.prompt import AGENT_SYSTEM_PROMPT
from shared.services.retrieval.agent_explore.shared import (
- EVIDENCE_TOOL_NAMES,
- budget_status_line,
cursor_execute_content,
- finish_refs_from_args,
invalid_finish_message,
+ invalid_pick_message,
read_ref_status,
- select_episode_refs,
tool_message_content,
validate_finish_args,
+ validate_pick_args,
wire_safe_tool_name,
)
from shared.services.retrieval.agent_explore.types import AgentStep, EpisodeResult
-from shared.services.retrieval.agent_tools import (
- REGISTRY,
- ToolBudget,
- ToolResult,
- load_corpus_schema_text,
-)
+from shared.services.retrieval.agent_tools import REGISTRY, ToolBudget, ToolResult
# Grace period for the underlying agent run to actually stop, after a
# best-effort run.cancel() following a wall_clock timeout, before this
-# process gives up waiting for a terminal RunResult and falls back to
-# whatever refs the trajectory already captured. Not tuned against real
-# cancel-RPC latency yet (no CURSOR_API_KEY in the implementation
-# environment) — revisit with eval-cursor-harness data.
+# process gives up waiting for a terminal RunResult.
_CANCEL_GRACE_SECONDS = 30.0
_BUDGET_EXHAUSTED_MESSAGE = (
"error: step budget exhausted for this episode — do not call any more "
- "corpus.* tools; call finish now with whatever refs you already have "
- "(or an empty list plus a notes explanation)."
+ "corpus.* tools; call finish now."
+)
+
+_PICK_PHASE_REJECTION = (
+ "Pick phase: only corpus_pick is accepted now. Pick from R/O ids above, "
+ "or pass an empty list."
+)
+
+_PICK_PHASE_INSTRUCTION = (
+ "Pick phase: you can only call corpus_pick now. Pick the ids worth "
+ "keeping, or pass an empty list."
)
+_ROUND_TAG_MISSING = "round tag missing"
+
def _require_cursor_sdk() -> Any:
try:
@@ -129,6 +123,10 @@ def _require_cursor_sdk() -> Any:
return cursor_sdk
+def _state_tail(pool: EvidencePool, budget: EpisodeBudget) -> str:
+ return "\n\n".join([pool.render_pool(), render_budget(budget)])
+
+
class CursorHarness:
"""``Harness`` implementation over the Cursor SDK local agent."""
@@ -156,42 +154,82 @@ async def run_episode(
tool_budget = ToolBudget()
loop = asyncio.get_running_loop()
- # The Cursor SDK delivers same-turn parallel tool calls as concurrent
- # HTTP requests on separate threads (ThreadingHTTPServer in
- # cursor_sdk._tool_callback) — CORPUS_SCHEMA.md's loop contract
- # explicitly invites the model to call several independent tools in
- # one turn. Without this lock, the check-then-increment on
- # budget.steps_used below is a race: several concurrently-dispatched
- # calls can each read "not exhausted yet" before any of them
- # increments, letting more calls through than max_steps allows.
- budget_lock = threading.Lock()
+ state = threading.Condition()
+ pool = EvidencePool()
+ round_of: dict[str, str] = {}
+ current_round: dict[str, Any] = {"id": None, "pick_phase": False}
steps: list[AgentStep] = []
- trajectory_refs: list[dict[str, Any]] = []
- # None until finish specifies refs. Explicit ``refs: []`` stays [].
- # Omitted refs still fall back via select_episode_refs.
- finish_state: dict[str, Any] = {"refs": None, "notes": ""}
stop_reason = "finished"
+ def _on_delta(update: Any) -> None:
+ if getattr(update, "type", None) != "tool-call-started":
+ return
+ with state:
+ round_of[update.call_id] = update.model_call_id
+ state.notify_all()
+
+ def _enter_round(ctx: Any) -> tuple[bool | None, bool]:
+ """Wait for this call's round tag (caller holds ``state``).
+
+ Returns ``(pick_phase, is_new_round)``. ``pick_phase`` is
+ ``None`` when the tag never arrived.
+ """
+ call_id = ctx.tool_call_id
+ if not state.wait_for(
+ lambda: call_id in round_of, timeout=budget.remaining_seconds()
+ ):
+ return None, False
+ model_call_id = round_of[call_id]
+ if model_call_id != current_round["id"]:
+ pool.begin_round()
+ current_round["id"] = model_call_id
+ current_round["pick_phase"] = pool.pick_phase
+ return current_round["pick_phase"], True
+ return current_round["pick_phase"], False
+
+ def _append_step(**fields: Any) -> None:
+ steps.append(AgentStep(step_index=len(steps), **fields))
+
+ def _reject(tool_name: str, args: dict[str, Any], message: str) -> None:
+ _append_step(
+ tool_name=tool_name,
+ tool_args=args,
+ observation_text=message,
+ error=message,
+ elapsed_ms=0,
+ round_index=pool.round_index,
+ )
+
def _dispatch_sync(
- tool_name: str, args: dict[str, Any]
+ tool_name: str, args: dict[str, Any], ctx: Any
) -> str | list[dict[str, Any]]:
- with budget_lock:
- if budget.steps_used >= budget.max_steps:
- steps.append(
- AgentStep(
- step_index=len(steps),
+ with state:
+ pick_round, new_round = _enter_round(ctx)
+ round_index = pool.round_index
+ if pick_round is None:
+ _reject(tool_name, args, _ROUND_TAG_MISSING)
+ return f"error: {_ROUND_TAG_MISSING}"
+ if pick_round:
+ _reject(tool_name, args, _PICK_PHASE_REJECTION)
+ return _PICK_PHASE_REJECTION
+ if new_round:
+ if budget.steps_used >= budget.max_steps:
+ observation = (
+ _BUDGET_EXHAUSTED_MESSAGE + "\n" + _state_tail(pool, budget)
+ )
+ _append_step(
tool_name=tool_name,
tool_args=args,
- observation_text=_BUDGET_EXHAUSTED_MESSAGE,
+ observation_text=observation,
error="budget_max_steps",
elapsed_ms=0,
- tokens_used_delta=0,
- tokens_used_total=budget.tokens_used,
+ round_index=round_index,
)
- )
- return _BUDGET_EXHAUSTED_MESSAGE
- budget.record_step()
+ return observation
+ budget.record_step()
+ readable = pool.readable()
+ decided = pool.decided()
tool_started = time.perf_counter()
future = asyncio.run_coroutine_threadsafe(
dispatch_tool_call(
@@ -203,6 +241,8 @@ def _dispatch_sync(
document_scope=document_scope,
budget=tool_budget,
query=query,
+ readable=readable,
+ decided=decided,
),
loop,
)
@@ -216,29 +256,28 @@ def _dispatch_sync(
tool_name=tool_name,
max_chars=tool_budget.max_chars,
)
- # Appended per call, unlike openai_harness.py's once-per-turn
- # placement — this harness has no batched-turn concept exposed to
- # the host process (see module docstring): each corpus.* dispatch
- # is the only per-step hook available to surface budget state.
- content_with_budget = content + "\n" + budget_status_line(budget)
- observation = cursor_execute_content(
- tool_result, text=content_with_budget
- )
- steps.append(
- AgentStep(
- step_index=len(steps),
+ with state:
+ candidates = pool.issue(tool_name, tool_result)
+ tail = _state_tail(pool, budget)
+ text = content
+ if candidates:
+ text = (
+ f"{content}\n{pool.render_candidates(candidates)}\n"
+ f"{_PICK_PHASE_INSTRUCTION}"
+ )
+ text = text + "\n\n" + tail
+ observation = cursor_execute_content(tool_result, text=text)
+ with state:
+ _append_step(
tool_name=tool_name,
tool_args=args,
- observation_text=content_with_budget,
+ observation_text=text,
error=tool_result.error,
elapsed_ms=elapsed_ms,
- tokens_used_delta=0,
- tokens_used_total=budget.tokens_used,
+ round_index=round_index,
ref_status=read_ref_status(tool_name, tool_result),
+ candidates=[item.handle for item in candidates] or None,
)
- )
- if tool_name in EVIDENCE_TOOL_NAMES and not tool_result.error:
- trajectory_refs.extend(tool_result.refs)
return observation
custom_tools: dict[str, Any] = {}
@@ -247,9 +286,9 @@ def _dispatch_sync(
def _make_execute(resolved_name: str):
def execute(
- args: dict[str, Any], _ctx: Any
+ args: dict[str, Any], ctx: Any
) -> str | list[dict[str, Any]]:
- return _dispatch_sync(resolved_name, dict(args or {}))
+ return _dispatch_sync(resolved_name, dict(args or {}), ctx)
return execute
@@ -259,45 +298,65 @@ def execute(
input_schema=spec.json_schema,
)
- def finish_execute(args: dict[str, Any], _ctx: Any) -> str:
+ def pick_execute(args: dict[str, Any], ctx: Any) -> str:
args = dict(args or {})
- validation_error = validate_finish_args(args)
- if validation_error is not None:
- with budget_lock:
- steps.append(
- AgentStep(
- step_index=len(steps),
- tool_name=FINISH_TOOL_NAME,
- tool_args=args,
- observation_text=validation_error,
- error=validation_error,
- elapsed_ms=0,
- tokens_used_delta=0,
- tokens_used_total=budget.tokens_used,
- )
- )
- return json.dumps(
- {"status": "error", "error": invalid_finish_message(validation_error)}
+ with state:
+ pick_round, _new_round = _enter_round(ctx)
+ if pick_round is None:
+ _reject(PICK_TOOL_NAME, args, _ROUND_TAG_MISSING)
+ return f"error: {_ROUND_TAG_MISSING}"
+ validation_error = validate_pick_args(args)
+ if validation_error is not None:
+ message = invalid_pick_message(validation_error)
+ _reject(PICK_TOOL_NAME, args, message)
+ return f"error: {message}"
+ outcome = pool.apply_pick(list(args["pick"]))
+ observation = render_pick_outcome(outcome)
+ _append_step(
+ tool_name=PICK_TOOL_NAME,
+ tool_args=args,
+ observation_text=observation,
+ error=None,
+ elapsed_ms=0,
+ round_index=pool.round_index,
+ picked=outcome.added,
+ pick_rejected=outcome.rejected,
)
- selected = finish_refs_from_args(args)
- cited = selected if selected is not None else []
- notes = str(args.get("notes") or "")
- with budget_lock:
- finish_state["refs"] = selected
- finish_state["notes"] = notes
- steps.append(
- AgentStep(
- step_index=len(steps),
- tool_name=FINISH_TOOL_NAME,
- tool_args=args,
- observation_text=f"refs={len(cited)} notes={notes!r}",
- error=None,
- elapsed_ms=0,
- tokens_used_delta=0,
- tokens_used_total=budget.tokens_used,
+ return observation + "\n\n" + _state_tail(pool, budget)
+
+ custom_tools[wire_safe_tool_name(PICK_TOOL_NAME)] = cursor_sdk.CustomTool(
+ execute=pick_execute,
+ description=PICK_TOOL_DESCRIPTION,
+ input_schema=PICK_TOOL_SCHEMA,
+ )
+
+ def finish_execute(args: dict[str, Any], ctx: Any) -> str:
+ args = dict(args or {})
+ with state:
+ pick_round, _new_round = _enter_round(ctx)
+ if pick_round is None or pick_round:
+ message = _ROUND_TAG_MISSING if pick_round is None else _PICK_PHASE_REJECTION
+ _reject(FINISH_TOOL_NAME, args, message)
+ return json.dumps({"status": "error", "error": message})
+ validation_error = validate_finish_args(args)
+ if validation_error is not None:
+ _reject(FINISH_TOOL_NAME, args, validation_error)
+ return json.dumps(
+ {
+ "status": "error",
+ "error": invalid_finish_message(validation_error),
+ }
)
+ notes = str(args.get("notes") or "")
+ _append_step(
+ tool_name=FINISH_TOOL_NAME,
+ tool_args=args,
+ observation_text=f"pool={len(pool.entries)} notes={notes!r}",
+ error=None,
+ elapsed_ms=0,
+ round_index=pool.round_index,
)
- return json.dumps({"status": "finished", "refs": len(cited)})
+ return json.dumps({"status": "finished", "pool": len(pool.entries)})
custom_tools[FINISH_TOOL_NAME] = cursor_sdk.CustomTool(
execute=finish_execute,
@@ -305,13 +364,7 @@ def finish_execute(args: dict[str, Any], _ctx: Any) -> str:
input_schema=FINISH_TOOL_SCHEMA,
)
- system_prompt = load_corpus_schema_text() + LOOP_CONTRACT_SUFFIX
- user_prompt = (
- f"{system_prompt}\n\n---\n\nUser query:\n{query}\n\n"
- "Tool names on the wire use underscores "
- f"({', '.join(sorted(custom_tools))}). Explore with those tools, "
- "then call finish with cited refs."
- )
+ user_prompt = f"{AGENT_SYSTEM_PROMPT}\n\n---\n\nUser query:\n{query}"
result: Any = None
async with await cursor_sdk.AsyncClient.launch_bridge(
@@ -327,7 +380,9 @@ def finish_execute(args: dict[str, Any], _ctx: Any) -> str:
),
)
) as agent:
- run = await agent.send(user_prompt)
+ run = await agent.send(
+ user_prompt, cursor_sdk.SendOptions(on_delta=_on_delta)
+ )
try:
result = await asyncio.wait_for(
run.wait(), timeout=budget.wall_clock_seconds
@@ -346,18 +401,11 @@ def finish_execute(args: dict[str, Any], _ctx: Any) -> str:
result_usage_total_tokens = result.usage.total_tokens
budget.record_usage({"total_tokens": result_usage_total_tokens})
- selection = select_episode_refs(
- finish_state["refs"],
- trajectory_refs,
- str(finish_state["notes"] or ""),
- )
return EpisodeResult(
- refs=selection.refs,
- notes=selection.notes,
+ pool=list(pool.entries),
steps=steps,
stop_reason=stop_reason,
tokens_used=budget.tokens_used,
model_name=self._model,
- agent_selected_refs=selection.agent_selected_refs,
- fallback_refs=selection.fallback_refs,
+ queried_tables=dict(pool.queried_tables()),
)
diff --git a/packages/shared-python/shared/services/retrieval/agent_explore/harness/openai_harness.py b/packages/shared-python/shared/services/retrieval/agent_explore/harness/openai_harness.py
index 1d84fdabd..1db56ac54 100644
--- a/packages/shared-python/shared/services/retrieval/agent_explore/harness/openai_harness.py
+++ b/packages/shared-python/shared/services/retrieval/agent_explore/harness/openai_harness.py
@@ -7,45 +7,19 @@
(2026-09-08) against ``deepseek-v4-flash`` via this codebase's client:
single tool call, parallel tool calls in one turn, tool-result feedback +
final synthesis, and forced ``tool_choice`` (used for the budget-exhaustion
-cutoff below) all work.
+cutoff and the pick phase below) all work.
+
+Each turn is one round and sends only a system message plus one rebuilt
+user message (query, one-line call trace, latest-turn results with pick ids,
+evidence pool, steps). Native tool-call history is not kept.
+
+A turn after a successful read or outline is a pick phase: only
+``corpus_pick`` is offered and forced, and the turn does not count as a
+step. Tokens are only summed for the episode total.
Tool calls within one turn are dispatched sequentially through
-``dispatch.dispatch_tool_call`` (fresh DB session per call — safe for any
-harness, not just this one), not via ``asyncio.gather``: batching several
-tool calls into one LLM turn already removes the LLM round-trip per tool
-(the dominant cost); true DB-level concurrency within a turn is not
-implemented here since this provider's tool calls are handled one at a time
-by design, not because concurrent dispatch would be unsafe (it no longer is
-— see ``dispatch.py``).
-
-No import from archived map-nav modules.
-
-Two Phase 4 fixes (audited live against the eval fixture in
-``apps/worker/scripts/fixtures/changheba_archive_eval_queries.json``), both
-now shared with any other harness via ``shared.py`` except stale-message
-collapsing (fix 1), which stays here — it mutates this harness's own
-``messages: list[dict]`` history, a mechanism the Cursor SDK harness has no
-equivalent hook for:
-
-1. **Stale discovery-message collapsing** (``_TOOL_MESSAGE_FRESH_TURNS``,
- ``_collapse_stale_tool_messages``): ``messages`` only ever appended, so a
- single ``corpus.outline``/``corpus.node_filter`` call (each capped at
- ``ToolBudget.max_chars`` — currently ``EVIDENCE_TEXT_CHAR_BUDGET=12_000``,
- see ``registry.py``) was resent in full on every later turn. Verified
- live: two independent queries (q04, q06 in the eval fixture) hit
- ``RETRIEVAL_NAV_TOKEN_LIMIT`` (100k default) within 7-8 LLM turns from
- this resend alone, not from query difficulty — per-turn token cost grew
- monotonically (q04: 4.4k -> 4.8k -> 19.8k -> 21.5k -> 24.2k -> 29.6k).
- Successful evidence reads remain visible until finish. Removing them after
- two turns caused a real SpaceX query to alternate between complementary
- sections until its token budget ran out. Per-result text caps and the
- episode budget still apply.
-2. **Trajectory refs fallback** (``shared.select_episode_refs``): verified
- live that ``finish`` can be called with no ``refs`` key at all (raw
- ``function.arguments`` was literally ``'{}'``) even after the model had
- already read clearly relevant sections via ``corpus.read``. Omitted refs
- (``None``) still fall back to ``corpus.read``/``corpus.assets`` trajectory
- refs. An explicit ``refs: []`` is respected and does not fall back.
+``dispatch.dispatch_tool_call`` (fresh DB session per call). No import from
+archived map-nav modules.
"""
from __future__ import annotations
@@ -64,38 +38,38 @@
FINISH_TOOL_DESCRIPTION,
FINISH_TOOL_NAME,
FINISH_TOOL_SCHEMA,
- LOOP_CONTRACT_SUFFIX,
+ PICK_TOOL_DESCRIPTION,
+ PICK_TOOL_NAME,
+ PICK_TOOL_SCHEMA,
)
from shared.services.retrieval.agent_explore.dispatch import DbFactory, dispatch_tool_call
+from shared.services.retrieval.agent_explore.evidence_pool import (
+ EvidencePool,
+ render_budget,
+ render_pick_outcome,
+ render_trace_line,
+ trace_status,
+)
+from shared.services.retrieval.agent_explore.prompt import AGENT_SYSTEM_PROMPT
from shared.services.retrieval.agent_explore.shared import (
- EVIDENCE_TOOL_NAMES,
- budget_status_line,
build_wire_tool_name_map,
- finish_refs_from_args,
- https_image_parts,
invalid_finish_message,
- model_accepts_images,
+ invalid_pick_message,
read_ref_status,
- select_episode_refs,
tool_message_content,
validate_finish_args,
+ validate_pick_args,
wire_safe_tool_name,
)
from shared.services.retrieval.agent_explore.types import AgentStep, EpisodeResult
-from shared.services.retrieval.agent_tools import (
- REGISTRY,
- ToolBudget,
- ToolResult,
- load_corpus_schema_text,
-)
+from shared.services.retrieval.agent_tools import REGISTRY, ToolBudget, ToolResult
+
+_PICK_WIRE_NAME = wire_safe_tool_name(PICK_TOOL_NAME)
-# A discovery or failed tool message is kept in full for the turn it was produced plus this
-# many additional turns, then collapsed to a placeholder — see module
-# docstring point 1. Not tuned against a real recall-vs-token tradeoff yet;
-# 2 was chosen so a result stays fully visible for one full turn after the
-# one it was produced in (enough for the model to act on it immediately),
-# revisit with more Phase 4 data.
-_TOOL_MESSAGE_FRESH_TURNS = 2
+_PICK_PHASE_INSTRUCTION = (
+ "Pick phase: you can only call corpus_pick now. Pick the ids worth "
+ "keeping, or pass an empty list."
+)
def _resolve_client_and_model() -> tuple[Any, str]:
@@ -141,6 +115,17 @@ def _build_openai_tools() -> tuple[list[dict[str, Any]], dict[str, str]]:
return tools, name_map
+def _build_pick_tool() -> dict[str, Any]:
+ return {
+ "type": "function",
+ "function": {
+ "name": _PICK_WIRE_NAME,
+ "description": PICK_TOOL_DESCRIPTION,
+ "parameters": PICK_TOOL_SCHEMA,
+ },
+ }
+
+
def _parse_tool_arguments(raw: str | None) -> tuple[dict[str, Any], str | None]:
"""Parse one tool call's JSON arguments, or return the parse error.
@@ -160,31 +145,27 @@ def _parse_tool_arguments(raw: str | None) -> tuple[dict[str, Any], str | None]:
return parsed, None
-def _collapse_stale_tool_messages(
- messages: list[dict[str, Any]],
- tool_message_log: list[dict[str, Any]],
+def _compose_user_content(
*,
- current_turn: int,
- fresh_turns: int,
-) -> None:
- """Replace stale discovery/error messages while preserving read evidence.
-
- ``messages`` only ever grows within one episode (see module docstring
- point 1); this is what keeps that growth bounded instead of resending
- every past discovery result on every later turn. Successful evidence must
- remain visible so complementary reads can be synthesized without rereading.
- """
- for entry in tool_message_log:
- if entry["collapsed"] or entry.get("has_evidence", False):
- continue
- if current_turn - entry["turn_index"] < fresh_turns:
- continue
- messages[entry["message_index"]]["content"] = (
- f"[collapsed: {entry['tool_name']} result from turn "
- f"{entry['turn_index']} was {entry['original_chars']} chars — "
- "call the tool again if you need it back in view]"
+ query: str,
+ trace_lines: list[str],
+ latest_results: list[str],
+ latest_turn: int,
+ pool: EvidencePool,
+ budget: EpisodeBudget,
+ instruction: str,
+) -> str:
+ parts = [f"User query: {query}"]
+ if trace_lines:
+ parts.append("trace:\n" + "\n".join(f" {line}" for line in trace_lines))
+ if latest_results:
+ parts.append(
+ f"latest results (turn {latest_turn}):\n" + "\n\n".join(latest_results)
)
- entry["collapsed"] = True
+ parts.append(pool.render_pool())
+ parts.append(render_budget(budget))
+ parts.append(instruction)
+ return "\n\n".join(part for part in parts if part)
class OpenAIHarness:
@@ -203,38 +184,44 @@ async def run_episode(
tool_budget = ToolBudget()
client, model = _resolve_client_and_model()
openai_tools, tool_name_map = _build_openai_tools()
-
- system_prompt = load_corpus_schema_text() + LOOP_CONTRACT_SUFFIX
- messages: list[dict[str, Any]] = [
- {"role": "system", "content": system_prompt},
- {"role": "user", "content": query},
- ]
-
+ pick_tool = _build_pick_tool()
+ pool = EvidencePool()
+ trace_lines: list[str] = []
+ latest_results: list[str] = []
+ latest_turn = 0
steps: list[AgentStep] = []
- finish_refs: list[dict[str, Any]] | None = None
result_notes = ""
- # Refs from every corpus.read/corpus.assets/corpus.query_table call this episode, in call
- # order — the fallback source when finish's own refs end up empty (see
- # module docstring point 2).
- trajectory_refs: list[dict[str, Any]] = []
- # One entry per appended tool-role message: {message_index, turn_index,
- # tool_name, original_chars, has_evidence, collapsed} — see _collapse_stale_tool_messages.
- tool_message_log: list[dict[str, Any]] = []
turn_index = 0
+ stop_reason = "finished"
while True:
turn_index += 1
- _collapse_stale_tool_messages(
- messages,
- tool_message_log,
- current_turn=turn_index,
- fresh_turns=_TOOL_MESSAGE_FRESH_TURNS,
- )
-
- forced_reason = budget.exhausted()
- tool_choice: Any = "auto"
- if forced_reason is not None:
- tool_choice = {"type": "function", "function": {"name": FINISH_TOOL_NAME}}
+ pool.begin_round()
+ pick_turn = pool.pick_phase
+ forced_reason = None if pick_turn else budget.exhausted()
+ if pick_turn:
+ tools = [pick_tool]
+ tool_choice: Any = {"type": "function", "function": {"name": _PICK_WIRE_NAME}}
+ else:
+ tools = openai_tools
+ tool_choice = "auto"
+ if forced_reason is not None:
+ tool_choice = {"type": "function", "function": {"name": FINISH_TOOL_NAME}}
+ messages = [
+ {"role": "system", "content": AGENT_SYSTEM_PROMPT},
+ {
+ "role": "user",
+ "content": _compose_user_content(
+ query=query,
+ trace_lines=trace_lines,
+ latest_results=latest_results,
+ latest_turn=latest_turn,
+ pool=pool,
+ budget=budget,
+ instruction=_PICK_PHASE_INSTRUCTION if pick_turn else "",
+ ),
+ },
+ ]
turn_started = time.perf_counter()
response, usage = await asyncio.to_thread(
@@ -243,13 +230,13 @@ async def run_episode(
model=model,
temperature=0.0,
max_tokens=AGENT_EXPLORE_MAX_COMPLETION_TOKENS,
- tools=openai_tools,
+ tools=tools,
tool_choice=tool_choice,
)
budget.record_usage(usage)
- budget.record_step()
+ if not pick_turn:
+ budget.record_step()
turn_elapsed_ms = int((time.perf_counter() - turn_started) * 1000)
- turn_tokens = int((usage or {}).get("total_tokens", 0) or 0)
message = response.choices[0].message
tool_calls = list(message.tool_calls or [])
@@ -265,47 +252,102 @@ async def run_episode(
observation_text=result_notes,
error=None,
elapsed_ms=turn_elapsed_ms,
- tokens_used_delta=turn_tokens,
- tokens_used_total=budget.tokens_used,
+ round_index=pool.round_index,
)
)
break
- finish_call = next(
- (tc for tc in tool_calls if tc.function.name == FINISH_TOOL_NAME), None
+ if pick_turn:
+ for call_index, tool_call in enumerate(tool_calls):
+ args, parse_error = _parse_tool_arguments(tool_call.function.arguments)
+ pick_error = parse_error or validate_pick_args(args)
+ if pick_error is not None:
+ message = invalid_pick_message(pick_error)
+ trace_lines.append(
+ render_trace_line(
+ len(trace_lines) + 1,
+ _PICK_WIRE_NAME,
+ args,
+ trace_status(ToolResult(text="", error=message)),
+ )
+ )
+ steps.append(
+ AgentStep(
+ step_index=len(steps),
+ tool_name=PICK_TOOL_NAME,
+ tool_args=args,
+ observation_text=message,
+ error=message,
+ elapsed_ms=turn_elapsed_ms if call_index == 0 else 0,
+ round_index=pool.round_index,
+ )
+ )
+ continue
+ outcome = pool.apply_pick(list(args["pick"]))
+ observation = render_pick_outcome(outcome)
+ trace_lines.append(
+ render_trace_line(
+ len(trace_lines) + 1, _PICK_WIRE_NAME, args, observation
+ )
+ )
+ steps.append(
+ AgentStep(
+ step_index=len(steps),
+ tool_name=PICK_TOOL_NAME,
+ tool_args=args,
+ observation_text=observation,
+ error=None,
+ elapsed_ms=turn_elapsed_ms if call_index == 0 else 0,
+ round_index=pool.round_index,
+ picked=outcome.added,
+ pick_rejected=outcome.rejected,
+ )
+ )
+ continue
+
+ parsed_calls: list[tuple[str, dict[str, Any], str | None]] = [
+ (
+ str(tool_call.function.name or ""),
+ *_parse_tool_arguments(tool_call.function.arguments),
+ )
+ for tool_call in tool_calls
+ ]
+
+ finish_entry = next(
+ (item for item in parsed_calls if item[0] == FINISH_TOOL_NAME),
+ None,
)
finish_error: str | None = None
- if finish_call is not None:
- args, parse_error = _parse_tool_arguments(finish_call.function.arguments)
+ finish_args: dict[str, Any] = {}
+ finish_parse_error: str | None = None
+ if finish_entry is not None:
+ _name, finish_args, finish_parse_error = finish_entry
+ parse_error = finish_parse_error
if parse_error is None:
- parse_error = validate_finish_args(args)
+ parse_error = validate_finish_args(finish_args)
if parse_error is not None and forced_reason is None:
finish_error = parse_error
- if finish_call is not None and finish_error is None:
- finish_refs = finish_refs_from_args(args) if parse_error is None else None
- cited = finish_refs if finish_refs is not None else []
+ if finish_entry is not None and finish_error is None:
result_notes = (
- parse_error if parse_error is not None else str(args.get("notes") or "")
+ finish_parse_error
+ if finish_parse_error is not None
+ else str(finish_args.get("notes") or "")
)
stop_reason = f"budget_{forced_reason}" if forced_reason else "finished"
steps.append(
AgentStep(
step_index=len(steps),
tool_name=FINISH_TOOL_NAME,
- tool_args=args,
- observation_text=f"refs={len(cited)} notes={result_notes!r}",
- error=parse_error,
+ tool_args=finish_args,
+ observation_text=f"pool={len(pool.entries)} notes={result_notes!r}",
+ error=finish_parse_error,
elapsed_ms=turn_elapsed_ms,
- tokens_used_delta=turn_tokens,
- tokens_used_total=budget.tokens_used,
+ round_index=pool.round_index,
)
)
break
if forced_reason is not None:
- # Forced tool_choice=finish but the provider returned a
- # different tool anyway (not observed in verification, but a
- # budget cutoff must never loop past). Stop here regardless.
stop_reason = f"budget_{forced_reason}"
result_notes = str(message.content or "") or (
"budget exhausted; provider did not return finish"
@@ -318,131 +360,85 @@ async def run_episode(
observation_text=result_notes,
error="forced_finish_not_honored",
elapsed_ms=turn_elapsed_ms,
- tokens_used_delta=turn_tokens,
- tokens_used_total=budget.tokens_used,
+ round_index=pool.round_index,
)
)
break
- messages.append(
- {
- "role": "assistant",
- "content": message.content or "",
- "tool_calls": [
- {
- "id": tc.id,
- "type": "function",
- "function": {
- "name": tc.function.name,
- "arguments": tc.function.arguments,
- },
- }
- for tc in tool_calls
- ],
- }
- )
- first_tool_tokens_recorded = False
- for tc in tool_calls:
+ readable = pool.readable()
+ decided = pool.decided()
+ first_step_recorded = False
+ turn_results: list[str] = []
+ for requested_name, call_args, parse_error in parsed_calls:
tool_started = time.perf_counter()
- args, parse_error = _parse_tool_arguments(tc.function.arguments)
- requested_name = str(tc.function.name or "")
canonical_name = tool_name_map.get(requested_name, requested_name)
- if tc is finish_call:
+ if requested_name == FINISH_TOOL_NAME:
tool_result = ToolResult(
text="", error=invalid_finish_message(str(finish_error))
)
+ trace_result = ToolResult(text="", error=str(finish_error))
elif parse_error is not None:
tool_result = ToolResult(text="", error=parse_error)
+ trace_result = tool_result
else:
tool_result = await dispatch_tool_call(
canonical_name,
- args,
+ call_args,
db_factory=db_factory,
user_id=user_id,
namespace=namespace,
document_scope=document_scope,
budget=tool_budget,
query=query,
+ readable=readable,
+ decided=decided,
)
+ trace_result = tool_result
tool_elapsed_ms = int((time.perf_counter() - tool_started) * 1000)
content = tool_message_content(
tool_result,
tool_name=canonical_name,
max_chars=tool_budget.max_chars,
)
- messages.append(
- {"role": "tool", "tool_call_id": tc.id, "content": content}
- )
- tool_message_index = len(messages) - 1
- if model_accepts_images(model):
- image_parts = https_image_parts(tool_result)
- if image_parts:
- messages.append(
- {"role": "user", "content": image_parts}
- )
- tool_message_log.append(
- {
- "message_index": tool_message_index,
- "turn_index": turn_index,
- "tool_name": canonical_name,
- "original_chars": len(content),
- "has_evidence": (
- canonical_name in EVIDENCE_TOOL_NAMES
- and not tool_result.error
- and bool(tool_result.refs)
- ),
- "collapsed": False,
- }
+ candidates = pool.issue(canonical_name, tool_result)
+ if candidates:
+ content = f"{content}\n{pool.render_candidates(candidates)}"
+ turn_results.append(f"{requested_name}:\n{content}")
+ trace_lines.append(
+ render_trace_line(
+ len(trace_lines) + 1,
+ requested_name,
+ call_args,
+ trace_status(trace_result),
+ )
)
- if canonical_name in EVIDENCE_TOOL_NAMES and not tool_result.error:
- trajectory_refs.extend(tool_result.refs)
- # Turn-level token usage is attributed to the first tool step in
- # this turn (the completion that decided all calls in it); the
- # rest are 0 to avoid double-counting the same LLM usage.
steps.append(
AgentStep(
step_index=len(steps),
tool_name=canonical_name,
- tool_args=args,
+ tool_args=call_args,
observation_text=content,
error=tool_result.error,
elapsed_ms=(
tool_elapsed_ms
- if first_tool_tokens_recorded
+ if first_step_recorded
else turn_elapsed_ms + tool_elapsed_ms
),
- tokens_used_delta=0 if first_tool_tokens_recorded else turn_tokens,
- tokens_used_total=budget.tokens_used,
+ round_index=pool.round_index,
ref_status=read_ref_status(canonical_name, tool_result),
+ candidates=[item.handle for item in candidates] or None,
)
)
- first_tool_tokens_recorded = True
+ first_step_recorded = True
- # Appended once per turn, to the last tool message only (not
- # every AgentStep's recorded observation_text above) — the model
- # only needs to see current remaining budget once before its next
- # completion call, not once per parallel tool call in this turn.
- last_tool = next(
- (
- message
- for message in reversed(messages)
- if message.get("role") == "tool"
- ),
- None,
- )
- if last_tool is not None:
- last_tool["content"] = (
- str(last_tool["content"]) + "\n" + budget_status_line(budget)
- )
+ latest_results = turn_results
+ latest_turn = turn_index
- selection = select_episode_refs(finish_refs, trajectory_refs, result_notes)
return EpisodeResult(
- refs=selection.refs,
- notes=selection.notes,
+ pool=list(pool.entries),
steps=steps,
stop_reason=stop_reason,
tokens_used=budget.tokens_used,
model_name=model,
- agent_selected_refs=selection.agent_selected_refs,
- fallback_refs=selection.fallback_refs,
+ queried_tables=dict(pool.queried_tables()),
)
diff --git a/packages/shared-python/shared/services/retrieval/agent_explore/prompt.py b/packages/shared-python/shared/services/retrieval/agent_explore/prompt.py
new file mode 100644
index 000000000..c84f6c17b
--- /dev/null
+++ b/packages/shared-python/shared/services/retrieval/agent_explore/prompt.py
@@ -0,0 +1,45 @@
+"""Agent-explore system prompt.
+
+Tool-specific usage stays on each tool's own description. This module only
+holds the shared overview plus the exploration-loop contract.
+"""
+
+from __future__ import annotations
+
+from shared.services.retrieval.agent_tools import load_corpus_overview_text
+
+LOOP_RULES = """\
+## How this exploration works
+
+You collect evidence for one user question; you do not write the answer.
+Each turn, either call tools or call finish.
+
+Reading:
+- corpus.read only accepts addresses (document_id plus section_path or
+ chunk_id) that appeared in results from your earlier turns. On your first
+ turn you have no results yet, so do not call corpus.read.
+- Calls in the same turn cannot use each other's results.
+
+Evidence pool: only what you pick reaches the answer writer.
+- A corpus.read result gives each successfully read ref a pick id (R3.1,
+ R3.2, ...). A corpus.outline result gives the whole outline one pick id (O2).
+ Failed refs get no id. Other tools give no ids: to pick an image or table,
+ read it by chunk_id first.
+- After a turn where corpus.read or corpus.outline succeeds, the next turn is
+ a pick phase: you can only call corpus.pick. Pass the ids worth keeping, or
+ an empty list. Picked ids join the evidence pool.
+- Body text you read but did not pick cannot be read again.
+- Each turn you see: a trace of your past calls (tool, arguments, ok or why
+ it failed), the full results of your latest calls, the evidence pool, and
+ the steps used so far.
+
+Call finish when the pool is enough to answer, or when you are sure the
+corpus has no answer. finish ends the exploration at once.
+
+If a call needs another call's result, wait for that result instead of
+issuing both in the same turn.
+
+Tool names on the wire use "_" instead of "." (corpus_read = corpus.read).
+"""
+
+AGENT_SYSTEM_PROMPT = load_corpus_overview_text() + "\n\n" + LOOP_RULES
diff --git a/packages/shared-python/shared/services/retrieval/agent_explore/ref_resolution.py b/packages/shared-python/shared/services/retrieval/agent_explore/ref_resolution.py
deleted file mode 100644
index d244e41ea..000000000
--- a/packages/shared-python/shared/services/retrieval/agent_explore/ref_resolution.py
+++ /dev/null
@@ -1,154 +0,0 @@
-"""Resolve ``finish.refs`` into the chunk_id-bearing shape ``resolve_workflow_references`` requires.
-
-Verified live: ``resolve_workflow_references`` -> ``hydrate_referenced_chunk_rows``
-drops any ref whose lookup key has an empty ``chunk_id`` (``row_utils.
-build_reference_lookup_key`` + the ``ref_keys = [k for k in ref_keys if k[0]
-and k[1]]`` guard in ``hydration/reference.py``) — a ``{document_id,
-section_path}``-only ref silently resolves to zero ``referenced_chunks``,
-which is exactly the shape ``agent_tools.CORPUS_SCHEMA.md``/``corpus.read``
-teaches the agent to cite (``corpus.read``'s rendered ``text`` — the only
-thing the LLM ever sees — shows ``section_path``, never ``chunk_id``;
-``chunk_id`` only appears in its structured ``payload``/``refs``, which the
-LLM does not see). This module closes that gap at the harness boundary
-instead of changing what the agent is taught to cite: for any ref missing
-``chunk_id``, resolve that section's own body chunk — the same "one section,
-one body chunk" lookup ``corpus.read``'s ``section_path`` branch performs
-(``agent_tools/section_path_lookup.py``), including the same suffix fallback
-when the agent cites a path without ancestor prefixes.
-"""
-
-from __future__ import annotations
-
-from shared.services.retrieval.corpus_revision_context import CorpusRevisionContext
-
-from shared.services.retrieval.corpus_storage import CorpusStorage
-
-from shared.services.retrieval.document_scope import DocumentScope
-
-from dataclasses import dataclass, field
-from typing import Any
-
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from shared.services.retrieval.agent_tools.section_path_lookup import (
- resolve_section_path_anchor,
-)
-
-_BODY_CHUNK_TYPES = ("text", "page")
-
-
-@dataclass
-class FinishRefResolution:
- resolved: list[dict[str, Any]] = field(default_factory=list)
- dropped: list[dict[str, Any]] = field(default_factory=list)
-
-
-async def resolve_finish_refs(
- db: AsyncSession,
- *,
- user_id: str,
- namespace: str,
- refs: list[dict[str, Any]],
- document_scope: DocumentScope = DocumentScope(),
-) -> FinishRefResolution:
- """Return refs with ``chunk_id`` populated; dropped refs keep a reason."""
- corpusStorage: CorpusStorage = CorpusStorage.resolve_namespace(namespace)
- resolution = FinishRefResolution()
- scoped: list[dict[str, Any]] = []
- for ref in refs:
- document_id = str(ref.get("document_id") or "").strip()
- if not document_id:
- resolution.dropped.append({"ref": ref, "reason": "missing document_id"})
- continue
- if not document_scope.allows(document_id):
- resolution.dropped.append(
- {"ref": ref, "reason": f"document_id out of scope: {document_id}"}
- )
- continue
- scoped.append(ref)
-
- document_ids = {
- str(ref.get("document_id") or "").strip() for ref in scoped if ref.get("document_id")
- }
- if not document_ids:
- return resolution
-
- documents = (
- (
- await db.execute(
- select(corpusStorage.Document)
- .where(corpusStorage.Document.document_id.in_(document_ids))
- .where(corpusStorage.Document.user_id == corpusStorage.resolve_owner(user_id))
- .where(corpusStorage.Document.namespace == namespace)
- .where(corpusStorage.Document.status == "active")
- .where(document_scope.predicate(corpusStorage.Document.document_id))
- )
- )
- .scalars()
- .all()
- )
- revision_by_doc = {
- d.document_id: revision for d in documents if (revision := CorpusRevisionContext.resolve_revision(d.document_id, d.current_job_result_id))
- }
-
- for ref in scoped:
- document_id = str(ref.get("document_id") or "").strip()
- chunk_id = str(ref.get("chunk_id") or "").strip()
- if document_id and chunk_id:
- resolution.resolved.append({"document_id": document_id, "chunk_id": chunk_id})
- continue
-
- section_path = str(ref.get("section_path") or "").strip()
- job_result_id = revision_by_doc.get(document_id)
- if not job_result_id:
- resolution.dropped.append(
- {"ref": ref, "reason": f"unknown document_id: {document_id}"}
- )
- continue
- if not section_path:
- resolution.dropped.append(
- {"ref": ref, "reason": f"ref for {document_id} needs section_path or chunk_id"}
- )
- continue
-
- resolved_path, path_error = await resolve_section_path_anchor(
- db,
- document_id=document_id,
- job_result_id=job_result_id,
- section_path=section_path,
- )
- if path_error or not resolved_path:
- resolution.dropped.append(
- {
- "ref": ref,
- "reason": path_error or f"unknown section_path for {document_id}",
- }
- )
- continue
-
- row = (
- await db.execute(
- select(corpusStorage.DocumentChunk.chunk_id)
- .select_from(corpusStorage.DocumentChunk)
- .join(
- corpusStorage.DocumentSection,
- corpusStorage.DocumentSection.section_id == corpusStorage.DocumentChunk.section_id,
- )
- .where(corpusStorage.DocumentChunk.document_id == document_id)
- .where(corpusStorage.DocumentChunk.job_result_id == job_result_id)
- .where(corpusStorage.DocumentSection.section_path == resolved_path)
- .where(corpusStorage.DocumentChunk.chunk_type.in_(_BODY_CHUNK_TYPES))
- )
- ).first()
- if row is None:
- resolution.dropped.append(
- {
- "ref": ref,
- "reason": f"no body chunk for {document_id}: {resolved_path}",
- }
- )
- continue
- resolution.resolved.append({"document_id": document_id, "chunk_id": str(row[0])})
-
- return resolution
diff --git a/packages/shared-python/shared/services/retrieval/agent_explore/shared.py b/packages/shared-python/shared/services/retrieval/agent_explore/shared.py
index 47fbc60ef..0294b5f92 100644
--- a/packages/shared-python/shared/services/retrieval/agent_explore/shared.py
+++ b/packages/shared-python/shared/services/retrieval/agent_explore/shared.py
@@ -5,34 +5,21 @@
and, as a debug-script PoC, had started duplicating and drifting from it
instead of sharing it — see the Phase 3.5 section of
``.cursor/plans/agentic_corpus_explore_retrieval_c2c4ea21.plan.md``.
-
-Deliberately excludes anything that assumes an editable ``messages:
-list[dict]`` conversation history (that's OpenAI-harness-specific — see
-``harness/openai_harness.py``'s ``_collapse_stale_tool_messages``, which is
-NOT here because the Cursor SDK manages its own context with no equivalent
-hook exposed to the host process).
"""
from __future__ import annotations
-from dataclasses import dataclass
from typing import Any
import jsonschema
import jsonschema.validators
-from shared.services.retrieval.agent_explore.budget import EpisodeBudget
-from shared.services.retrieval.agent_explore.config import FINISH_TOOL_SCHEMA
-from shared.services.retrieval.agent_tools import ToolResult
-
-# Tools whose ToolResult.refs point at evidence the agent has actually looked
-# at (full body content), as opposed to candidate/listing refs from
-# list_documents/outline/node_filter/recall/grep — those describe *where
-# things are*, not *what was read*, and would inject unread noise into the
-# trajectory-refs fallback below if included.
-EVIDENCE_TOOL_NAMES = frozenset(
- {"corpus.read", "corpus.assets", "corpus.query_table"}
+from shared.services.retrieval.agent_explore.config import (
+ FINISH_TOOL_SCHEMA,
+ PICK_TOOL_NAME,
+ PICK_TOOL_SCHEMA,
)
+from shared.services.retrieval.agent_tools import ToolResult
# The two map-narrowing tools bound their own text at MAP_TOOL_CHAR_BUDGET by
# folding whole subtrees (agent_tools.map_render) or failing the call, so
@@ -112,6 +99,7 @@ def tool_message_content(result: ToolResult, *, tool_name: str, max_chars: int)
if tool_name in MAP_TOOL_NAMES or len(text) <= max_chars:
return text
omitted = len(text) - max_chars
+ # TODO: return a fragment for oversized corpus.read bodies, the way oversized tables do, instead of this head cut.
return (
text[:max_chars]
+ f"\n...[truncated, {omitted} more chars — narrow the scope "
@@ -119,54 +107,6 @@ def tool_message_content(result: ToolResult, *, tool_name: str, max_chars: int)
)
-@dataclass(frozen=True)
-class EpisodeRefSelection:
- """Final episode refs plus how they were chosen.
-
- ``agent_selected_refs`` is ``None`` only when finish was never called.
- An explicit empty finish stays empty and does not take the trajectory
- fallback.
- """
-
- refs: list[dict[str, Any]]
- notes: str
- agent_selected_refs: list[dict[str, Any]] | None
- fallback_refs: list[dict[str, Any]]
-
-
-def select_episode_refs(
- finish_refs: list[dict[str, Any]] | None,
- trajectory_refs: list[dict[str, Any]],
- notes: str,
-) -> EpisodeRefSelection:
- """Choose episode refs without treating ``[]`` and ``None`` as the same."""
- if finish_refs is None:
- fallback_refs = dedup_refs(trajectory_refs)
- if not fallback_refs:
- return EpisodeRefSelection(
- refs=[],
- notes=notes,
- agent_selected_refs=None,
- fallback_refs=[],
- )
- suffix = (
- "[refs auto-filled from corpus.read/corpus.assets/"
- "corpus.query_table trajectory; finish was not called]"
- )
- return EpisodeRefSelection(
- refs=fallback_refs,
- notes=(notes + " " if notes else "") + suffix,
- agent_selected_refs=None,
- fallback_refs=fallback_refs,
- )
- return EpisodeRefSelection(
- refs=list(finish_refs),
- notes=notes,
- agent_selected_refs=list(finish_refs),
- fallback_refs=[],
- )
-
-
def validate_finish_args(args: dict[str, Any]) -> str | None:
"""Validate ``finish``'s own args against ``FINISH_TOOL_SCHEMA``; ``None`` = valid.
@@ -176,10 +116,26 @@ def validate_finish_args(args: dict[str, Any]) -> str | None:
is unverified (see ``config.py``'s ``FINISH_TOOL_SCHEMA`` docstring
context), so this is the real enforcement point.
"""
+ return _schema_args_error("finish", FINISH_TOOL_SCHEMA, args)
+
+
+def validate_pick_args(args: dict[str, Any]) -> str | None:
+ """Validate ``corpus.pick`` args against ``PICK_TOOL_SCHEMA``; ``None`` = valid.
+
+ The Cursor SDK does not enforce ``input_schema`` (a live run sent
+ ``pick_ids``), so a malformed call must fail here instead of being
+ applied as an empty pick that closes the pick phase.
+ """
+ return _schema_args_error(PICK_TOOL_NAME, PICK_TOOL_SCHEMA, args)
+
+
+def _schema_args_error(
+ tool_name: str, schema: dict[str, object], args: dict[str, Any]
+) -> str | None:
if not isinstance(args, dict):
- return f"finish: arguments must be a JSON object, got {type(args).__name__}"
- validator_cls = jsonschema.validators.validator_for(FINISH_TOOL_SCHEMA)
- validator = validator_cls(FINISH_TOOL_SCHEMA)
+ return f"{tool_name}: arguments must be a JSON object, got {type(args).__name__}"
+ validator_cls = jsonschema.validators.validator_for(schema)
+ validator = validator_cls(schema)
errors = sorted(
validator.iter_errors(args), key=lambda error: [str(p) for p in error.path]
)
@@ -190,7 +146,7 @@ def validate_finish_args(args: dict[str, Any]) -> str | None:
if error.validator == "oneOf" and isinstance(error.schema, dict):
message = str(error.schema.get("description") or message)
location = "".join(f"[{p}]" if isinstance(p, int) else f".{p}" for p in error.path)
- return f"finish: invalid arguments{f' at {location}' if location else ''}: {message}"
+ return f"{tool_name}: invalid arguments{f' at {location}' if location else ''}: {message}"
def read_ref_status(tool_name: str, result: ToolResult) -> list[dict[str, Any]] | None:
@@ -205,65 +161,14 @@ def invalid_finish_message(error: str) -> str:
"""Model-facing text for a rejected ``finish`` call; the episode goes on."""
return (
f"{error}. finish was not accepted and the episode continues. Correct "
- 'form: {"refs": [{"document_id": "...", "section_path": "..."} or '
- '{"document_id": "...", "chunk_id": "..."}], "notes": "..."} — each '
- "ref names exactly one of section_path or chunk_id. Call finish again "
+ 'form: {"notes": "..."} — Call finish again '
"with fixed arguments, or keep exploring with the corpus tools."
)
-def finish_refs_from_args(args: dict[str, Any] | None) -> list[dict[str, Any]] | None:
- """Return cited refs, or ``None`` when finish omitted the ``refs`` key.
-
- ``None`` means the agent did not specify refs (never called finish, or
- called finish with ``{}``). An explicit ``refs: []`` stays an empty list
- and must not be collapsed into ``None``.
- """
- if not isinstance(args, dict) or "refs" not in args or args.get("refs") is None:
- return None
- return normalize_finish_refs(args.get("refs"))
-
-
-def normalize_finish_refs(raw: Any) -> list[dict[str, Any]]:
- """Keep only dict items with a non-empty ``document_id`` from a raw ``finish.refs``."""
- if not isinstance(raw, list):
- return []
- normalized: list[dict[str, Any]] = []
- for item in raw:
- if isinstance(item, dict) and str(item.get("document_id") or "").strip():
- normalized.append(item)
- return normalized
-
-
-def budget_status_line(budget: EpisodeBudget) -> str:
- """One-line remaining-budget summary appended to a tool observation.
-
- Neither harness previously surfaced ``EpisodeBudget``'s own counters
- (``steps_used``/``max_steps``, ``tokens_used``/``token_limit``,
- elapsed/wall_clock) to the model at all — it had no way to tell "I'm on
- step 3 of 12" from "I'm on step 11 of 12", so it could not self-regulate
- when to stop exploring and call ``finish``. This exposes the same
- ``EpisodeBudget.snapshot()`` data already used for the hard cutoff,
- reused as a soft signal the model can read every turn.
- """
- snap = budget.snapshot()
+def invalid_pick_message(error: str) -> str:
+ """Model-facing text for a rejected ``corpus.pick`` call; the pick phase goes on."""
return (
- f"[budget: steps {snap['steps_used']}/{snap['max_steps']}, "
- f"tokens {snap['tokens_used']}/{snap['token_limit']}, "
- f"elapsed {snap['elapsed_seconds']:.0f}s/{snap['wall_clock_seconds']:.0f}s]"
+ f"{error}. Nothing was picked and the pick phase continues. Correct "
+ 'form: {"pick": ["Knowhere · Document Agent
-PDF PROFILE 阶段手册
-- 给反复查阅用：PROFILE 主体是协调器固定流水线；真正可自由选用的侦察工具只剩「全文 GREP」； - 「提切分 / 校验 / 裁决」是确定性门控。page_memory 认真做目录，但不进真切分环。 - （已移除无效的 inspect.pages。） -
- -1. 一句话架构
-
- 整体没有「模型随便选工具绕圈」。日常 PROFILE = 固定阶段。真正的多轮环只服务「超大 PDF + chunk 需要真切分」。
-
- 固定流水线（几乎每份 PDF） - ① 扫文字特征 → ② 统计 → ③（可选）找目录 + VLM 抄目录 - → ④ VLM 粗分类（类别 / 图册? / 扫描件?） - → ⑤ 扫资产图表 → 再刷统计 - → ⑥ 按「页数 / 是否图册」决定要不要解剖、要不要切分 - -侦察（可选） - 全文 GREP —— 主要出现在超大切分环 - -门控链（确定性触发） - 提切分 → 校验 → 裁决 → 落盘 - -page_memory：强制倾向做目录；跳过真切分，塞「整本一片」占位。-
2. 三层分类：流程 / 侦察工具 / 门控
-关键分界是「谁决定触发」，不是「里面有没有 LLM」。
-
- 流程 · 协调器写死
- 侦察 · 可选选用
- 门控 · 触发确定性
-
-
-
-
-
-
-
- 流程 模型选不了
-文字探测 · 页种类粗标 · 统计聚合（两次）· VLM 粗分类 · 资产初探 · 目录两步（固定顺序）· 是否进解剖 / 是否开环 · 单片占位 · 组装落盘 · ReAct 调度器本身
-
-
- 侦察工具 仅 GREP
-全文 GREP（原生文字 PDF）。时机来自粗分类「下一步建议」或环里决策。已移除无效的「再看几页」。
-
-
- 门控 挂成工具壳
-提切分 → 校验 → 裁决。成功路径被铁律卡住：不能跳过校验直接成功；结束必须走裁决。
-
-
- 目录两步的特殊身份
-形态上是注册工具，但日常由协调器按死顺序调用（找锚点 → 抄目录），不是模型随手点的侦察工具。
-流程阶段 - 文字探测 → 统计 → 目录? → 粗分类 → 资产 → 再统计 - │ - ▼ -侦察工具（可选，仅超大切分环） - GREP - │ - ▼ -门控链（确定性触发） - 提切分 → 校验 → 裁决 → 落盘-
3. 总流程图
-
-
-
-flowchart TD
- A[PDF 进 PROFILE] --> B[① 全页文字探测]
- B --> C[② 算统计 + 极值页]
- C --> D{要做目录?}
- D -->|page_memory 强制 / chunk 看开关| E[找目录锚点：关键词扫]
- E --> F[VLM 确认 + 扩窗抄目录]
- D -->|关| G[目录跳过]
- F --> H[④ VLM 粗分类]
- G --> H
- H --> I[⑤ 全页资产初探]
- I --> J[再刷统计]
- J --> K{图册?}
- K -->|是| Z[结束：跳过解剖]
- K -->|否| L{页数超限? 约200}
- L -->|否| M[轻量解剖]
- L -->|是| N[完整结构解剖]
- M --> M1{要真切分?}
- M1 -->|page_memory 否| M2[单片占位 → 落盘]
- M1 -->|chunk 是| M3[一次性提切分门控]
- N --> N1{要真切分?}
- N1 -->|page_memory 否| N2[单片占位 → 落盘]
- N1 -->|chunk 是| N3[进入多轮环]
- N3 --> R0[可选侦察: GREP]
- R0 --> R1[门控: 提切分]
- R1 --> R2[门控: 校验]
- R2 --> R3[门控: 裁决]
- R3 --> P[落盘解剖图]
- M2 --> P
- M3 --> P
- N2 --> P
-
- 4. 能力清单与时机
-| 能力 | -分类 | -做什么 | -何时 | -实现性质 | -
|---|---|---|---|---|
| 文字探测 | -流程 | -每页字数、密度、横竖、空白感 | -一进来必跑 | -纯代码 | -
| 页种类粗标 | -流程 | -横版 / 普通等规则标签 | -文字探测后立刻 | -纯代码 | -
| 统计聚合 | -流程 | -均值分位、最短最长页；粗分类靠极值页抽样 | -探测后一次；资产后再刷 | -纯代码 | -
| 找目录锚点 | -流程壳 | -扫「目录 / contents」，滤页眉假命中 | -目录开时固定第一步 | -文本扫描 | -
| 抄目录 | -流程壳 | -确认真目录页，扩窗抽标题树 | -紧接锚点 | -VLM | -
| 粗分类 | -流程 | -语义类别、路由（图册/扫描/幻灯/通用）、页眉页脚带、「下一步建议」 | -粗阶段必跑 | -VLM（规划一步，不是工具） | -
| 资产 / 图表初探 | -流程 | -嵌入图、表、矢量块；用页眉页脚带去噪 | -粗分类之后 | -纯代码几何（不是 VLM 读图） | -
| 全文 GREP | -侦察 | -子串 / 正则搜字 | -超大切分环可选；扫描件不可用 | -纯文本搜 | -
| 提切分方案 | -门控 | -要不要切、刀切在哪 | -见下一节触发规则 | -混合（内部可有 LLM） | -
| 校验 | -门控 | -覆盖是否完整、每片是否超限 | -成功收工前硬门 | -纯代码 | -
| 裁决 | -门控 | -成功 / 中止；唯一出口 | -校验通过后或失败路径 | -控制逻辑 | -
- 你常记得的三块都能对上：统计=流程必调；超长切割=页数超限时的门控链（chunk 才真切）；资产图表初探=粗分类后的流程。
-
- 5. 门控触发规则（按触发，不按是否用 LLM）
-| 门控 | -触发规则 | -
|---|---|
| 提切分 | -- 轻量解剖：协调器必调一次（或 page_memory 直接塞单片占位，连门都不进）。 - 超大环：没方案时下一步默认就是它；非法动作也会被掰回它。 - | -
| 校验 | -- 硬门：想成功收工但还没校验通过 → 执行器强制改成先校验。 - 确定性模式：有方案后下一步固定是校验。 - | -
| 裁决 | -- 唯一出口。校验通过 → 才能成功收工；预算耗尽 / 失败 → 中止。 - 不是「探完再想想要不要结束」。 - | -
确定性模式写死的顺序
-没方案 → 提切分 → 校验 →（过）成功裁决
- └（不过）回退单片再校验
- 有模型时环里表面上还能「选工具」，但成功路径仍被两条铁律卡住：不能跳过校验直接成功；结束必须走裁决。
-6. 三条故事线
- -例 A · 40 页普通报告（page_memory / v2）
-扫字 → 统计 → 关键词找目录 → VLM 抄目录 -→ VLM 粗分类（通用）→ 扫资产 → 再统计 -→ 页数没超 → 轻量解剖 → 不真切分（整本一片） -→ 结束。后面建层级吃的是「目录树」，不吃切分计划。 - -没有 agent 环。GREP 基本不出现。- -
例 B · 500 页法规/招股书，chunk 要喂 MinerU
-前面粗阶段同上（目录看开关） -→ 超限 + 非图册 → 完整结构 -→ 可选侦察：粗分类说「再搜 Chapter」→ GREP -→ 提切分 → 校验 → 裁决 -→ 下游按刀口拆 PDF 分别 MinerU - -这里才有真正的多轮环；但环的骨架仍是门控链。- -
例 C · 图册 / 图纸为主
-扫字 → 统计 →（可选目录）→ VLM 说「这是图册」
-→ 扫资产 → 直接结束，不做解剖 / 切分环
-→ chunk 下游改走图册解析；page_memory 仍走页管线，但不消费切分
- 7. page_memory vs chunk 分叉
-| 维度 | -chunk / MinerU | -page_memory | -
|---|---|---|
| 目录 | -可选（全局开关，常关） | -强制倾向开启；常在粗分类前做完 | -
| 真切分 | -超大时要真实切分计划 | -跳过；单片占位即可 | -
| 多轮环 | -超大 + 非图册时进入 | -即使超大也不进切分环 | -
| 图册 | -跳过解剖；下游走图册解析器 | -PROFILE 可标图册并跳过解剖；解析侧不按图册绕道 | -
| 下游主要吃什么 | -路由类别、切分刀口、可选目录 | -目录层级为主；切分字段基本是占位 | -
| 页数门槛 | -约 200 页为「超大」切分门 | -另有页记忆硬上限；不消费切分计划 | -
8. VLM / GREP / 纯代码对照
-| 步骤 | -类型 | -
|---|---|
| 全页文字特征、横竖版标签、统计极值、资产/表/矢量聚类 | 纯代码 |
| 目录关键词扫全文、全文 GREP | 文本扫描 / GREP |
| 粗分类、目录确认与抽取 | VLM |
| 切分时印刷页→物理页校准（有目录时） | 常为 VLM |
| 按章决定刀口 | 文本 LLM（失败则纯代码回退） |
| 无目录切分、校验、单片占位、阶段编排 | 纯代码 / 固定协调 |
| 环里「下一步选哪个」 | 文本 LLM 决策（仅超大切分路径；成功仍受门控约束） |
9. 注册表备忘（实现对照）
-下面只方便对照代码，日常心智模型请用上面的「流程 / 侦察 / 门控」。
-
- 注册表里现有工具形态：真正自由侦察只剩 GREP；提切分 / 校验 / 裁决是门控；目录两步是流程步骤的工具壳。（inspect.pages 已删除）
-
- | 注册名 | -心智分类 | -谁触发 | -
|---|---|---|
find.toc_anchor_pages | 流程壳 | 协调器固定 |
extract.toc_with_boundaries | 流程壳 | 协调器固定 |
grep.text | 侦察 | 粗分类建议 / 环可选 |
propose.shard_plan | 门控 | 确定性：轻量必调 / 环默认 |
validate.anatomy_map | 门控 | 成功收工前硬门 |
verdict | 门控 | 唯一出口 |
未进注册表、但会跑的流程步骤
--
-
- 文字探测 · 页种类粗标 · 统计聚合 · 资产初探 -
- VLM 粗分类（规划一步） -
- 单片占位 · 组装 / 落盘解剖图 -
- ReAct 执行环本身 -
- 相关代码位置（查阅用）：
- apps/worker/app/services/document_parser/profiling/doc_profiler.py、
- apps/worker/app/services/document_agent/coordinator.py、
- apps/worker/app/services/document_agent/registry.py、
- apps/worker/app/services/document_agent/executor/react_loop.py、
- apps/worker/app/services/document_agent/tools/
-
| sub |
| FULL |
| 30 mg |
| 30 mg |
| 30 mg |
| Revenue |
| Q4 |
| FULL TABLE SHOULD NOT APPEAR |
| Unit |
|---|
| tablet |
| FULL TABLE SHOULD NOT APPEAR |
| Unit |
|---|
| tablet |
| FULL TABLE SHOULD NOT APPEAR |
| Unit |
|---|
| tablet |