@quantbrasil/cli 0.1.0-beta.10 → 0.1.0-beta.12

package/README.md

@@ -76,7 +76,9 @@ quantbrasil holdings var 182 --years 1 --confidence 95
 quantbrasil rankings list
 quantbrasil rankings current --system momentum-90d --top 20
 quantbrasil rankings current --system magic-formula --top 10
+quantbrasil rankings current --system low-risk --top 30
 quantbrasil rankings current --id 123 --top 20
+quantbrasil rankings return --system magic-formula --from 2024-01-18 --to 2026-05-25 --top 20 --rebalance quarterly
 quantbrasil screening universes
 quantbrasil screening indicators
 quantbrasil screening run --system acoes-mais-liquidas --query-file ./screening.json

package/dist/cli/index.d.ts

@@ -1,9 +1,10 @@
 import { Command } from "commander";
 import { type CapabilitiesCommandIO, runCapabilitiesCommand } from "../commands/capabilities.js";
+import { runCointegrationPairCommand } from "../commands/cointegration.js";
 import { runMarketAssetsCommand, runMarketPriceCommand } from "../commands/market.js";
 import { runInitCommand } from "../commands/init.js";
 import { runHoldingCreateCommand, runHoldingBetaCommand, runHoldingGetCommand, runHoldingHistoricalReturnCommand, runHoldingListCommand, runHoldingRenameCommand, runHoldingSetPositionsCommand, runHoldingSetTargetsCommand, runHoldingVarCommand, runWatchlistAddAssetsCommand, runWatchlistCreateCommand, runWatchlistGetCommand, runWatchlistListCommand, runWatchlistRemoveAssetsCommand, runWatchlistRenameCommand } from "../commands/portfolios.js";
-import { runRankingsCurrentCommand, runRankingsListCommand } from "../commands/rankings.js";
+import { runRankingsCurrentCommand, runRankingsListCommand, runRankingsReturnCommand } from "../commands/rankings.js";
 import { runScreeningIndicatorsCommand, runScreeningRunCommand, runScreeningUniversesCommand } from "../commands/screening.js";
 import { runSkillsInstallCommand } from "../commands/skills.js";
 import { runStatusCommand } from "../commands/status.js";
@@ -30,7 +31,8 @@ export { runAssetOverviewCommand } from "../commands/assets.js";
 export { runCapabilitiesCommand, runStatusCommand };
 export { runInitCommand };
 export { runMarketAssetsCommand, runMarketPriceCommand };
-export { runRankingsCurrentCommand, runRankingsListCommand };
+export { runRankingsCurrentCommand, runRankingsListCommand, runRankingsReturnCommand, };
+export { runCointegrationPairCommand };
 export { runScreeningIndicatorsCommand, runScreeningRunCommand, runScreeningUniversesCommand, };
 export { runHoldingBetaCommand, runHoldingCreateCommand, runHoldingGetCommand, runHoldingHistoricalReturnCommand, runHoldingListCommand, runHoldingRenameCommand, runHoldingSetPositionsCommand, runHoldingSetTargetsCommand, runHoldingVarCommand, runWatchlistAddAssetsCommand, runWatchlistCreateCommand, runWatchlistGetCommand, runWatchlistListCommand, runWatchlistRemoveAssetsCommand, runWatchlistRenameCommand, };
 export { runSkillsInstallCommand };

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,OAAO,EACL,KAAK,qBAAqB,EAE1B,sBAAsB,EACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAGL,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,cAAc,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,iCAAiC,EACjC,qBAAqB,EACrB,uBAAuB,EACvB,6BAA6B,EAC7B,2BAA2B,EAC3B,oBAAoB,EACpB,4BAA4B,EAC5B,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,+BAA+B,EAC/B,yBAAyB,EAC1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAGL,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,6BAA6B,EAC7B,sBAAsB,EACtB,4BAA4B,EAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,uBAAuB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,gBAAgB,EAEhB,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAQvE,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,qBAAqB,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAgFzE;AAeD,wBAAsB,GAAG,CACvB,IAAI,WAAe,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAoCD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,CAAC;AAC7D,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,4BAA4B,GAC7B,CAAC;AACF,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,iCAAiC,EACjC,qBAAqB,EACrB,uBAAuB,EACvB,6BAA6B,EAC7B,2BAA2B,EAC3B,oBAAoB,EACpB,4BAA4B,EAC5B,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,+BAA+B,EAC/B,yBAAyB,GAC1B,CAAC;AACF,OAAO,EAAE,uBAAuB,EAAE,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,OAAO,EACL,KAAK,qBAAqB,EAE1B,sBAAsB,EACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAGL,2BAA2B,EAC5B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAGL,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,cAAc,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,iCAAiC,EACjC,qBAAqB,EACrB,uBAAuB,EACvB,6BAA6B,EAC7B,2BAA2B,EAC3B,oBAAoB,EACpB,4BAA4B,EAC5B,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,+BAA+B,EAC/B,yBAAyB,EAC1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAGL,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,6BAA6B,EAC7B,sBAAsB,EACtB,4BAA4B,EAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,uBAAuB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,gBAAgB,EAEhB,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAQvE,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,qBAAqB,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAsFzE;AAeD,wBAAsB,GAAG,CACvB,IAAI,WAAe,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAoCD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,CAAC;AACzD,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,GACzB,CAAC;AACF,OAAO,EAAE,2BAA2B,EAAE,CAAC;AACvC,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,4BAA4B,GAC7B,CAAC;AACF,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,iCAAiC,EACjC,qBAAqB,EACrB,uBAAuB,EACvB,6BAA6B,EAC7B,2BAA2B,EAC3B,oBAAoB,EACpB,4BAA4B,EAC5B,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,+BAA+B,EAC/B,yBAAyB,GAC1B,CAAC;AACF,OAAO,EAAE,uBAAuB,EAAE,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/cli/index.js

