From 669daed0f83b350bf034178aa8ff9cdb35b56c8f Mon Sep 17 00:00:00 2001 From: Anirudh Kamath Date: Thu, 12 Dec 2024 12:02:29 -0800 Subject: [PATCH 1/4] tidy: deprecate fields --- README.md | 11 +++++++---- examples/example.ts | 3 ++- lib/index.ts | 42 ++++++++++++++++++++---------------------- types/stagehand.ts | 7 ++++++- 4 files changed, 35 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 5ad7de6d..82fb4e32 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,7 @@ This constructor is used to create an instance of Stagehand. - `domSettleTimeoutMs`: an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. Defaults to 30000 (30 seconds). - `apiKey`: (optional) your Browserbase API key. Defaults to `BROWSERBASE_API_KEY` environment variable. - `projectId`: (optional) your Browserbase project ID. Defaults to `BROWSERBASE_PROJECT_ID` environment variable. - - `browserBaseSessionCreateParams`: configuration options for creating new Browserbase sessions. + - `browserbaseSessionCreateParams`: configuration options for creating new Browserbase sessions. - `browserbaseResumeSessionID`: ID of an existing Browserbase session to resume. - `logger`: a function that handles log messages. Useful for custom logging implementations. - `verbose`: an `integer` that enables several levels of logging during automation: @@ -184,11 +184,14 @@ This constructor is used to create an instance of Stagehand. `init()` asynchronously initializes the Stagehand instance. It should be called before any other methods. +> [!WARNING] +> Passing parameters to `init()` is deprecated and will be removed in the next major version. Use the constructor options instead. + - **Arguments:** - - `modelName`: (optional) an `AvailableModel` string to specify the model to use. This will be used for all other methods unless overridden. - - `modelClientOptions`: (optional) configuration options for the model client - - `domSettleTimeoutMs`: (optional) timeout in milliseconds for waiting for the DOM to settle + - `modelName`: (**deprecated**, optional) an `AvailableModel` string to specify the model to use. This will be used for all other methods unless overridden. + - `modelClientOptions`: (**deprecated**, optional) configuration options for the model client + - `domSettleTimeoutMs`: (**deprecated**, optional) timeout in milliseconds for waiting for the DOM to settle - **Returns:** diff --git a/examples/example.ts b/examples/example.ts index ee96935c..93beaf94 100644 --- a/examples/example.ts +++ b/examples/example.ts @@ -8,9 +8,10 @@ async function example() { debugDom: true, enableCaching: false, modelName: "claude-3-5-sonnet-latest", + domSettleTimeoutMs: 10_000, }); - await stagehand.init({ domSettleTimeoutMs: 3000 }); + await stagehand.init(); await stagehand.page.goto("https://www.mycmh.org/locations/"); const result = await stagehand.extract({ diff --git a/lib/index.ts b/lib/index.ts index fff0e970..acd2d105 100644 --- a/lib/index.ts +++ b/lib/index.ts @@ -316,7 +316,7 @@ export class Stagehand { private logger: (logLine: LogLine) => void; private externalLogger?: (logLine: LogLine) => void; private domSettleTimeoutMs: number; - private browserBaseSessionCreateParams?: Browserbase.Sessions.SessionCreateParams; + private browserbaseSessionCreateParams?: Browserbase.Sessions.SessionCreateParams; private enableCaching: boolean; private variables: { [key: string]: unknown }; private browserbaseResumeSessionID?: string; @@ -336,7 +336,7 @@ export class Stagehand { llmProvider, headless, logger, - browserBaseSessionCreateParams, + browserbaseSessionCreateParams, domSettleTimeoutMs, enableCaching, browserbaseResumeSessionID, @@ -364,25 +364,26 @@ export class Stagehand { ); this.domSettleTimeoutMs = domSettleTimeoutMs ?? 30_000; this.headless = headless ?? false; - this.browserBaseSessionCreateParams = browserBaseSessionCreateParams; + this.browserbaseSessionCreateParams = browserbaseSessionCreateParams; this.browserbaseResumeSessionID = browserbaseResumeSessionID; } - async init({ - modelName, - modelClientOptions, - domSettleTimeoutMs, - }: InitOptions = {}): Promise { - const llmClient = modelName - ? this.llmProvider.getClient(modelName, modelClientOptions) - : this.llmClient; + async init( + /** @deprecated Use constructor options instead */ + initOptions?: InitOptions, + ): Promise { + if (initOptions) { + console.warn( + "initOptions is deprecated and will be removed in the next major version. Use constructor options instead.", + ); + } const { context, debugUrl, sessionUrl, contextPath } = await getBrowser( this.apiKey, this.projectId, this.env, this.headless, this.logger, - this.browserBaseSessionCreateParams, + this.browserbaseSessionCreateParams, this.browserbaseResumeSessionID, ).catch((e) => { console.error("Error in init:", e); @@ -399,7 +400,6 @@ export class Stagehand { // Redundant but needed for users who are re-connecting to a previously-created session await this.page.waitForLoadState("domcontentloaded"); await this._waitForSettledDom(); - this.domSettleTimeoutMs = domSettleTimeoutMs ?? this.domSettleTimeoutMs; // Overload the page.goto method const originalGoto = this.page.goto.bind(this.page); @@ -431,7 +431,7 @@ export class Stagehand { waitForSettledDom: this._waitForSettledDom.bind(this), startDomDebug: this.startDomDebug.bind(this), cleanupDomDebug: this.cleanupDomDebug.bind(this), - llmClient, + llmClient: this.llmClient, }); this.extractHandler = new StagehandExtractHandler({ @@ -442,7 +442,7 @@ export class Stagehand { cleanupDomDebug: this.cleanupDomDebug.bind(this), llmProvider: this.llmProvider, verbose: this.verbose, - llmClient, + llmClient: this.llmClient, }); this.observeHandler = new StagehandObserveHandler({ @@ -453,23 +453,21 @@ export class Stagehand { cleanupDomDebug: this.cleanupDomDebug.bind(this), llmProvider: this.llmProvider, verbose: this.verbose, - llmClient, + llmClient: this.llmClient, }); - this.llmClient = llmClient; return { debugUrl, sessionUrl }; } + /** @deprecated initFromPage is deprecated and will be removed in the next major version. */ async initFromPage({ page, - modelName, - modelClientOptions, }: InitFromPageOptions): Promise { + console.warn( + "initFromPage is deprecated and will be removed in the next major version. To instantiate from a page, use `browserbaseResumeSessionID` in the constructor.", + ); this.page = page; this.context = page.context(); - this.llmClient = modelName - ? this.llmProvider.getClient(modelName, modelClientOptions) - : this.llmClient; const originalGoto = this.page.goto.bind(this.page); this.page.goto = async (url: string, options?: GotoOptions) => { diff --git a/types/stagehand.ts b/types/stagehand.ts index 59f77928..6086dd88 100644 --- a/types/stagehand.ts +++ b/types/stagehand.ts @@ -15,7 +15,7 @@ export interface ConstructorParams { headless?: boolean; logger?: (message: LogLine) => void; domSettleTimeoutMs?: number; - browserBaseSessionCreateParams?: Browserbase.Sessions.SessionCreateParams; + browserbaseSessionCreateParams?: Browserbase.Sessions.SessionCreateParams; enableCaching?: boolean; browserbaseResumeSessionID?: string; modelName?: AvailableModel; @@ -28,8 +28,11 @@ export interface InitResult { } export interface InitOptions { + /** @deprecated Pass this into the Stagehand constructor instead. This will be removed in the next major version. */ modelName?: AvailableModel; + /** @deprecated Pass this into the Stagehand constructor instead. This will be removed in the next major version. */ modelClientOptions?: ClientOptions; + /** @deprecated Pass this into the Stagehand constructor instead. This will be removed in the next major version. */ domSettleTimeoutMs?: number; } @@ -40,7 +43,9 @@ export interface InitResult { export interface InitFromPageOptions { page: Page; + /** @deprecated Pass this into the Stagehand constructor instead. This will be removed in the next major version. */ modelName?: AvailableModel; + /** @deprecated Pass this into the Stagehand constructor instead. This will be removed in the next major version. */ modelClientOptions?: ClientOptions; } From 7ea96a982ed7c7e74811f13c0b5b03f5fec22f89 Mon Sep 17 00:00:00 2001 From: Anirudh Kamath Date: Thu, 12 Dec 2024 12:03:53 -0800 Subject: [PATCH 2/4] console warn --- lib/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/index.ts b/lib/index.ts index acd2d105..3540b320 100644 --- a/lib/index.ts +++ b/lib/index.ts @@ -374,7 +374,7 @@ export class Stagehand { ): Promise { if (initOptions) { console.warn( - "initOptions is deprecated and will be removed in the next major version. Use constructor options instead.", + "Passing parameters to init() is deprecated and will be removed in the next major version. Use constructor options instead.", ); } const { context, debugUrl, sessionUrl, contextPath } = await getBrowser( From 8910cf196e712375121bfeb46b116853362a2428 Mon Sep 17 00:00:00 2001 From: Anirudh Kamath Date: Thu, 12 Dec 2024 12:10:06 -0800 Subject: [PATCH 3/4] update changeset --- .changeset/gorgeous-readers-rush.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 .changeset/gorgeous-readers-rush.md diff --git a/.changeset/gorgeous-readers-rush.md b/.changeset/gorgeous-readers-rush.md new file mode 100644 index 00000000..0cbe03ff --- /dev/null +++ b/.changeset/gorgeous-readers-rush.md @@ -0,0 +1,7 @@ +--- +"@browserbasehq/stagehand": minor +--- + +- Deprecate fields in `init` in favor of constructor options +- Deprecate `initFromPage` in favor of `browserbaseResumeSessionID` in constructor +- Rename `browserBaseSessionCreateParams` -> `browserbaseSessionCreateParams` From c0339b6f6d90c218d7d1e3eaa0fd3fb15044c0eb Mon Sep 17 00:00:00 2001 From: Anirudh Kamath Date: Thu, 12 Dec 2024 12:17:53 -0800 Subject: [PATCH 4/4] mroe cleanup --- README.md | 2 +- evals/utils.ts | 4 +++- examples/parameterizeApiKey.ts | 7 +------ 3 files changed, 5 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 82fb4e32..fefb5ce4 100644 --- a/README.md +++ b/README.md @@ -201,7 +201,7 @@ This constructor is used to create an instance of Stagehand. - **Example:** ```javascript - await stagehand.init({ modelName: "gpt-4o" }); + await stagehand.init(); ``` #### `act()` diff --git a/evals/utils.ts b/evals/utils.ts index d0fa30d5..1286182d 100644 --- a/evals/utils.ts +++ b/evals/utils.ts @@ -30,12 +30,14 @@ export const initStagehand = async ({ }) => { const stagehand = new Stagehand({ ...defaultStagehandOptions, + modelName, + domSettleTimeoutMs, logger: (logLine: LogLine) => { logger.log(logLine); }, }); logger.init(stagehand); - const initResponse = await stagehand.init({ modelName, domSettleTimeoutMs }); + const initResponse = await stagehand.init(); return { stagehand, logger, initResponse }; }; diff --git a/examples/parameterizeApiKey.ts b/examples/parameterizeApiKey.ts index 00daa36c..dc29f5f8 100644 --- a/examples/parameterizeApiKey.ts +++ b/examples/parameterizeApiKey.ts @@ -23,12 +23,7 @@ async function example() { }, }); - await stagehand.init({ - modelName: "gpt-4o", - modelClientOptions: { - apiKey: process.env.USE_OPENAI_API_KEY, - }, - }); + await stagehand.init(); await stagehand.page.goto("https://github.com/browserbase/stagehand"); await stagehand.act({ action: "click on the contributors" }); const contributor = await stagehand.extract({