Feedback on 0.2 docs

[bracesproul]

We're releasing LangChain 0.2 the week of 5/20/24 (see #5383), and a major part of this release is revamping our docs.

The high level changes to the docs are that we:

• Are strictly following diataxis
• Have flattened the structure
• Support versioning

You can read a bit more about these changes in our 0.2 intro blog and see a preview of the 0.2 docs here.

We'd love your feedback on the 0.2 docs.

All of these changes have been informed by great feedback we've gotten on the existing docs, and we want to make sure that we're continuing to improve.

If you'd prefer to leave anonymous feedback, you can use this Google Form.

[Abhicurio]

The recent update from Langchain version 0.1 to 0.2 has introduced significant changes, particularly in terms of deprecating various functions. While advancements and improvements in the framework are always welcome, the transition has posed challenges due to the absence of clear documentation and mapping for the deprecated functions to their new counterparts.

Challenges Encountered:

1. Deprecation Without Clear Replacement Paths:

• Several functions that were frequently used in version 0.1 have been deprecated in version 0.2. However, there is a notable lack of detailed documentation indicating which new functions or methods are intended to replace the deprecated ones.
• This omission forces developers to spend considerable time and effort in trial and error, or in some cases, to reverse-engineer the new version to understand the new methodologies and workflows.

2. Increased Learning Curve:

• The absence of a migration guide or clear mapping increases the learning curve for existing users of Langchain. Users who were accustomed to the old version now have to invest additional time to understand the new version from scratch.
• This can be particularly frustrating for developers working on critical projects with tight deadlines, as the transition to the updated version could cause unexpected delays.

3. Inconsistency in Documentation:

• The existing documentation does not adequately highlight the changes or provide side-by-side comparisons of deprecated and new functions.
• A comprehensive change log or an upgrade guide would be beneficial to bridge this gap, ensuring a smoother transition for users.

Suggestions for Improvement:

1. Detailed Migration Guide:

• Develop a thorough migration guide that lists each deprecated function from version 0.1 along with its corresponding replacement in version 0.2.
• Include examples demonstrating how to use the new functions in place of the old ones. This will significantly reduce the time users spend figuring out the new functionalities.

2. Enhanced Documentation:

• Update the official documentation to include a section dedicated to deprecated functions and their replacements.
• Provide detailed explanations and usage scenarios for the new functions to help users understand their benefits and how to integrate them into their existing projects.

[rsgrewal-aws]

Could we please ensure the ChatBedrockConverse class is not publicized. The right class to use is ChatBedrock with a flag passed in

[LuisFX]

Is there per chance, instructions on how to build/run/browse docs offline?

[rsgrewal-aws]

yes let me share

[LuisFX]

Great, waiting anxiously!

[LuisFX]

Hi @rsgrewal-aws, just wondering if you got around getting those notes. We'd really appreciate it. Thank you!!

[rsgrewal-aws]

could not find one -- i can create it but the code will be
from langchain_aws.chat_models.bedrock import ChatBedrock
llm = ChatBedrock(beta_use_converse_api=True, model="anthropic.claude-3-sonnet-20240229-v1:0", **model_kwargs)
Invoke:
.. code-block:: python

        messages = [
            ("system", "You are a helpful translator. Translate the user sentence to French."),
            ("human", "I love programming."),
        ]
        llm.invoke(messages)

    .. code-block:: python

        AIMessage(content=[{'type': 'text', 'text': "J'aime la programmation."}], response_metadata={'ResponseMetadata': {'RequestId': '9ef1e313-a4c1-4f79-b631-171f658d3c0e', 'HTTPStatusCode': 200, 'HTTPHeaders': {'date': 'Sat, 15 Jun 2024 01:19:24 GMT', 'content-type': 'application/json', 'content-length': '205', 'connection': 'keep-alive', 'x-amzn-requestid': '9ef1e313-a4c1-4f79-b631-171f658d3c0e'}, 'RetryAttempts': 0}, 'stopReason': 'end_turn', 'metrics': {'latencyMs': 609}}, id='run-754e152b-2b41-4784-9538-d40d71a5c3bc-0', usage_metadata={'input_tokens': 25, 'output_tokens': 11, 'total_tokens': 36})