@@ -3,10 +3,11 @@ import { Command } from "commander";
 import { registerAssetsCommands, } from "../commands/assets.js";
 import { registerAuthCommands, runAuthWhoamiCommand, } from "../commands/auth.js";
 import { registerCapabilitiesCommand, runCapabilitiesCommand, } from "../commands/capabilities.js";
+import { registerCointegrationCommands, runCointegrationPairCommand, } from "../commands/cointegration.js";
 import { registerMarketCommands, runMarketAssetsCommand, runMarketPriceCommand, } from "../commands/market.js";
 import { registerInitCommand, runInitCommand, } from "../commands/init.js";
 import { registerPortfoliosCommands, runHoldingCreateCommand, runHoldingBetaCommand, runHoldingGetCommand, runHoldingHistoricalReturnCommand, runHoldingListCommand, runHoldingRenameCommand, runHoldingSetPositionsCommand, runHoldingSetTargetsCommand, runHoldingVarCommand, runWatchlistAddAssetsCommand, runWatchlistCreateCommand, runWatchlistGetCommand, runWatchlistListCommand, runWatchlistRemoveAssetsCommand, runWatchlistRenameCommand, } from "../commands/portfolios.js";
-import { registerRankingsCommands, runRankingsCurrentCommand, runRankingsListCommand, } from "../commands/rankings.js";
+import { registerRankingsCommands, runRankingsCurrentCommand, runRankingsListCommand, runRankingsReturnCommand, } from "../commands/rankings.js";
 import { registerScreeningCommands, runScreeningIndicatorsCommand, runScreeningRunCommand, runScreeningUniversesCommand, } from "../commands/screening.js";
 import { registerSkillsCommands, runSkillsInstallCommand, } from "../commands/skills.js";
 import { registerStatusFlag, runStatusCommand, } from "../commands/status.js";
@@ -50,6 +51,11 @@ export function createCliProgram(options = {}) {
         env: options.env,
         fetch: options.fetch,
     };
