AGENTS.md

1# AGENTS.md
2 
3This file provides guidance to AI coding agents when working with code in this repository.
4 
5## Project Overview
6 
7Langflow is a visual workflow builder for AI-powered agents. It has a Python/FastAPI backend, React/TypeScript frontend, and a lightweight executor CLI (lfx).
8 
9## Prerequisites
10 
11- **Python:** 3.10-3.14
12- **uv:** >=0.4 (Python package manager)
13- **Node.js:** >=20.19.0 (v22.12 LTS recommended)
14- **npm:** v10.9+
15- **make:** For build coordination
16 
17## Common Commands
18 
19### Development Setup
20```bash
21make init              # Install all dependencies + pre-commit hooks
22make run_cli           # Build and run Langflow (http://localhost:7860)
23make run_clic          # Clean build and run (use when frontend issues occur)
24```
25 
26### Development Mode (Hot Reload)
27```bash
28make backend           # FastAPI on port 7860 (terminal 1)
29make frontend          # Vite dev server on port 3000 (terminal 2)
30```
31 
32For component development, enable dynamic loading:
33```bash
34LFX_DEV=1 make backend                    # Load all components dynamically
35LFX_DEV=mistral,openai make backend       # Load only specific modules
36```
37 
38### Code Quality
39```bash
40make format_backend    # Format Python (ruff) - run FIRST before lint
41make format_frontend   # Format TypeScript (biome)
42make format            # Both
43make lint              # mypy type checking
44```
45 
46### Testing
47```bash
48make unit_tests                    # Backend unit tests (pytest, parallel)
49make unit_tests async=false        # Sequential tests
50uv run pytest path/to/test.py      # Single test file
51uv run pytest path/to/test.py::test_name  # Single test
52
53make test_frontend                 # Jest unit tests
54make tests_frontend                # Playwright e2e tests
55```
56 
57### Database Migrations
58```bash
59make alembic-revision message="Description"  # Create migration
60make alembic-upgrade                         # Apply migrations
61make alembic-downgrade                       # Rollback one version
62```
63 
64## Architecture
65 
66### Monorepo Structure
67```
68src/
69├── backend/
70│   ├── base/langflow/     # Core backend package (langflow-base)
71│   │   ├── api/           # FastAPI routes (v1/, v2/)
72│   │   ├── components/    # Built-in Langflow components
73│   │   ├── services/      # Service layer (auth, database, cache, etc.)
74│   │   ├── graph/         # Flow graph execution engine
75│   │   └── custom/        # Custom component framework
76│   └── tests/             # Backend tests
77├── frontend/              # React/TypeScript UI
78│   └── src/
79│       ├── components/    # UI components
80│       ├── stores/        # Zustand state management
81│       └── icons/         # Component icons
82├── langflow-core/         # Usable provider-free Langflow distribution
83├── bundles/               # Curated provider integrations
84└── lfx/                   # Lightweight executor and shared primitives
85```
86 
87### Key Packages
88- **langflow**: Full end-user package; depends on `langflow-core` and curated provider bundles
89- **langflow-core**: Service-complete, provider-bundle-free distribution; owns the `langflow` CLI
90- **langflow-base**: Modular application platform (API, services, graph engine); extras add service integrations
91- **lfx**: Shared execution primitives and standalone CLI (`lfx serve`, `lfx run`)
92 
93The public dependency direction is `langflow → langflow-core → langflow-base → lfx`.
94Provider packages under `src/bundles/` are added only by the full `langflow` distribution.
95 
96### Service Layer
97Backend services in `src/backend/base/langflow/services/`:
98- `auth/` - Authentication
99- `authorization/` - Authorization (RBAC) plugin layer — see below
100- `database/` - SQLAlchemy models and migrations
101- `cache/` - Caching layer
102- `storage/` - File storage
103- `tracing/` - Observability integrations
104 
105### Authorization (RBAC)
106 
107Authorization is a pluggable layer separate from authentication:
108 
109- **OSS** ships the interface (`BaseAuthorizationService` in `lfx`) + a pass-through implementation (`LangflowAuthorizationService`) + the `authz_*` and `casbin_rule` DB schema + route guards.
110- Implementations register via the `lfx.services` entry point `authorization_service` in `lfx.toml` (same pattern as the SSO `auth_service`). A registered plugin reads the `authz_*` admin tables and writes compiled rules to `casbin_rule`.
111 
112Default is **off**: `LANGFLOW_AUTHZ_ENABLED=false`. When enabled with only the OSS stub registered, every check returns allow — the stub is a no-op so routes stay wired and audit rows still flow. Real allow/deny requires a registered authorization plugin.
113 
114Route guards live in `langflow.services.authorization.guards` (the legacy `langflow.services.authorization.utils` path re-exports them for backward compatibility):
115- `ensure_flow_permission(user, FlowAction.*, flow_id=..., flow_user_id=..., workspace_id=..., folder_id=...)` — single-flow CRUD + execute
116- `ensure_deployment_permission(user, DeploymentAction.*, deployment_id=..., deployment_user_id=..., workspace_id=..., project_id=...)`
117- `ensure_project_permission(user, ProjectAction.*, project_id=..., project_user_id=..., workspace_id=...)`
118- `ensure_knowledge_base_permission(user, KnowledgeBaseAction.*, kb_name=..., kb_user_id=...)`
119- `ensure_variable_permission(user, VariableAction.*, variable_id=..., variable_user_id=...)`
120- `ensure_file_permission(user, FileAction.*, file_id=..., file_user_id=...)`
121- `ensure_share_permission(user, ShareAction.*, share_id=..., share_user_id=...)`
122- `filter_visible_resources(user, resource_type=..., candidates=..., act=...)` — list-endpoint filter; safe no-op in OSS
123 
124The enforcement request shape is `(subject, domain, object, action)`:
125- subject = `user:{uuid}`
126- domain = `project:{uuid}` → `workspace:{uuid}` → `*` (resolved by `_resolve_flow_domain`; the more specific domain wins so project-scoped grants match directly while workspace-scoped grants still flow down via plugin-side role inheritance)
127- object = `flow:{uuid}` / `deployment:{uuid}` / `project:{uuid}` / `flow:*` / etc.
128- action = `read` / `write` / `create` / `delete` / `execute` / `deploy`
129 
130**Share-aware fetch (Phase 3):** route fetch helpers (`_read_flow`, `get_flow_by_id_or_endpoint_name`, `get_deployment`, project reads in `projects.py`, v2 file fetcher, variable PATCH/DELETE in `variable.py`) branch on `BaseAuthorizationService.supports_cross_user_fetch()`. The OSS pass-through reports `False` so the existing owner-scoped queries are preserved — enabling `LANGFLOW_AUTHZ_ENABLED=true` without a registered plugin cannot widen visibility. Plugins set `SUPPORTS_CROSS_USER_FETCH=True` so resources load by id alone and `ensure_*_permission` decides access; route handlers can convert a plugin-deny `HTTPException(403)` to `HTTPException(404)` via `langflow.services.authorization.fetch.deny_to_404` to preserve UUID privacy.
131 
132**Share CRUD API (Phase 3):** `/api/v1/authz/shares` provides POST / GET / PATCH / DELETE on `authz_share` rows. The handler enforces an OSS floor (resource owner or superuser may administer shares for that resource) so the OSS pass-through cannot let a non-owner mint share rows. Each write fires `BaseAuthorizationService.invalidate_user` / `invalidate_all` so a registered enforcer can drop cached policy. Audit rows are written via `audit_decision` with `share:create` / `share:update` / `share:delete` actions.
133 
134**Audit query API (Phase 4):** `GET /api/v1/authz/audit` (superuser-only) exposes a paginated, filterable view of `authz_audit_log`. Supports `user_id`, `resource_type`, `resource_id`, `action`, `result`, `since`, `until` filters; page size capped at 200.
135 
136**Default role catalog (Phase 4):** the consolidated foundations migration `7c8d9e0f1a2b_authz_foundations` seeds the three built-in `is_system=True` roles (viewer / developer / admin) with `"{resource}:{action}"` permission slugs. OSS does not interpret these — they exist so a registered plugin's policy sync has a stable bootstrap source.
137 
138## Component Development
139 
140Components live in `src/backend/base/langflow/components/`. To add a new component:
141 
1421. Create component class inheriting from `Component`
1432. Define `display_name`, `description`, `icon`, `inputs`, `outputs`
1443. Add to `__init__.py` (alphabetical order)
1454. Run with `LFX_DEV=1 make backend` for hot reload
146 
147**IMPORTANT:** Changing a component's class name is a breaking change and should never be done. The class name serves as an identifier used to match components in saved flows and to flag them for updates in the UI. Renaming it will break existing flows that use that component.
148 
149### Component Structure
150```python
151from langflow.custom import Component
152from langflow.io import MessageTextInput, Output
153 
154class MyComponent(Component):
155    display_name = "My Component"
156    description = "What it does"
157    icon = "component-icon"  # Lucide icon name or custom
158 
159    inputs = [
160        MessageTextInput(name="input_value", display_name="Input"),
161    ]
162    outputs = [
163        Output(display_name="Output", name="output", method="process"),
164    ]
165 
166    def process(self) -> Message:
167        # Component logic
168        return Message(text=self.input_value)
169```
170 
171### Component Testing
172Tests go in `src/backend/tests/unit/components/`. Use base classes:
173- `ComponentTestBaseWithClient` - Components needing API access
174- `ComponentTestBaseWithoutClient` - Pure logic components
175 
176Required fixtures: `component_class`, `default_kwargs`, `file_names_mapping`
177 
178## Frontend Development
179 
180- **React 19** + TypeScript + Vite
181- **Zustand** for state management
182- **@xyflow/react** for graph visualization
183- **Tailwind CSS** for styling
184 
185### Custom Icons
1861. Create SVG component in `src/frontend/src/icons/YourIcon/`
1872. Export with `forwardRef` and `isDark` prop support
1883. Add to `lazyIconImports.ts`
1894. Set `icon = "YourIcon"` in Python component
190 
191## Testing Notes
192 
193- `@pytest.mark.api_key_required` - Tests requiring external API keys
194- `@pytest.mark.no_blockbuster` - Skip blockbuster plugin
195- Database tests may fail in batch but pass individually
196- Pre-commit hooks require `uv run git commit`
197- Always use `uv run` when running Python commands
198- When running tests inside a sub-package (e.g. `langflow-base`, `lfx`), sync that package's dev group first: `uv sync --group dev --package langflow-base`. The default `uv sync` only resolves the top-level workspace and may leave dev-only test deps (e.g. `fakeredis`) uninstalled.
199 
200### Graph Testing Pattern
201 
202Proper Graph tests follow this pattern:
2031. Build graph with connected components
2042. Connect them via `.set()` calls
2053. Call `async_start` and iterate over the results
2064. Validate the results
207 
208### Testing Best Practices
209 
210- Avoid mocking in tests when possible
211- Prefer real integrations for more reliable tests
212 
213## Version Management
214```bash
215make patch v=1.5.0  # Update version across all packages
216```
217 
218This updates: `pyproject.toml`, `src/backend/base/pyproject.toml`, `src/frontend/package.json`
219 
220## Pre-commit Workflow
221 
222Pre-commit hooks run ruff and biome automatically on `git commit`, so manual
223formatting is not required. To avoid an extra commit cycle when you have many
224changes:
225 
2261. Run `make format_backend` once before staging - fixes most ruff issues up front.
2272. Run `uv run git commit` (the `uv run` ensures pre-commit finds the right Python).
2283. If you touched backend code, run `make unit_tests` locally for faster feedback than CI.
229 
230## Pull Request Guidelines
231 
232- Follow [semantic commit conventions](https://www.conventionalcommits.org/)
233- Reference any issues fixed (e.g., `Fixes #1234`)
234- Ensure all tests pass before submitting
235 
236## Documentation
237 
238Documentation uses Docusaurus and lives in `docs/`:
239```bash
240cd docs
241yarn install
242yarn start        # Dev server on port 3000 (prompts for 3001 if 3000 is in use)
243```
244