From d0b6299beb8314124e360ac52b33961e2405e70e Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Mon, 31 Mar 2025 13:54:10 -0400 Subject: [PATCH] docs: platform content (#7091) * initial-content * fix-url-errors * update platform build instructions for environment variable setup * code-review * code-review * naming-and-cleanup * fix-broken-link-for-build * typo-and-confirm-windows-path * local-memory-update * memory-introduction * no-deploy * fix-build-error * title-anchors-correctly * more-overview-and-walkthrough * reorder-pages-fix-link * another-link * Apply suggestions from code review Co-authored-by: KimberlyFields <46325568+KimberlyFields@users.noreply.github.com> * page-titles * numbered-list-to-bullets * trailing-spaces --------- Co-authored-by: KimberlyFields <46325568+KimberlyFields@users.noreply.github.com> --- docs/docs/Concepts/concepts-flows.md | 5 +- docs/docs/Develop/develop-application.md | 163 ++++++++++++++++++ docs/docs/Develop/develop-overview.md | 17 ++ .../Develop/install-custom-dependencies.md | 76 ++++++++ docs/docs/Develop/logging.md | 26 +++ docs/docs/Develop/memory.md | 93 ++++++++++ docs/docs/Develop/session-id.md | 40 +++++ docs/sidebars.js | 12 ++ 8 files changed, 431 insertions(+), 1 deletion(-) create mode 100644 docs/docs/Develop/develop-application.md create mode 100644 docs/docs/Develop/develop-overview.md create mode 100644 docs/docs/Develop/install-custom-dependencies.md create mode 100644 docs/docs/Develop/logging.md create mode 100644 docs/docs/Develop/memory.md create mode 100644 docs/docs/Develop/session-id.md diff --git a/docs/docs/Concepts/concepts-flows.md b/docs/docs/Concepts/concepts-flows.md index d1df9570e..6b5d4ebfa 100644 --- a/docs/docs/Concepts/concepts-flows.md +++ b/docs/docs/Concepts/concepts-flows.md @@ -1,4 +1,7 @@ -# Flows +--- +title: Flows +slug: /concepts-flows +--- Flows in Langflow are fully serializable and can be saved and loaded from the file system. In this guide, we'll explore how to import and export flows. diff --git a/docs/docs/Develop/develop-application.md b/docs/docs/Develop/develop-application.md new file mode 100644 index 000000000..d35461076 --- /dev/null +++ b/docs/docs/Develop/develop-application.md @@ -0,0 +1,163 @@ +--- +title: Develop an application in Langflow +slug: /develop-application +--- + +Follow this guide to learn how to build an application using Langflow. +You'll learn how to set up a project directory, manage dependencies, configure environment variables, and package your Langflow application in a Docker image. + +To deploy your application to Docker or Kubernetes, see [Deployment](/deployment-docker). + +## Create a project directory + +Create a project directory similar to this one. + +```text +LANGFLOW-APPLICATION/ +├── flows/ +│ ├── flow1.json +│ └── flow2.json +├── langflow-config-dir/ +├── docker.env +├── Dockerfile +├── README.md +``` + +The `/flows` folder holds the flows you want to host. + +The `langflow-config-dir` is referenced in the Dockerfile as the location for Langflow's configuration files, database, and logs. For more information, see [Environment variables](/environment-variables). + +The `docker.env` file is copied to the Docker image as a `.env` file in the container root. This file controls Langflow's behavior, holds secrets, and configures runtime settings like authentication, database storage, API keys, and server configurations. + +The `Dockerfile` controls how your image is built. This file copies your flows and `docker.env` files to your image. + +### Package management + +The base Docker image includes the Langflow core dependencies by using `langflowai/langflow:latest` as the parent image. + +If your application requires additional dependencies, create a `pyproject.toml` file and add the dependencies to the file. For more information, see [Install custom dependencies](/install-custom-dependencies). + +To deploy the application with the additional dependencies to Docker, copy the `pyproject.toml` and `uv.lock` files to the Docker image by adding the following to the Dockerfile. + +```text +COPY pyproject.toml uv.lock /app/ +``` + +## Environment variables + +The `docker.env` file is a `.env` file loaded into your Docker image. + +The following example `docker.env` file defines auto-login behavior and which port to expose. Your environment may vary. For more information, see [Environment variables](/environment-variables). + +```text +LANGFLOW_AUTO_LOGIN=true +LANGFLOW_SAVE_DB_IN_CONFIG_DIR=true +LANGFLOW_BASE_URL=http://0.0.0.0:7860 +OPENAI_API_KEY=sk-... +``` + +This example uses Langflow's default [SQLite](https://www.sqlite.org/) database for storage, and configures no authentication. + +To modify Langflow's default memory behavior, see [Memory](/memory). + +To add authentication to your server, see [Authentication](/configuration-authentication). + +## Add flows and components + +Add your flow's `.JSON` files to the `/flows` folder. + +To export your flows from Langflow, see [Flows](/concepts-flows). + +Optionally, add any custom components to a `/components` folder, and specify the path in your `docker.env`. + +## Package your Langflow project in a Docker image + +1. Add the following commands to your Dockerfile. + +```dockerfile +# Use the latest version of langflow +FROM langflowai/langflow:latest + +# Create accessible folders and set the working directory in the container +RUN mkdir /app/flows +RUN mkdir /app/langflow-config-dir +WORKDIR /app + +# Copy the flows, optional components, and langflow-config-dir folders to the container +COPY flows /app/flows +COPY components /app/components +COPY langflow-config-dir /app/langflow-config-dir + +# copy docker.env file +COPY docker.env /app/.env + +# Set environment variables +ENV PYTHONPATH=/app +ENV LANGFLOW_LOAD_FLOWS_PATH=/app/flows +ENV LANGFLOW_CONFIG_DIR=/app/langflow-config-dir +ENV LANGFLOW_COMPONENTS_PATH=/app/components +ENV LANGFLOW_LOG_ENV=container + +# Command to run the server +EXPOSE 7860 +CMD ["langflow", "run", "--backend-only", "--env-file","/app/.env","--host", "0.0.0.0", "--port", "7860"] +``` + +The environment variables set in the Dockerfile specify resource paths and allow Langflow to access them. Values from `docker.env` override the values set in the Dockerfile. Additionally, logging behavior is set here with `ENV LANGFLOW_LOG_ENV=container` for serialized JSON to `stdout`, for tracking your application's behavior in a containerized environment. For more information on configuring logs, see [Logging](/logging). + +:::note +Optionally, remove the `--backend-only` flag from the startup command to start Langflow with the frontend enabled. +For more on `--backend-only` mode and the Langflow Docker image, see [Docker](/deployment-docker). +::: + +2. Save your Dockerfile. +3. Build the Docker image: +```bash +docker build -t langflow-pokedex:1.2.0 . +``` +4. Run the Docker container: +```bash +docker run -p 7860:7860 langflow-pokedex:1.2.0 +``` + +:::note +For instructions on building and pushing your image to Docker Hub, see [Docker](/deployment-docker). +::: + +5. Confirm the server is serving your flows. +Open a `.JSON` file in your `/flows` folder and find the file's `id` value. It's the first value in the flow document. + +```json +"id": "e4167236-938f-4aca-845b-21de3f399858", +``` + +6. Add the file's `id` value as the `flow-id` to a POST request to the `/run` endpoint. + +This command also uses a custom `session_id` value of `charizard_test_request`. +By default, session IDs use the `flow-id` value. +A custom session ID maintains a unique conversation thread, which keeps LLM contexts clean and can make debugging easier. +For more information, see [Session ID](/session-id). + +```bash +curl --request POST \ + --url 'http://127.0.0.1:7860/api/v1/run/e4167236-938f-4aca-845b-21de3f399858?stream=false' \ + --header 'Content-Type: application/json' \ + --data '{ + "input_value": "Tell me about Charizard please", + "output_type": "chat", + "input_type": "chat", + "session_id": "charizard_test_request" +}' +``` + +If the flow streams the result back to you, your flow is being served, and can be consumed from a front-end application by submitting POST requests to this endpoint. + +:::note +The test application returns a large amount of text, so the example command used `?stream=true`. If you prefer, set `?stream=false` to use batching. For more information, see the [API examples](/api-reference-api-examples#run-flow). +::: + +## Deploy to Docker Hub and Kubernetes + +For instructions on building and pushing your image to Docker Hub, see [Docker](/deployment-docker). + +To deploy your application to Kubernetes, see [Kubernetes](/deployment-kubernetes). \ No newline at end of file diff --git a/docs/docs/Develop/develop-overview.md b/docs/docs/Develop/develop-overview.md new file mode 100644 index 000000000..b2c800732 --- /dev/null +++ b/docs/docs/Develop/develop-overview.md @@ -0,0 +1,17 @@ +--- +title: About developing and configuring Langflow applications +slug: /develop-overview +--- + +The following pages provide information about how to develop and configure Langflow applications. + +The [Develop an application in Langflow](/develop-application) guide walks you through packaging and serving a flow, from your local development environment to a containerized application. +As you build your application, you will configure the following application behaviors. More detailed explanation is provided in the individual pages. + +• [Custom Dependencies](/install-custom-dependencies) - Add and manage additional Python packages and external dependencies in your Langflow projects. + +• [Memory and Storage](/memory) - Configure Langflow's storage and caching behavior. + +• [Session Management](/session-id) - Use session ID to manage communication between components. + +• [Logging](/logging) - Monitor and debug your Langflow applications. \ No newline at end of file diff --git a/docs/docs/Develop/install-custom-dependencies.md b/docs/docs/Develop/install-custom-dependencies.md new file mode 100644 index 000000000..27f840f6b --- /dev/null +++ b/docs/docs/Develop/install-custom-dependencies.md @@ -0,0 +1,76 @@ +--- +title: Install custom dependencies +slug: /install-custom-dependencies +--- + +To install custom dependencies in your Langflow environment, add them with your package manager. + +## Create a virtual environment for local testing + +When testing locally, use a virtual environment to isolate your dependencies and prevent conflicts with other Python projects. + +For example, if you want to experiment with `matplotlib` with Langflow: + +```bash +# Create and activate a virtual environment +uv venv YOUR_LANGFLOW_VENV +source YOUR_LANGFLOW_VENV/bin/activate + +# Install langflow and your additional dependency +uv pip install langflow matplotlib +``` + +If you're working within a cloned Langflow repository, add dependencies with `uv add` because there is already a `pyproject.toml` file for uv to reference. +```bash +uv add langflow matplotlib +``` + +## Add dependencies to the Langflow project + +When contributing to Langflow itself, add dependencies to the project's configuration. Langflow uses a workspace with two packages: + +* The `main` package (root level): For end-user features and main application code +* The `base` package (in `src/backend/base`): For core functionality and shared code + +Dependencies can be added in different groups: + +* Regular dependencies: Core functionality needed to run the package +* Development dependencies: Tools for testing, linting, or debugging are added in the `[dependency-groups.dev]` section +* Optional dependencies: Features that users can optionally install are added in the`[project.optional-dependencies]` + +There are three ways to add a package using make commands: + +* Add to main package dependencies (for end-user features): +```bash +make add main="matplotlib" +``` + +* Add to development tools (for testing, linting, debugging): +```bash +make add devel="matplotlib" +``` + +* Add to base package dependencies (for core functionality): +```bash +make add base="matplotlib" +``` + +You can also add these dependencies manually to the `pyproject.toml` file: + +``` +[project] +dependencies = [ + "matplotlib>=3.8.0" +] +``` + +* Or as an optional dependency: + +``` +[project.optional-dependencies] +plotting = [ + "matplotlib>=3.8.0", +] +``` + +The `make` commands add the dependency with `uv add` and update the `uv.lock` file in the appropriate location. \ No newline at end of file diff --git a/docs/docs/Develop/logging.md b/docs/docs/Develop/logging.md new file mode 100644 index 000000000..453208c1c --- /dev/null +++ b/docs/docs/Develop/logging.md @@ -0,0 +1,26 @@ +--- +title: Logging options in Langflow +slug: /logging +--- + +Langflow uses the `loguru` library for logging. + +The default `log_level` is `ERROR`. Other options are `DEBUG`, `INFO`, `WARNING`, and `CRITICAL`. + +The default logfile is called `langflow.log`, and its location depends on your operating system. + +* Linux/WSL: `\~/.cache/langflow/` +* macOS: `/Users/\/Library/Caches/langflow/` +* Windows: `%LOCALAPPDATA%\langflow\langflow\Cache` + +The `LANGFLOW_LOG_ENV` controls log output and formatting. The `container` option outputs serialized JSON to stdout. The `container_csv` option outputs CSV-formatted plain text to stdout. The `default` (or not set) logging option outputs prettified output with [RichHandler](https://rich.readthedocs.io/en/stable/reference/logging.html). + +To modify Langflow's logging configuration, add them to your `.env` file and start Langflow. + +```text +LANGFLOW_LOG_LEVEL=ERROR +LANGFLOW_LOG_FILE=path/to/logfile.log +LANGFLOW_LOG_ENV=container +``` + +To start Langflow with the values from your .env file, start Langflow with `uv run langflow run --env-file .env` \ No newline at end of file diff --git a/docs/docs/Develop/memory.md b/docs/docs/Develop/memory.md new file mode 100644 index 000000000..38f8dee35 --- /dev/null +++ b/docs/docs/Develop/memory.md @@ -0,0 +1,93 @@ +--- +title: Memory management options +slug: /memory +--- + +Langflow provides flexible memory management options for storage and retrieval. + +This page details the following memory configuration options in Langflow. + +- [Use local Langflow database tables](#local-langflow-database-tables) +- [Store messages in local memory](#store-messages-in-local-memory) +- [Configure external memory](#configure-external-memory) +- [Configure the external database connection](#configure-the-external-database-connection) +- [Configure cache memory](#configure-cache-memory) + +## Local Langflow database tables + +The default storage option in Langflow is a [SQLite](https://www.sqlite.org/) database located at `langflow/src/backend/base/langflow/langflow.db`. The following tables are stored in `langflow.db`: + +• **User** - Stores user account information including credentials, permissions, and profiles. For more information, see [Authentication](/configuration-authentication). + +• **Flow** - Contains flow configurations. For more information, see [Flows](/concepts-flows). + +• **Message** - Stores chat messages and interactions that occur between components. For more information, see [Message objects](/concepts-objects#message-object). + +• **Transaction** - Records execution history and results of flow runs. This information is used for [logging](/logging). + +• **ApiKey** - Manages API authentication keys for users. For more information, see [API keys](/configuration-api-keys). + +• **Folder** - Provides a structure for flow storage. For more information, see [Projects and folders](/concepts-overview#projects-and-folders). + +• **Variables** - Stores global encrypted values and credentials. For more information, see [Global variables](/configuration-global-variables). + +• **VertexBuild** - Tracks the build status of individual nodes within flows. For more information, see [Run a flow in the playground](/concepts-playground). + +For more information, see the database models in the [source code](https://github.com/langflow-ai/langflow/tree/main/src/backend/base/langflow/services/database/models). + +## Store messages in local memory + +To store messages in local Langflow memory, add a [Message store](/components-helpers#message-store) component to your flow. + +To retrieve messages from local Langflow memory, add a [Message history](/components-helpers#message-history) component to your flow. + +For an example of using local chat memory, see the [Memory chatbot](/tutorials-memory-chatbot) starter flow. + +To store or retrieve chat messages from external memory, connect the **External memory** port of the **Message store** or **Message history** component to a **Memory** component, like the [Astra DB chat memory](components-memories#astradbchatmemory-component) component. An example flow looks like this: + +![Sample Flow storing Chat Memory in AstraDB](/img/astra_db_chat_memory_rounded.png) + +If external storage is connected to a memory helper component, no chat messages are stored in local Langflow memory. + +## Configure external memory + +To replace the default Langflow SQLite database with another database, modify the `LANGFLOW_DATABASE_URL` and start Langflow with this value. + +``` +LANGFLOW_DATABASE_URL=postgresql://user:password@localhost:5432/langflow +``` + +For an example, see [Configure an external PostgreSQL database](/configuration-custom-database). + +## Configure the external database connection + +The following settings allow you to fine-tune your database connection pool and timeout settings: + +``` +LANGFLOW_DB_CONNECTION_SETTINGS='{"pool_size": 20, "max_overflow": 30, "pool_timeout": 30, "pool_pre_ping": true, "pool_recycle": 1800, "echo": false}' +LANGFLOW_DB_CONNECT_TIMEOUT=20 +``` + +- `pool_size`: Maximum number of database connections to keep in the pool (default: 20) +- `max_overflow`: Maximum number of connections that can be created beyond the pool_size (default: 30) +- `pool_timeout`: Number of seconds to wait before timing out on getting a connection from the pool (default: 30) +- `pool_pre_ping`: If true, the pool tests connections for liveness upon each checkout (default: true) +- `pool_recycle`: Number of seconds after which a connection is automatically recycled (default: 1800, or 30 minutes) +- `echo`: If true, SQL queries are logged for debugging purposes (default: false) +- `LANGFLOW_DB_CONNECT_TIMEOUT`: Maximum number of seconds to wait when establishing a new database connection (default: 20) + +## Configure cache memory + +Langflow provides multiple caching options that can be configured using the `LANGFLOW_CACHE_TYPE` environment variable. + +| Type | Description | Storage Location | Persistence | +|------|-------------|------------------|-------------| +| `async` (default) | Asynchronous in-memory cache | Application memory | Cleared on restart | +| `memory` | Thread-safe in-memory cache | Application memory | Cleared on restart | +| `disk` | File system-based cache | System cache directory* | Persists after restart | +| `redis` | Distributed cache | Redis server | Persists in Redis | + +*System cache directory locations: +- Linux/WSL: `~/.cache/langflow/` +- macOS: `/Users//Library/Caches/langflow/` +- Windows: `%LOCALAPPDATA%\langflow\langflow\Cache` \ No newline at end of file diff --git a/docs/docs/Develop/session-id.md b/docs/docs/Develop/session-id.md new file mode 100644 index 000000000..99aa0569d --- /dev/null +++ b/docs/docs/Develop/session-id.md @@ -0,0 +1,40 @@ +--- +title: Use session ID to manage communication between components +slug: /session-id +--- + +Session ID is a unique identifier for client/server connections. A single session equals the duration of a client's connection to a server. + +In the Langflow **Playground**, current sessions are listed on the left side of the pane. + +Langflow uses session IDs to track different chat interactions within flows. This allows multiple chat sessions to exist in a single flow. Messages are stored in the database with session IDs as a reference. + +This differentiation between users per session is helpful in managing client/server connections, but is also important in maintaining separate conversational contexts within a single flow. LLMs rely on past interactions to generate responses to queries, and if these conversations aren't separated, the responses becomes less useful, or even confused. + +## Customize session ID + +Custom session IDs can be set as part of the payload in API calls, or as advanced settings in individual components. The API session ID value takes precedence. If no session ID is specified, the flow ID is assigned. + +If you set a custom session ID in a payload, all downstream components use the upstream component's session ID value. + +``` +curl --request POST \ + --url 'http://127.0.0.1:7860/api/v1/run/$FLOW_ID' \ + --header 'Content-Type: application/json' \ + --data '{ + "input_value": "Hello", + "output_type": "chat", + "input_type": "chat", + "session_id": "my_custom_session_value" +}' +``` + +The `my_custom_session_value` value is used in components that accept it, and the stored messages from this flow are stored in `langflow.db` with their respective `session_id` values. + +## Retrieval of messages from memory by session ID + +Add a [Message store](/components-helpers#message-store) component to a flow to access the default `langflow.db` database. The component accepts `sessionID` as a filter parameter, and uses the session ID value from upstream automatically to retrieve message history by session ID from storage. + +Messages can be retrieved by `session_id` from the `/monitor` endpoint in the API. For more information, see the [API examples](https://docs.langflow.org/api-reference-api-examples#get-messages). + +For an example of session ID in action, see [Use Session IDs in Langflow](https://www.youtube.com/watch?v=nJiF_eF21MY). \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index 71d0371a1..57eb33b5e 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -85,6 +85,18 @@ module.exports = { "Configuration/configuration-security-best-practices" ], }, + { + type: "category", + label: "Develop", + items: [ + "Develop/develop-overview", + "Develop/develop-application", + "Develop/install-custom-dependencies", + "Develop/memory", + "Develop/session-id", + "Develop/logging", + ], + }, { type: "category", label: "Deployment",