+    const cointegrationContext = {
+        io: options.io,
+        env: options.env,
+        fetch: options.fetch,
+    };
     const screeningContext = {
         io: options.io,
         env: options.env,
@@ -87,6 +93,7 @@ export function createCliProgram(options = {}) {
     registerMarketCommands(program, marketContext);
     registerPortfoliosCommands(program, portfoliosContext);
     registerRankingsCommands(program, rankingsContext);
+    registerCointegrationCommands(program, cointegrationContext);
     registerScreeningCommands(program, screeningContext);
     registerSkillsCommands(program, skillsContext);
     registerUpdateCommand(program, updateContext);
@@ -155,7 +162,8 @@ export { runAssetOverviewCommand } from "../commands/assets.js";
 export { runCapabilitiesCommand, runStatusCommand };
 export { runInitCommand };
 export { runMarketAssetsCommand, runMarketPriceCommand };
-export { runRankingsCurrentCommand, runRankingsListCommand };
+export { runRankingsCurrentCommand, runRankingsListCommand, runRankingsReturnCommand, };
+export { runCointegrationPairCommand };
 export { runScreeningIndicatorsCommand, runScreeningRunCommand, runScreeningUniversesCommand, };
 export { runHoldingBetaCommand, runHoldingCreateCommand, runHoldingGetCommand, runHoldingHistoricalReturnCommand, runHoldingListCommand, runHoldingRenameCommand, runHoldingSetPositionsCommand, runHoldingSetTargetsCommand, runHoldingVarCommand, runWatchlistAddAssetsCommand, runWatchlistCreateCommand, runWatchlistGetCommand, runWatchlistListCommand, runWatchlistRemoveAssetsCommand, runWatchlistRenameCommand, };
 export { runSkillsInstallCommand };

package/dist/commands/cointegration.d.ts

@@ -0,0 +1,52 @@
+import { Command } from "commander";
+import type { JsonValue } from "../vendor/core/index.js";
+import { type CliInvokeContext } from "../cli/client.js";
+import { type TerminalWriter } from "../cli/terminal.js";
+export interface CointegrationCommandIO {
+    stdout: TerminalWriter;
+}
+export interface CointegrationPairCommandOptions {
+    window?: string;
+    json?: boolean;
+}
+export interface CointegrationZScorePoint {
+    [key: string]: JsonValue;
+    date: string;
+    zscore: number | null;
+}
+export interface CointegrationBetaPoint {
+    [key: string]: JsonValue;
+    date: string;
+    slope: number | null;
+}
+export interface CointegrationPairResponse {
+    [key: string]: JsonValue;
+    ok: boolean;
+    summary_markdown: string;
+    base_asset: string;
+    comparison_asset: string;
+    window: number;
+    beta: number | null;
+    beta_std: number | null;
+    beta_mean: number | null;
+    beta_volatility: number | null;
+    adf: number | null;
+    p_value: number | null;
+    confidence: number | null;
+    halflife: number | null;
+    critical_values: Record<string, number>;
+    zscore_series: CointegrationZScorePoint[];
+    beta_series: CointegrationBetaPoint[];
+}
+export interface CointegrationCommandContext extends CliInvokeContext {
+    io?: CointegrationCommandIO;
+}
+type JsonRecord = {
+    [key: string]: JsonValue;
+};
+export declare function registerCointegrationCommands(program: Command, context?: CointegrationCommandContext): void;
+export declare function runCointegrationPairCommand(baseAsset: string, comparisonAsset: string, options: CointegrationPairCommandOptions, context?: CointegrationCommandContext): Promise<void>;
+export declare function buildCointegrationPairInput(baseAsset: string, comparisonAsset: string, options: CointegrationPairCommandOptions): JsonRecord;
+export declare function formatCointegrationPairHuman(data: CointegrationPairResponse, theme?: import("../cli/terminal.js").TerminalTheme): string;
+export {};
+//# sourceMappingURL=cointegration.d.ts.map

package/dist/commands/cointegration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cointegration.d.ts","sourceRoot":"","sources":["../../src/commands/cointegration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE9E,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,+BAA+B;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,yBAAyB;IACxC,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,aAAa,EAAE,wBAAwB,EAAE,CAAC;IAC1C,WAAW,EAAE,sBAAsB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,2BAA4B,SAAQ,gBAAgB;IACnE,EAAE,CAAC,EAAE,sBAAsB,CAAC;CAC7B;AAED,KAAK,UAAU,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE/C,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,2BAAgC,GACxC,IAAI,CA6BN;AAED,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,+BAA+B,EACxC,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,+BAA+B,GACvC,UAAU,CAkBZ;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,yBAAyB,EAC/B,KAAK,6CAAsC,GAC1C,MAAM,CAiDR"}

package/dist/commands/cointegration.js

@@ -0,0 +1,118 @@
+import { invokeCliCapability } from "../cli/client.js";
+import { createCliValidationError } from "../cli/errors.js";
+import { createTerminalTheme } from "../cli/terminal.js";
+export function registerCointegrationCommands(program, context = {}) {
+    const cointegrationCommand = program
+        .command("cointegration")
+        .description("Calcula cointegração para análise de Long & Short");
+    cointegrationCommand
+        .command("pair")
+        .description("Calcula cointegração para análise de Long & Short")
+        .argument("<base_asset>", "Ticker do ativo base, por exemplo PETR4")
+        .argument("<comparison_asset>", "Ticker do ativo de comparação, por exemplo VALE3")
+        .option("--window <n>", "Janela de candles (padrão 250)")
+        .option("--json", "Exibe saída JSON")
+        .action(async (baseAsset, comparisonAsset, options) => {
+        await runCointegrationPairCommand(baseAsset, comparisonAsset, options, context);
+    });
+}
+export async function runCointegrationPairCommand(baseAsset, comparisonAsset, options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const response = await invokeCliCapability({
+        capability: "cointegration.pair",
+        input: buildCointegrationPairInput(baseAsset, comparisonAsset, options),
+        env: context.env,
+        fetch: context.fetch,
+    });
+    if (options.json) {
+        stdout.write(`${JSON.stringify(response.data, null, 2)}\n`);
+        return;
+    }
+    stdout.write(`${formatCointegrationPairHuman(response.data, theme)}\n`);
+}
+export function buildCointegrationPairInput(baseAsset, comparisonAsset, options) {
+    const normalizedBase = normalizeTicker(baseAsset, "base_asset");
+    const normalizedComparison = normalizeTicker(comparisonAsset, "comparison_asset");
+    if (normalizedBase === normalizedComparison) {
+        throw createCliValidationError("Os ativos base e de comparação devem ser diferentes.");
+    }
+    return {
+        base_asset: normalizedBase,
+        comparison_asset: normalizedComparison,
+        window: parseWindowOption(options.window),
+    };
+}
+export function formatCointegrationPairHuman(data, theme = createTerminalTheme(process.stdout)) {
+    const lines = [
+        theme.label("Cointegração / Long & Short entre ativos"),
+        "",
+        theme.bold(`${data.base_asset} x ${data.comparison_asset}`),
+        `${theme.label("Janela:")} ${formatInteger(data.window)} candles`,
+        "",
+    ];
+    lines.push(`${theme.label("Beta:")} ${formatOptionalNumber(data.beta)}`);
+    if (data.beta_mean !== null) {
+        lines.push(`${theme.label("Beta médio:")} ${formatNumber(data.beta_mean)}`);
+    }
+    if (data.beta_std !== null) {
+        lines.push(`${theme.label("Beta std:")} ${formatNumber(data.beta_std)}`);
+    }
+    if (data.beta_volatility !== null) {
+        lines.push(`${theme.label("Volatilidade beta:")} ${formatNumber(data.beta_volatility)}`);
+    }
+    lines.push(`${theme.label("ADF:")} ${formatOptionalNumber(data.adf)}`);
+    lines.push(`${theme.label("P-valor:")} ${formatOptionalNumber(data.p_value)}`);
+    lines.push(`${theme.label("Confiança:")} ${data.confidence === null ? "n/d" : formatPercent(data.confidence * 100)}`);
+    lines.push(`${theme.label("Meia-vida:")} ${formatOptionalNumber(data.halflife)}`);
+    const latest = data.zscore_series[data.zscore_series.length - 1];
+    if (latest && latest.zscore !== null) {
+        lines.push(`${theme.label("Z-score atual:")} ${formatNumber(latest.zscore)} ${theme.dim(`(${latest.date})`)}`);
+    }
+    lines.push(`${theme.label("Pontos da série de z-score:")} ${formatInteger(data.zscore_series.length)}`);
+    lines.push(`${theme.label("Pontos da série de beta:")} ${formatInteger(data.beta_series.length)}`);
+    return lines.join("\n");
+}
+function normalizeTicker(rawTicker, label) {
+    const normalized = rawTicker.trim().toUpperCase();
+    if (!normalized) {
+        throw createCliValidationError(`${label} é obrigatório.`);
+    }
+    return normalized;
+}
+function parseWindowOption(rawWindow) {
+    if (rawWindow === undefined) {
+        return 250;
+    }
+    const trimmed = rawWindow.trim();
+    if (!trimmed) {
+        throw createCliValidationError("--window não pode ser vazio.");
+    }
+    const parsed = Number.parseInt(trimmed, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0 || String(parsed) !== trimmed) {
+        throw createCliValidationError("--window deve ser um inteiro positivo.");
+    }
+    if (parsed < 20 || parsed > 2000) {
+        throw createCliValidationError("--window deve estar entre 20 e 2000 candles.");
+    }
+    return parsed;
+}
+function formatInteger(value) {
+    return new Intl.NumberFormat("pt-BR", {
+        maximumFractionDigits: 0,
+    }).format(value);
+}
+function formatNumber(value) {
+    return new Intl.NumberFormat("pt-BR", {
+        maximumFractionDigits: 4,
+    }).format(value);
+}
+function formatOptionalNumber(value) {
+    return value === null ? "n/d" : formatNumber(value);
+}
+function formatPercent(value) {
+    return `${new Intl.NumberFormat("pt-BR", {
+        maximumFractionDigits: 2,
+        minimumFractionDigits: 2,
+    }).format(value)}%`;
+}

package/dist/commands/rankings.d.ts

@@ -14,6 +14,22 @@ export interface RankingsCurrentCommandOptions {
     top?: string;
     json?: boolean;
 }
+export interface RankingsReturnCommandOptions {
+    system?: string;
+    from?: string;
+    to?: string;
+    top?: string;
+    rebalance?: string;
+    weight?: string;
+    indexFilter?: string;
+    json?: boolean;
+}
+export interface RankingReturnSimulationOut {
+    [key: string]: JsonValue;
+    supported: boolean;
+    earliest_start_date: string | null;
+    max_top_n: number | null;
+}
 export interface RankingMetricOut {
     [key: string]: JsonValue;
     key: string;
@@ -31,6 +47,7 @@ export interface RankingDefinitionOut {
     metrics: RankingMetricOut[];
     latest_as_of: string | null;
     total_assets: number | null;
+    return_simulation: RankingReturnSimulationOut;
 }
 export interface RankingsListResponse {
     [key: string]: JsonValue;
@@ -66,6 +83,51 @@ export interface RankingCurrentResponse {
     count: number;
     rows: RankingCurrentRowOut[];
 }
+export interface RankingReturnAssetAllocation {
+    [key: string]: JsonValue;
+    ticker: string;
+    weight: number;
+    ranking_position: number;
+}
+export interface RankingReturnRebalance {
+    [key: string]: JsonValue;
+    date: string;
+    portfolio: RankingReturnAssetAllocation[];
+}
+export interface RankingReturnAssetReturn {
+    [key: string]: JsonValue;
+    ticker: string;
+    return_value: number;
+    weight: number;
+    contribution: number;
+}
+export interface RankingReturnPeriodReturn {
+    [key: string]: JsonValue;
+    start_date: string;
+    end_date: string;
+    total_return: number;
+    asset_returns: RankingReturnAssetReturn[];
+}
+export interface RankingReturnResult {
+    [key: string]: JsonValue;
+    total_return: number;
+    annualized_return: number;
+    start_date: string;
+    end_date: string;
+    top_n: number;
+    rebalance_frequency: string;
+    rebalance_dates: RankingReturnRebalance[];
+    period_returns: RankingReturnPeriodReturn[];
+    ibov_return: number;
+    ibov_annualized_return: number;
+}
+export interface RankingReturnResponse {
+    [key: string]: JsonValue;
+    ok: boolean;
+    summary_markdown: string;
+    ranking: RankingDefinitionOut;
+    result: RankingReturnResult;
+}
 export interface RankingsCommandContext extends CliInvokeContext {
     io?: RankingsCommandIO;
 }
@@ -75,8 +137,11 @@ type JsonRecord = {
 export declare function registerRankingsCommands(program: Command, context?: RankingsCommandContext): void;
 export declare function runRankingsListCommand(options: RankingsListCommandOptions, context?: RankingsCommandContext): Promise<void>;
 export declare function runRankingsCurrentCommand(options: RankingsCurrentCommandOptions, context?: RankingsCommandContext): Promise<void>;
+export declare function runRankingsReturnCommand(options: RankingsReturnCommandOptions, context?: RankingsCommandContext): Promise<void>;
 export declare function buildRankingsCurrentInput(options: RankingsCurrentCommandOptions): JsonRecord;
+export declare function buildRankingsReturnInput(options: RankingsReturnCommandOptions): JsonRecord;
 export declare function formatRankingsListHuman(data: RankingsListResponse, theme?: import("../cli/terminal.js").TerminalTheme): string;
 export declare function formatRankingCurrentHuman(data: RankingCurrentResponse, theme?: import("../cli/terminal.js").TerminalTheme): string;
+export declare function formatRankingReturnHuman(data: RankingReturnResponse, theme?: import("../cli/terminal.js").TerminalTheme): string;
 export {};
 //# sourceMappingURL=rankings.d.ts.map

package/dist/commands/rankings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rankings.d.ts","sourceRoot":"","sources":["../../src/commands/rankings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rankings.d.ts","sourceRoot":"","sources":["../../src/commands/rankings.ts"],"names":[],"mappings":"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"}

package/dist/commands/rankings.js

@@ -1,3 +1,4 @@
+import { rankingReturnIndexFilterValues, rankingReturnRebalanceValues, rankingReturnWeightingValues, } from "../vendor/core/capabilities/index.js";
 import { invokeCliCapability } from "../cli/client.js";
 import { createCliValidationError } from "../cli/errors.js";
 import { createTerminalTheme } from "../cli/terminal.js";
@@ -22,6 +23,20 @@ export function registerRankingsCommands(program, context = {}) {
         .action(async (options) => {
         await runRankingsCurrentCommand(options, context);
     });
+    rankingsCommand
+        .command("return")
+        .description("Calcula o retorno histórico de um ranking do sistema")
+        .requiredOption("--system <slug>", "Slug do ranking do sistema")
+        .requiredOption("--from <date>", "Data inicial em AAAA-MM-DD")
+        .requiredOption("--to <date>", "Data final em AAAA-MM-DD")
+        .option("--top <n>", "Número de ativos em cada rebalanceamento", "20")
+        .requiredOption("--rebalance <frequency>", "Frequência: weekly, monthly, bimonthly, quarterly, semiannually ou annually")
+        .option("--weight <method>", "Método de ponderação", "equal")
+        .option("--index-filter <filter>", "Filtro: NONE, IBOV, IBX100 ou SMLL", "NONE")
+        .option("--json", "Exibe saída JSON")
+        .action(async (options) => {
+        await runRankingsReturnCommand(options, context);
+    });
 }
 export async function runRankingsListCommand(options, context = {}) {
     const stdout = context.io?.stdout ?? process.stdout;
@@ -52,6 +67,21 @@ export async function runRankingsCurrentCommand(options, context = {}) {
     }
     stdout.write(`${formatRankingCurrentHuman(response.data, theme)}\n`);
 }
+export async function runRankingsReturnCommand(options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const response = await invokeCliCapability({
+        capability: "rankings.return",
+        input: buildRankingsReturnInput(options),
+        env: context.env,
+        fetch: context.fetch,
+    });
+    if (options.json) {
+        stdout.write(`${JSON.stringify(response.data, null, 2)}\n`);
+        return;
+    }
+    stdout.write(`${formatRankingReturnHuman(response.data, theme)}\n`);
+}
 export function buildRankingsCurrentInput(options) {
     const hasId = options.id !== undefined;
     const hasSystem = options.system !== undefined;
@@ -69,6 +99,22 @@ export function buildRankingsCurrentInput(options) {
     }
     return input;
 }
+export function buildRankingsReturnInput(options) {
+    const startDate = parseIsoDateOption(options.from, "--from");
+    const endDate = parseIsoDateOption(options.to, "--to");
+    if (startDate >= endDate) {
+        throw createCliValidationError("--from deve ser anterior a --to.");
+    }
+    return {
+        system_id: normalizeRequiredString(options.system, "--system"),
+        start_date: startDate,
+        end_date: endDate,
+        top_n: parseRankingReturnTopOption(options.top),
+        rebalance_frequency: parseEnumOption(options.rebalance, "--rebalance", rankingReturnRebalanceValues),
+        weighting_method: parseEnumOption(options.weight ?? "equal", "--weight", rankingReturnWeightingValues),
+        index_filter: parseEnumOption(options.indexFilter ?? "NONE", "--index-filter", rankingReturnIndexFilterValues),
+    };
+}
 export function formatRankingsListHuman(data, theme = createTerminalTheme(process.stdout)) {
     const lines = [
         theme.label("Rankings"),
@@ -108,6 +154,33 @@ export function formatRankingCurrentHuman(data, theme = createTerminalTheme(proc
     lines.push(...formatRankingRows(data.rows, data.ranking.order_metric.label));
     return lines.join("\n");
 }
+export function formatRankingReturnHuman(data, theme = createTerminalTheme(process.stdout)) {
+    const result = data.result;
+    const alpha = result.total_return - result.ibov_return;
+    const lines = [
+        theme.label("Retorno de ranking"),
+        "",
+        `${theme.bold(data.ranking.name)} ${theme.dim("(sistema)")}`,
+        `${theme.label("Sistema:")} ${data.ranking.id}`,
+        `${theme.label("Período:")} ${formatDatePtBr(result.start_date)} a ${formatDatePtBr(result.end_date)}`,
+        `${theme.label("Top:")} ${formatInteger(result.top_n)}`,
+        `${theme.label("Rebalanceamento:")} ${formatRebalanceFrequency(result.rebalance_frequency)}`,
+        "",
+        `${theme.label("Retorno total:")} ${formatPercentage(result.total_return)}`,
+        `${theme.label("Retorno anualizado:")} ${formatPercentage(result.annualized_return)}`,
+        `${theme.label("IBOV no período:")} ${formatPercentage(result.ibov_return)}`,
+        `${theme.label("IBOV anualizado:")} ${formatPercentage(result.ibov_annualized_return)}`,
+        `${theme.label("Alfa vs IBOV:")} ${formatPercentagePoints(alpha)}`,
+        "",
+        `${theme.label("Rebalanceamentos:")} ${formatInteger(result.rebalance_dates.length)}`,
+        `${theme.label("Períodos calculados:")} ${formatInteger(result.period_returns.length)}`,
+    ];
+    if (data.summary_markdown.trim()) {
+        lines.push("");
+        lines.push(data.summary_markdown);
+    }
+    return lines.join("\n");
+}
 function formatRankingGroup(title, rankings, theme) {
     const lines = [
         `${theme.label(title)} ${theme.dim(`(${formatInteger(rankings.length)})`)}`,
@@ -139,6 +212,9 @@ function formatRankingGroup(title, rankings, theme) {
             lines.push(`    ${theme.label("Ativos:")} ${formatInteger(ranking.total_assets)}`);
         }
         lines.push(`    ${theme.label("Uso:")} ${formatRankingUsage(ranking)}`);
+        if (ranking.kind === "SYSTEM") {
+            lines.push(`    ${theme.label("Retorno:")} ${formatRankingReturnUsage(ranking)}`);
+        }
     }
     return lines;
 }
@@ -158,6 +234,15 @@ function formatRankingUsage(ranking) {
     }
     return `quantbrasil rankings current --system ${ranking.id} --top 20`;
 }
+function formatRankingReturnUsage(ranking) {
+    if (!ranking.return_simulation.supported) {
+        return "indisponível";
+    }
+    return `quantbrasil rankings return --system ${ranking.id} --from ${formatRankingReturnUsageStartDate(ranking)} --to AAAA-MM-DD --top 20 --rebalance quarterly`;
+}
+function formatRankingReturnUsageStartDate(ranking) {
+    return ranking.return_simulation.earliest_start_date ?? "AAAA-MM-DD";
+}
 function formatRankingKind(kind) {
     return kind === "SYSTEM" ? "sistema" : "usuário";
 }
@@ -194,12 +279,76 @@ function formatMetricValue(metric) {
     }
     return String(metric.value);
 }
+function formatPercentage(value) {
+    return `${formatNumber(value * 100)}%`;
+}
+function formatPercentagePoints(value) {
+    const prefix = value > 0 ? "+" : value < 0 ? "-" : "";
+    return `${prefix}${formatNumber(Math.abs(value * 100))} p.p.`;
+}
+function formatDatePtBr(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(value);
+    if (!match) {
+        return value;
+    }
+    return `${match[3]}/${match[2]}/${match[1]}`;
+}
+function formatRebalanceFrequency(value) {
+    switch (value) {
+        case "weekly":
+            return "semanal";
+        case "monthly":
+            return "mensal";
+        case "bimonthly":
+            return "bimestral";
+        case "quarterly":
+            return "trimestral";
+        case "semiannually":
+            return "semestral";
+        case "annually":
+            return "anual";
+        default:
+            return value;
+    }
+}
 function parseTopOption(rawTop) {
     if (rawTop === undefined) {
         return 20;
     }
     return parsePositiveInteger(rawTop, "--top");
 }
+function parseRankingReturnTopOption(rawTop) {
+    const parsed = parseTopOption(rawTop);
+    if (parsed > 30) {
+        throw createCliValidationError("--top deve ser menor ou igual a 30.");
+    }
+    return parsed;
+}
+function parseIsoDateOption(rawValue, label) {
+    const normalized = normalizeRequiredString(rawValue, label);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(normalized)) {
+        throw createCliValidationError(`${label} deve usar o formato AAAA-MM-DD.`);
+    }
+    const parsed = new Date(`${normalized}T00:00:00.000Z`);
+    if (Number.isNaN(parsed.getTime())) {
+        throw createCliValidationError(`${label} deve ser uma data válida.`);
+    }
+    const [year, month, day] = normalized.split("-").map(Number);
+    if (parsed.getUTCFullYear() !== year ||
+        parsed.getUTCMonth() + 1 !== month ||
+        parsed.getUTCDate() !== day) {
+        throw createCliValidationError(`${label} deve ser uma data válida.`);
+    }
+    return normalized;
+}
+function parseEnumOption(rawValue, label, allowedValues) {
+    const normalized = normalizeRequiredString(rawValue, label);
+    const match = allowedValues.find(value => value === normalized);
+    if (!match) {
+        throw createCliValidationError(`${label} deve ser um destes valores: ${allowedValues.join(", ")}.`);
+    }
+    return match;
+}
 function parsePositiveInteger(rawValue, label) {
     const normalized = normalizeRequiredString(rawValue, label);
     const parsed = Number.parseInt(normalized, 10);

package/dist/vendor/core/capabilities/cointegration.d.ts

@@ -0,0 +1,52 @@
+export declare const cointegrationCapabilities: readonly [{
+    readonly id: "cointegration.pair";
+    readonly kind: "read";
+    readonly visibility: readonly ["cli", "opencode"];
+    readonly description: "Calcula cointegração para análise de Long & Short entre dois ativos: z-score, beta, p-valor, meia-vida e intervalos de confiança.";
+    readonly http: {
+        readonly method: "POST";
+        readonly path: "/api/desk/tools/cointegration/pair";
+        readonly inputMode: "json_body";
+        readonly schemas: {
+            readonly request: "CointegrationPairRequest";
+            readonly response: "CointegrationPairResponse";
+        };
+    };
+    readonly cli: {
+        readonly group: "cointegration";
+        readonly command: "pair";
+        readonly summary: "Calcula cointegração para análise de Long & Short.";
+        readonly positional: readonly [{
+            readonly kind: "positional";
+            readonly name: "base_asset";
+            readonly type: "string";
+            readonly required: true;
+            readonly placeholder: "TICKER";
+            readonly description: "Ticker do ativo base, por exemplo PETR4.";
+        }, {
+            readonly kind: "positional";
+            readonly name: "comparison_asset";
+            readonly type: "string";
+            readonly required: true;
+            readonly placeholder: "TICKER";
+            readonly description: "Ticker do ativo de comparação, por exemplo VALE3.";
+        }];
+        readonly options: readonly [{
+            readonly kind: "option";
+            readonly flag: "--window";
+            readonly name: "window";
+            readonly type: "integer";
+            readonly required: false;
+            readonly placeholder: "N";
+            readonly defaultValue: 250;
+            readonly description: "Janela de candles para a regressão. Padrão 250 dias úteis.";
+        }];
+        readonly examples: readonly ["quantbrasil cointegration pair PETR4 VALE3", "quantbrasil cointegration pair PETR4 VALE3 --window 120", "quantbrasil cointegration pair PETR4 VALE3 --json"];
+    };
+    readonly tool: {
+        readonly name: "qb_cointegration_pair";
+        readonly title: "Calcular cointegração para Long & Short";
+    };
+    readonly outputModes: readonly ["json", "human"];
+}];
+//# sourceMappingURL=cointegration.d.ts.map

package/dist/vendor/core/capabilities/cointegration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cointegration.d.ts","sourceRoot":"","sources":["../../src/capabilities/cointegration.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+Dc,CAAC"}