Stream:
    .. code-block:: python

        for chunk in llm.stream(messages):
            print(chunk)

    .. code-block:: python

        AIMessageChunk(content=[], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117')
        AIMessageChunk(content=[{'type': 'text', 'text': 'J', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117')
        AIMessageChunk(content=[{'text': "'", 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117')
        AIMessageChunk(content=[{'text': 'a', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117')
        AIMessageChunk(content=[{'text': 'ime', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117')
        AIMessageChunk(content=[{'text': ' la', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117')
        AIMessageChunk(content=[{'text': ' programm', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117')
        AIMessageChunk(content=[{'text': 'ation', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117')
        AIMessageChunk(content=[{'text': '.', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117')
        AIMessageChunk(content=[{'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117')
        AIMessageChunk(content=[], response_metadata={'stopReason': 'end_turn'}, id='run-da3c2606-4792-440a-ac66-72e0d1f6d117')
        AIMessageChunk(content=[], response_metadata={'metrics': {'latencyMs': 581}}, id='run-da3c2606-4792-440a-ac66-72e0d1f6d117', usage_metadata={'input_tokens': 25, 'output_tokens': 11, 'total_tokens': 36})

    .. code-block:: python

        stream = llm.stream(messages)
        full = next(stream)
        for chunk in stream:
            full += chunk
        full

    .. code-block:: python

        AIMessageChunk(content=[{'type': 'text', 'text': "J'aime la programmation.", 'index': 0}], response_metadata={'stopReason': 'end_turn', 'metrics': {'latencyMs': 554}}, id='run-56a5a5e0-de86-412b-9835-624652dc3539', usage_metadata={'input_tokens': 25, 'output_tokens': 11, 'total_tokens': 36})

Tool calling:
    .. code-block:: python

        from langchain_core.pydantic_v1 import BaseModel, Field

        class GetWeather(BaseModel):
            '''Get the current weather in a given location'''

            location: str = Field(..., description="The city and state, e.g. San Francisco, CA")

        class GetPopulation(BaseModel):
            '''Get the current population in a given location'''

            location: str = Field(..., description="The city and state, e.g. San Francisco, CA")

        llm_with_tools = llm.bind_tools([GetWeather, GetPopulation])
        ai_msg = llm_with_tools.invoke("Which city is hotter today and which is bigger: LA or NY?")
        ai_msg.tool_calls

    .. code-block:: python

        [{'name': 'GetWeather',
          'args': {'location': 'Los Angeles, CA'},
          'id': 'tooluse_Mspi2igUTQygp-xbX6XGVw'},
         {'name': 'GetWeather',
          'args': {'location': 'New York, NY'},
          'id': 'tooluse_tOPHiDhvR2m0xF5_5tyqWg'},
         {'name': 'GetPopulation',
          'args': {'location': 'Los Angeles, CA'},
          'id': 'tooluse__gcY_klbSC-GqB-bF_pxNg'},
         {'name': 'GetPopulation',
          'args': {'location': 'New York, NY'},
          'id': 'tooluse_-1HSoGX0TQCSaIg7cdFy8Q'}]

    See ``ChatBedrockConverse.bind_tools()`` method for more.

Structured output:
    .. code-block:: python

        from typing import Optional

        from langchain_core.pydantic_v1 import BaseModel, Field

        class Joke(BaseModel):
            '''Joke to tell user.'''

            setup: str = Field(description="The setup of the joke")
            punchline: str = Field(description="The punchline to the joke")
            rating: Optional[int] = Field(description="How funny the joke is, from 1 to 10")

        structured_llm = llm.with_structured_output(Joke)
        structured_llm.invoke("Tell me a joke about cats")

    .. code-block:: python

        Joke(setup='What do you call a cat that gets all dressed up?', punchline='A purrfessional!', rating=7)

    See ``ChatBedrockConverse.with_structured_output()`` for more.

Image input:
    .. code-block:: python

        import base64
        import httpx
        from langchain_core.messages import HumanMessage

        image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
        image_data = base64.b64encode(httpx.get(image_url).content).decode("utf-8")
        message = HumanMessage(
            content=[
                {"type": "text", "text": "describe the weather in this image"},
                {
                    "type": "image",
                    "source": {"type": "base64", "media_type": "image/jpeg", "data": image_data},
                },
            ],
        )
        ai_msg = llm.invoke([message])
        ai_msg.content

    .. code-block:: python

        [{'type': 'text',
          'text': 'The image depicts a sunny day with a partly cloudy sky. The sky is a brilliant blue color with scattered white clouds drifting across. The lighting and cloud patterns suggest pleasant, mild weather conditions. The scene shows an open grassy field or meadow, indicating warm temperatures conducive for vegetation growth. Overall, the weather portrayed in this scenic outdoor image appears to be sunny with some clouds, likely representing a nice, comfortable day.'}]

Token usage:
    .. code-block:: python

        ai_msg = llm.invoke(messages)
        ai_msg.usage_metadata

    .. code-block:: python

        {'input_tokens': 25, 'output_tokens': 11, 'total_tokens': 36}

Response metadata
    .. code-block:: python

        ai_msg = llm.invoke(messages)
        ai_msg.response_metadata

    .. code-block:: python

        {'ResponseMetadata': {'RequestId': '776a2a26-5946-45ae-859e-82dc5f12017c',
          'HTTPStatusCode': 200,
          'HTTPHeaders': {'date': 'Mon, 17 Jun 2024 01:37:05 GMT',
           'content-type': 'application/json',
           'content-length': '206',
           'connection': 'keep-alive',
           'x-amzn-requestid': '776a2a26-5946-45ae-859e-82dc5f12017c'},
          'RetryAttempts': 0},
         'stopReason': 'end_turn',
         'metrics': {'latencyMs': 1290}}
"""  # noqa: E501

client: Any = Field(exclude=True)  #: :meta private:

model_id: str = Field(alias="model")
"""Id of the model to call.

e.g., ``"anthropic.claude-3-sonnet-20240229-v1:0"``. This is equivalent to the 
modelID property in the list-foundation-models api. For custom and provisioned 
models, an ARN value is expected. See 
https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html#model-ids-arns 
for a list of all supported built-in models.
"""

max_tokens: Optional[int] = None
"""Max tokens to generate."""

stop_sequences: Optional[List[str]] = Field(None, alias="stop")
"""Stop generation if any of these substrings occurs."""

temperature: Optional[float] = None
"""Sampling temperature. Must be 0 to 1."""

top_p: Optional[float] = None
"""The percentage of most-likely candidates that are considered for the next token.

Must be 0 to 1.

For example, if you choose a value of 0.8 for topP, the model selects from 
the top 80% of the probability distribution of tokens that could be next in the 
sequence."""

region_name: Optional[str] = None
"""The aws region, e.g., `us-west-2`. 

Falls back to AWS_DEFAULT_REGION env variable or region specified in ~/.aws/config 
in case it is not provided here.
"""

credentials_profile_name: Optional[str] = Field(default=None, exclude=True)
"""The name of the profile in the ~/.aws/credentials or ~/.aws/config files.

Profile should either have access keys or role information specified.
If not specified, the default credential profile or, if on an EC2 instance,
credentials from IMDS will be used. See: 
https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
"""

provider: str = ""
"""The model provider, e.g., amazon, cohere, ai21, etc. 

When not supplied, provider is extracted from the first part of the model_id, e.g. 
'amazon' in 'amazon.titan-text-express-v1'. This value should be provided for model 
ids that do not have the provider in them, like custom and provisioned models that 
have an ARN associated with them.
"""

endpoint_url: Optional[str] = Field(None, alias="base_url")
"""Needed if you don't want to default to us-east-1 endpoint"""

config: Any = None
"""An optional botocore.config.Config instance to pass to the client."""

guardrail_config: Optional[Dict[str, Any]] = Field(None, alias="guardrails")
"""Configuration information for a guardrail that you want to use in the request."""

additional_model_request_fields: Optional[Dict[str, Any]] = None
"""Additional inference parameters that the model supports.

Parameters beyond the base set of inference parameters that Converse supports in the
inferenceConfig field.
"""

additional_model_response_field_paths: Optional[List[str]] = None
"""Additional model parameters field paths to return in the response. 

Converse returns the requested fields as a JSON Pointer object in the 
additionalModelResponseFields field. The following is example JSON for 
additionalModelResponseFieldPaths.
"""

[LuisFX]

@rsgrewal-aws , I'm not sure what that does. I think i might have misstated my question. All I need is to be able to browse the langchain documentation without an internet connection. Thank you for trying anyway.