Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 22:00 UTC
docs: update tool docs to add auth snippets as well as tool call snippets
balyan.sid@gmail.com committed
Jul 19, 2025 at 01:48 UTC
b304cb0f5d53c4b7c18f38e5e48e51798483db4d
24 files changed
+1049
-179
fern/generators/tool_doc_generator/main.py
+323
-154
@@ -49,8 +49,6 @@ IMPORTANT_TOOL_SLUGS = [
49
]
50
51
52
-
53
-
52
try:
53
from ruamel.yaml import YAML
54
@@ -66,15 +64,13 @@ except ImportError:
64
)
65
66
69
-
70
-
67
# Configure logging
68
logger = logging.getLogger(__name__)
69
70
71
class TelemetryFilter(logging.Filter):
72
"""Filter out telemetry-related log messages"""
77
-
73
+
74
def filter(self, record):
75
# Filter out telemetry-related messages
76
message = record.getMessage()
@@ -83,18 +79,18 @@ class TelemetryFilter(logging.Filter):
79
"telemetry",
80
"TELEMETRY",
81
"metrics/invocations",
86
- "errors"
82
+ "errors",
83
]
88
-
84
+
85
# Also filter by logger name
86
if "telemetry" in record.name.lower():
87
return False
92
-
88
+
89
# Filter by message content
90
for keyword in telemetry_keywords:
91
if keyword in message:
92
return False
97
-
93
+
94
return True
95
96
@@ -204,7 +200,7 @@ class DocumentContent:
200
self._blocks.extend(
201
[
202
"## Overview",
207
- f"### SLUG\n`{app_id.upper()}`",
203
+ f"**SLUG**: `{app_id.upper()}`",
204
f"### Description\n{sanitize_html(description)}",
205
]
206
)
@@ -221,81 +217,192 @@ class DocumentContent:
217
218
return self
219
224
- def _add_auth_schemes(self, auth_schemes: t.List[toolkit_retrieve_response.AuthConfigDetail]) -> None:
220
+ def add_connection_section(
221
+ self,
222
+ app_name: str,
223
+ app_slug: str,
224
+ auth_schemes: t.Optional[t.List[toolkit_retrieve_response.AuthConfigDetail]] = None,
225
+ ) -> None:
226
+ schemes = ", ".join(
227
+ self._get_auth_type(s) for s in (auth_schemes or []) if self._extract_auth_fields(s)
228
+ )
229
+ self._blocks.extend(
230
+ [
231
+ f"""## Connecting to {app_name}
232
+### Create an auth config
233
+Use the dashboard to create an auth config for the {app_name} toolkit. This allows you to connect multiple {app_name} accounts to Composio for agents to use.
234
+
235
+<Steps>
236
+ <Step title="Select App">
237
+ Navigate to the [{app_name} toolkit page](https://app.composio.dev/apps/{app_name}) and click **"Setup Integration"**.
238
+ </Step>
239
+ <Step title="Configure Auth Config Settings">
240
+ Select among the supported auth schemes of and configure them here.
241
+ </Step>
242
+ <Step title="Create and Get auth config ID">
243
+ Click **"Create Integration"**. After creation, **copy the displayed ID starting with `ac_`**. This is your auth config ID. This is _not_ a sensitive ID -- you can save it in environment variables or a database.
244
+ **This ID will be used to create connections to the toolkit for a given user.**
245
+ </Step>
246
+</Steps>
247
+"""
248
+ ],
249
+ )
250
+
251
+ # Add auth code snippets
252
+ self._add_auth_section(app_name, app_slug, auth_schemes)
253
+
254
+ def _add_auth_section(
255
+ self,
256
+ app_name: str,
257
+ app_slug: str,
258
+ auth_schemes: t.List[toolkit_retrieve_response.AuthConfigDetail] = None,
259
+ ) -> None:
260
+ """Add code snippets for each auth scheme using direct template processing"""
261
+ if not auth_schemes:
262
+ return
263
+
264
+ self._blocks.append("### Connect Your Account")
265
+
266
+ # Group auth schemes by type to avoid duplicates
267
+ seen_auth_types = set()
268
+
269
+ for scheme in auth_schemes:
270
+ # Get normalized auth type
271
+ auth_type_display = self._get_auth_type(scheme)
272
+ auth_type_key = auth_type_display.lower().replace(" ", "_")
273
+
274
+ # Skip if we've already shown this auth type or if it's no_auth
275
+ if auth_type_key in seen_auth_types or auth_type_key == "no_auth":
276
+ continue
277
+ seen_auth_types.add(auth_type_key)
278
+
279
+ # Add section for this auth type
280
+ self._blocks.append(f"#### Using {auth_type_display}")
281
+
282
+ # Prepare variables for template replacement
283
+ template_vars = {
284
+ "toolkit_name": app_name,
285
+ "toolkit_slug": app_slug.lower(),
286
+ "auth_config_id": f"ac_YOUR_{app_slug.upper()}_CONFIG_ID",
287
+ "user_id": "user@example.com",
288
+ "api_key_placeholder": f"your_{app_slug.lower()}_api_key",
289
+ "username_placeholder": f"your_{app_slug.lower()}_username",
290
+ "password_placeholder": f"your_{app_slug.lower()}_password",
291
+ "bearer_token_placeholder": f"your_{app_slug.lower()}_bearer_token"
292
+ }
293
+
294
+ try:
295
+ # Create code blocks using the new template method
296
+ python_block = MDX.as_code_block_from_template(
297
+ f"templates/python/{auth_type_key}.py",
298
+ template_vars=template_vars,
299
+ title="Python",
300
+ max_lines=40,
301
+ word_wrap=True
302
+ )
303
+
304
+ typescript_block = MDX.as_code_block_from_template(
305
+ f"templates/typescript/{auth_type_key}.ts",
306
+ template_vars=template_vars,
307
+ title="TypeScript",
308
+ max_lines=40,
309
+ word_wrap=True
310
+ )
311
+
312
+ # Add code blocks wrapped in CodeGroup
313
+ self._blocks.append(MDX.as_code_group(python_block, typescript_block))
314
+
315
+ except Exception as e:
316
+ logger.warning(f"Failed to process auth template for {auth_type_key}: {e}")
317
+ # Fallback to a simple message if template processing fails
318
+ self._blocks.append(f"*Authentication template for {auth_type_display} coming soon*")
319
+
320
+ def _add_auth_schemes(
321
+ self, auth_schemes: t.List[toolkit_retrieve_response.AuthConfigDetail]
322
+ ) -> None:
323
"""Add authentication schemes section."""
324
self._blocks.append("### Authentication Details")
227
-
325
+
326
for scheme in auth_schemes:
327
fields = self._extract_auth_fields(scheme)
328
if fields:
329
auth_type = self._get_auth_type(scheme)
330
self._blocks.append(MDX.as_accordion(auth_type, "\n".join(fields)))
331
234
- def _extract_auth_fields(self, scheme: toolkit_retrieve_response.AuthConfigDetail) -> t.List[str]:
332
+ def _extract_auth_fields(
333
+ self, scheme: toolkit_retrieve_response.AuthConfigDetail
334
+ ) -> t.List[str]:
335
"""Extract authentication fields from scheme."""
336
fields = []
237
-
238
- if hasattr(scheme, 'fields') and scheme.fields:
337
+
338
+ if hasattr(scheme, "fields") and scheme.fields:
339
for field in scheme.fields:
340
fields.extend(self._process_tuple_field(field))
241
-
242
-
341
+
342
return fields
343
344
def _process_tuple_field(self, field: tuple) -> t.List[str]:
345
"""Process tuple-style authentication field."""
346
fields = []
347
_, field_config = field
249
-
250
- for field_list, required in [(getattr(field_config, 'required', []), True),
251
- (getattr(field_config, 'optional', []), False)]:
348
+
349
+ for field_list, required in [
350
+ (getattr(field_config, "required", []), True),
351
+ (getattr(field_config, "optional", []), False),
352
+ ]:
353
for f in field_list:
253
- if hasattr(f, 'name'):
354
+ if hasattr(f, "name"):
355
fields.append(self._create_param_from_field(f, required))
255
-
356
+
357
return fields
358
258
- def _create_param_from_field(self, field: toolkit_retrieve_response.AuthConfigDetail, required: t.Optional[bool] = None) -> str:
359
+ def _create_param_from_field(
360
+ self, field: toolkit_retrieve_response.AuthConfigDetail, required: t.Optional[bool] = None
361
+ ) -> str:
362
"""Create parameter string from field object."""
363
return MDX.as_param(
364
name=str(field.name).replace('"', '\\"'),
262
- required=required if required is not None else getattr(field, 'required', False),
263
- typ=str(getattr(field, 'type', '')).replace('"', '\\"'),
264
- default=str(getattr(field, 'default', '')).replace('"', '\\"') if getattr(field, 'default', None) else "",
265
- doc=str(getattr(field, 'description', '')).replace('"', '\\"')
365
+ required=required if required is not None else getattr(field, "required", False),
366
+ typ=str(getattr(field, "type", "")).replace('"', '\\"'),
367
+ default=str(getattr(field, "default", "")).replace('"', '\\"')
368
+ if getattr(field, "default", None)
369
+ else "",
370
+ doc=str(getattr(field, "description", "")).replace('"', '\\"'),
371
)
372
373
def _get_auth_type(self, scheme: toolkit_retrieve_response.AuthConfigDetail) -> str:
374
"""Get authentication type from scheme."""
375
auth_type = (
271
- getattr(scheme, 'mode', None) or
272
- getattr(scheme, 'type', None) or
273
- getattr(scheme, 'auth_type', None) or
274
- getattr(scheme, 'auth_mode', None) or
275
- 'Authentication'
376
+ getattr(scheme, "mode", None)
377
+ or getattr(scheme, "type", None)
378
+ or getattr(scheme, "auth_type", None)
379
+ or getattr(scheme, "auth_mode", None)
380
+ or "Authentication"
381
)
277
-
382
+
383
auth_type_mapping = {
279
- 'oauth2': 'OAuth2',
280
- 'OAUTH2': 'OAuth2',
281
- 'api_key': 'API Key',
282
- 'API_KEY': 'API Key',
283
- 'bearer_token': 'Bearer Token',
284
- 'BEARER_TOKEN': 'Bearer Token',
285
- 'basic': 'Basic Auth',
286
- 'BASIC': 'Basic Auth',
287
- 'no_auth': 'No Authentication',
288
- 'NO_AUTH': 'No Authentication'
384
+ "oauth2": "OAuth2",
385
+ "OAUTH2": "OAuth2",
386
+ "api_key": "API Key",
387
+ "API_KEY": "API Key",
388
+ "bearer_token": "Bearer Token",
389
+ "BEARER_TOKEN": "Bearer Token",
390
+ "basic": "Basic Auth",
391
+ "BASIC": "Basic Auth",
392
+ "no_auth": "No Authentication",
393
+ "NO_AUTH": "No Authentication",
394
}
290
-
291
- return auth_type_mapping.get(auth_type, auth_type.replace('_', ' ').title())
395
293
- def add_actions(self, actions: t.List[Tool]) -> "DocumentContent":
396
+ return auth_type_mapping.get(auth_type, auth_type.replace("_", " ").title())
397
+
398
+ def add_actions(self, actions: t.List[Tool], app_name: str, app_slug: str) -> "DocumentContent":
399
"""
400
Add actions section to the document.
401
402
Args:
403
actions: List of tool models to document
404
+ app_name: The name of the application
405
+ app_slug: The application slug
406
407
Returns:
408
Self reference for method chaining
@@ -303,6 +410,66 @@ class DocumentContent:
410
# If this is the first action, add the Actions header
411
if not any("## Tools" in block for block in self._blocks):
412
self._blocks.append("## Tools")
413
+ self._blocks.append("### Executing tools")
414
+
415
+ # Prepare template variables
416
+ template_vars = {
417
+ "toolkit_name": app_name,
418
+ "toolkit_slug": app_slug.lower(),
419
+ "user_id": "user@example.com"
420
+ }
421
+
422
+ # Generate code blocks from templates
423
+ openai_block = MDX.as_code_block_from_template(
424
+ "templates/python/openai_tools.py",
425
+ template_vars=template_vars,
426
+ title="Python",
427
+ max_lines=40,
428
+ word_wrap=True
429
+ )
430
+
431
+ anthropic_block = MDX.as_code_block_from_template(
432
+ "templates/typescript/anthropic_tools.ts",
433
+ template_vars=template_vars,
434
+ title="TypeScript",
435
+ max_lines=40,
436
+ word_wrap=True
437
+ )
438
+
439
+ google_block = MDX.as_code_block_from_template(
440
+ "templates/python/google_tools.py",
441
+ template_vars=template_vars,
442
+ title="Python",
443
+ max_lines=40,
444
+ word_wrap=True
445
+ )
446
+
447
+ vercel_block = MDX.as_code_block_from_template(
448
+ "templates/typescript/vercel_tools.ts",
449
+ template_vars=template_vars,
450
+ title="TypeScript",
451
+ max_lines=40,
452
+ word_wrap=True
453
+ )
454
+
455
+ # Build the tabs with populated code blocks
456
+ self._blocks.append(
457
+ f"""<Tabs>
458
+<Tab title="OpenAI (Python)">
459
+{openai_block}
460
+</Tab>
461
+<Tab title="Anthropic (TypeScript)">
462
+{anthropic_block}
463
+</Tab>
464
+<Tab title="Google (Python)">
465
+{google_block}
466
+</Tab>
467
+<Tab title="Vercel (TypeScript)">
468
+{vercel_block}
469
+</Tab>
470
+</Tabs>"""
471
+ )
472
+ self._blocks.append("### Tool List")
473
474
action_contents = []
475
@@ -325,66 +492,70 @@ class DocumentContent:
492
def _process_tool(self, tool: Tool) -> t.Optional[str]:
493
"""Process a single tool and return accordion content."""
494
tool_data = self._extract_tool_data(tool)
328
- if not tool_data['name']:
495
+ if not tool_data["name"]:
496
return None
330
-
497
+
498
content = [
332
- f"**SLUG:** `{tool_data['slug']}`\n",
333
- MDX.as_code_block(tool_data['description'], "text")
499
+ f"**Tool Name:** {self._sanitize_action_name(tool_data['name'])}\n\n**Description**\n",
500
+ MDX.as_code_block(tool_data["description"], "text"),
501
]
335
-
502
+
503
# Add parameters
504
content.append("\n**Action Parameters**\n")
338
- content.append("\n".join(self._process_parameters(tool_data['params'])))
339
-
505
+ content.append("\n".join(self._process_parameters(tool_data["params"])))
506
+
507
# Add responses
508
content.append("\n**Action Response**\n")
342
- content.append("\n".join(self._process_parameters(tool_data['response'])))
343
-
344
- safe_name = self._sanitize_action_name(tool_data['name'])
345
- return MDX.as_accordion(safe_name, "\n".join(content))
509
+ content.append("\n".join(self._process_parameters(tool_data["response"])))
510
+
511
+ # safe_name = self._sanitize_action_name(tool_data['name'])
512
+ return MDX.as_accordion(tool_data["slug"], "\n".join(content))
513
514
def _extract_tool_data(self, tool: Tool) -> t.Dict[str, t.Any]:
515
"""Extract data from tool object or dict."""
516
517
return {
351
- 'name': tool.name or tool.slug,
352
- 'description': tool.description,
518
+ "name": tool.name or tool.slug,
519
+ "description": tool.description,
520
"slug": tool.slug,
354
- 'params': tool.input_parameters,
355
- 'response': tool.output_parameters
521
+ "params": tool.input_parameters,
522
+ "response": tool.output_parameters,
523
}
524
525
def _process_parameters(self, params: t.Any) -> t.List[str]:
526
"""Process parameters from various formats."""
527
if not params or not isinstance(params, dict):
528
return []
362
-
529
+
530
param_list = []
364
-
365
- if 'properties' in params:
366
- properties = params.get('properties', {})
367
- required = params.get('required', [])
368
-
531
+
532
+ if "properties" in params:
533
+ properties = params.get("properties", {})
534
+ required = params.get("required", [])
535
+
536
for name, schema in properties.items():
370
- param_list.append(MDX.as_param(
371
- name=name,
372
- typ=str(schema.get("type", "")),
373
- doc=sanitize_html(schema.get("description", "")),
374
- default=schema.get("default", ""),
375
- required=name in required
376
- ))
377
- else:
378
- for name, schema in params.items():
379
- if isinstance(schema, dict):
380
- param_list.append(MDX.as_param(
537
+ param_list.append(
538
+ MDX.as_param(
539
name=name,
540
typ=str(schema.get("type", "")),
541
doc=sanitize_html(schema.get("description", "")),
542
default=schema.get("default", ""),
385
- required=schema.get("required", False)
386
- ))
387
-
543
+ required=name in required,
544
+ )
545
+ )
546
+ else:
547
+ for name, schema in params.items():
548
+ if isinstance(schema, dict):
549
+ param_list.append(
550
+ MDX.as_param(
551
+ name=name,
552
+ typ=str(schema.get("type", "")),
553
+ doc=sanitize_html(schema.get("description", "")),
554
+ default=schema.get("default", ""),
555
+ required=schema.get("required", False),
556
+ )
557
+ )
558
+
559
return param_list
560
561
def _sanitize_action_name(self, name: str) -> str:
@@ -394,12 +565,12 @@ class DocumentContent:
565
(r"<(\d+)", r"less than \1"),
566
(r">(\d+)", r"greater than \1"),
567
(r"<=(\d+)", r"less than or equal to \1"),
397
- (r">=(\d+)", r"greater than or equal to \1")
568
+ (r">=(\d+)", r"greater than or equal to \1"),
569
]
570
for pattern, replacement in replacements:
571
name = re.sub(pattern, replacement, name)
572
name = name.replace("<", "<").replace(">", ">")
402
-
573
+
574
return name
575
576
def __str__(self) -> str:
@@ -432,7 +603,9 @@ class ToolDocGenerator:
603
self.generated_tools = []
604
self.problematic_actions = []
605
435
- def generate_docs(self, output_path: Path, max_workers: int | None = None, limit: int | None = None) -> None:
606
+ def generate_docs(
607
+ self, output_path: Path, max_workers: int | None = None, limit: int | None = None
608
+ ) -> None:
609
"""
610
Generate documentation for all apps in parallel.
611
@@ -446,12 +619,12 @@ class ToolDocGenerator:
619
620
# Get all apps
621
toolkits = self.composio.toolkits.get()
449
-
622
+
623
# Apply limit if specified
624
if limit is not None:
625
toolkits = toolkits[:limit]
626
logger.info(f"Limited to first {limit} toolkits")
454
-
627
+
628
logger.info(f"Starting documentation generation for {len(toolkits)} toolkits")
629
630
# Track failures with a synchronized list
@@ -501,7 +674,9 @@ class ToolDocGenerator:
674
else:
675
logger.info(f"\nSuccessfully generated docs for all {len(toolkits)} toolkits!")
676
504
- logger.info(f"Generated {success_count} toolkit docs in parallel using {max_workers} workers")
677
+ logger.info(
678
+ f"Generated {success_count} toolkit docs in parallel using {max_workers} workers"
679
+ )
680
681
# Update docs.yml with the generated tools
682
self.update_docs_yml(output_path.parent / "docs.yml")
@@ -518,12 +693,11 @@ class ToolDocGenerator:
693
toolkit_model = self.composio.toolkits.get(slug=toolkit.slug)
694
tools = self.composio.tools.get_raw_composio_tools(toolkits=[toolkit.slug], limit=99999)
695
logger.info(f"Toolkit tools: {toolkit}")
521
-
522
-
696
+
697
logger.info(f"Retrieved {len(tools)} tools for {toolkit.name}")
698
if tools:
699
logger.debug(f"First tool type: {type(tools[0])}")
526
- if hasattr(tools[0], '__dict__'):
700
+ if hasattr(tools[0], "__dict__"):
701
logger.debug(f"First tool attributes: {list(tools[0].__dict__.keys())}")
702
elif isinstance(tools[0], dict):
703
logger.debug(f"First tool dict keys: {list(tools[0].keys())}")
@@ -536,10 +710,14 @@ class ToolDocGenerator:
710
category = None
711
if toolkit_model.meta.categories:
712
# Use the first category if multiple exist
539
- category = toolkit_model.meta.categories[0].get('name') if isinstance(toolkit_model.meta.categories[0], dict) else getattr(toolkit_model.meta.categories[0], 'name', None)
540
-
713
+ category = (
714
+ toolkit_model.meta.categories[0].get("name")
715
+ if isinstance(toolkit_model.meta.categories[0], dict)
716
+ else getattr(toolkit_model.meta.categories[0], "name", None)
717
+ )
718
+
719
# Add frontmatter
542
- content.add_frontmatter(titleize(toolkit.name), category)
720
+ content.add_frontmatter(toolkit.name, category)
721
722
# Handle auth schemes safely
723
auth_schemes = None
@@ -549,42 +727,46 @@ class ToolDocGenerator:
727
logger.info(f"Could not process auth schemes for {toolkit.name}: {e}")
728
# Continue without auth schemes
729
552
-
730
no_auth = "NO_AUTH" in (toolkit.auth_schemes or [])
731
732
logger.info(f"No auth: {no_auth}")
733
557
-
558
-
734
# Add overview section
735
+ # For no-auth tools, don't pass auth_schemes to avoid showing authentication details
736
content.add_overview_section(
737
app_name=toolkit.name,
738
app_id=toolkit.slug,
739
description=toolkit.meta.description,
564
- auth_schemes=auth_schemes,
740
+ auth_schemes=None if no_auth else auth_schemes,
741
)
742
743
+ # Only add connection section if authentication is required
744
+ if not no_auth:
745
+ content.add_connection_section(
746
+ app_name=toolkit.name, app_slug=toolkit.slug, auth_schemes=auth_schemes
747
+ )
748
+
749
# Filter out problematic actions
750
filtered_tools = []
751
for tool in tools:
752
# Extract tool slug for filtering
753
if isinstance(tool, dict):
572
- if 'function' in tool:
573
- tool_slug = tool['function'].get('name', '')
754
+ if "function" in tool:
755
+ tool_slug = tool["function"].get("name", "")
756
else:
575
- tool_slug = tool.get('slug', '')
757
+ tool_slug = tool.get("slug", "")
758
else:
577
- tool_slug = getattr(tool, 'slug', '')
578
-
759
+ tool_slug = getattr(tool, "slug", "")
760
+
761
if tool_slug not in self.problematic_actions:
762
filtered_tools.append(tool)
763
else:
764
logger.info(f"Filtered out problematic tool: {tool_slug}")
583
-
765
+
766
logger.info(f"After filtering: {len(filtered_tools)} tools remaining out of {len(tools)}")
585
-
767
+
768
# Add actions section (only the filtered ones)
587
- content.add_actions(filtered_tools)
769
+ content.add_actions(filtered_tools, app_name=toolkit.name, app_slug=toolkit.slug)
770
771
# Write to file
772
filename = f"{toolkit.slug.lower()}.mdx"
@@ -630,10 +812,13 @@ class ToolDocGenerator:
812
proxy_apps = []
813
no_auth_tools = []
814
categories: dict[str, list] = {}
633
-
815
816
for tool in sorted_tools:
636
- entry = {"page": tool["display_name"], "slug": "tools/" + tool["name"], "path": tool["path"]}
817
+ entry = {
818
+ "page": tool["display_name"],
819
+ "slug": "tools/" + tool["name"],
820
+ "path": tool["path"],
821
+ }
822
name = tool["name"]
823
category = tool.get("category", "").strip()
824
@@ -659,14 +844,12 @@ class ToolDocGenerator:
844
845
# Sort categories by number of elements (descending), then by name
846
sorted_categories = sorted(
662
- categories.items(),
663
- key=lambda item: (-len(item[1]), item[0])
847
+ categories.items(), key=lambda item: (-len(item[1]), item[0])
848
)
849
850
logger.info(f"Category keys: {list(categories.keys())}")
851
logger.info(f"Sorted categories keys: {[cat for cat, _ in sorted_categories]}")
852
669
-
853
# Find the "tools" tab section in the navigation structure
854
for tab_section in docs_data.get("navigation", []):
855
if tab_section.get("tab") == "tools":
@@ -678,21 +861,44 @@ class ToolDocGenerator:
861
862
# Add Important section if present
863
if important_tools:
681
- new_layout.append({"section": "Important", "skip-slug": True, "contents": important_tools, })
682
-
864
+ new_layout.append(
865
+ {
866
+ "section": "Important",
867
+ "skip-slug": True,
868
+ "contents": important_tools,
869
+ }
870
+ )
871
872
# Add each category as its own section
873
for cat, tools_list in sorted_categories:
874
if tools_list:
687
- new_layout.append({"section": titleize(cat), "skip-slug": True, "contents": tools_list, })
875
+ new_layout.append(
876
+ {
877
+ "section": titleize(cat),
878
+ "skip-slug": True,
879
+ "contents": tools_list,
880
+ }
881
+ )
882
883
# Add Proxy Apps section if present
884
if proxy_apps:
691
- new_layout.append({"section": "Proxy Apps", "skip-slug": True, "contents": proxy_apps, })
885
+ new_layout.append(
886
+ {
887
+ "section": "Proxy Apps",
888
+ "skip-slug": True,
889
+ "contents": proxy_apps,
890
+ }
891
+ )
892
893
# Add No Auth section if present
894
if no_auth_tools:
695
- new_layout.append({"section": "No Auth", "skip-slug": True, "contents": no_auth_tools, })
895
+ new_layout.append(
896
+ {
897
+ "section": "No Auth",
898
+ "skip-slug": True,
899
+ "contents": no_auth_tools,
900
+ }
901
+ )
902
903
logger.info("new_layout: %s", new_layout)
904
tab_section["layout"] = new_layout
@@ -726,11 +932,11 @@ def configure_logging(log_level: str) -> None:
932
format="%(asctime)s - %(levelname)s - %(message)s",
933
datefmt="%Y-%m-%d %H:%M:%S",
934
)
729
-
935
+
936
# Add telemetry filter to root logger to filter out telemetry requests
937
telemetry_filter = TelemetryFilter()
938
logging.getLogger().addFilter(telemetry_filter)
733
-
939
+
940
# Also add filter to specific loggers that might handle HTTP requests
941
for logger_name in ["httpx", "urllib3", "requests"]:
942
logging.getLogger(logger_name).addFilter(telemetry_filter)
@@ -814,42 +1020,5 @@ def cli_main() -> int:
1020
return 1
1021
1022
817
-def generate_tool_docs(
818
- output_dir,
819
- config=None,
820
- include_local=False,
821
- log_level="info",
822
- workers=None,
823
- lint_only=False,
824
- no_lint=False,
825
- limit=None
826
-):
827
- """
828
- Generate tool documentation
829
-
830
- Args:
831
- output_dir: Path to output directory
832
- config: Optional path to config file
833
- include_local: Whether to include local development tools
834
- log_level: Logging level (debug, info, warning, error, critical)
835
- workers: Number of parallel worker threads
836
- lint_only: Only lint existing MDX files without generating new ones
837
- no_lint: Skip the linting step when generating documentation
838
- limit: Limit processing to first N toolkits (for debugging)
839
- """
840
- # Configure logging
841
- configure_logging(log_level)
842
-
843
- # Create generator
844
- generator = ToolDocGenerator(include_local=include_local)
845
-
846
- # Generate docs with specified number of workers
847
- generator.generate_docs(output_dir, max_workers=workers, limit=limit)
848
-
849
- # Force exit immediately without waiting for background telemetry
850
- logger.info("Documentation generation complete. Exiting immediately.")
851
- os._exit(0)
852
-
853
-
1023
if __name__ == "__main__":
1024
sys.exit(cli_main())
fern/generators/tool_doc_generator/mdx_formatter.py
+227
-4
@@ -7,6 +7,10 @@ This module provides utilities for formatting MDX content for Composio tool docu
7
import re
8
import typing as t
9
from dataclasses import dataclass
10
+from pathlib import Path
11
+import logging
12
+
13
+logger = logging.getLogger(__name__)
14
15
16
class MDX:
@@ -34,6 +38,7 @@ class MDX:
38
frontmatter += f'\nsubtitle: "Learn how to use {app_name} with Composio"'
39
if category is not None:
40
frontmatter += f'\ncategory: "{category}"'
41
+ frontmatter += f'\nimage: "https://og.composio.dev/api/og?title=Using%20{app_name}%20with%20Composio"'
42
return "---\n" + frontmatter + "\n---\n"
43
44
@staticmethod
@@ -201,18 +206,236 @@ class MDX:
206
return f'<AccordionGroup>\n{content}\n</AccordionGroup>\n'
207
208
@staticmethod
204
- def as_code_block(content: str, language: str = "python") -> str:
209
+ def as_code_block(
210
+ content: str,
211
+ language: str = "python",
212
+ display_name: str = None,
213
+ highlight_lines: str = None, # e.g., "25-30" or "5"
214
+ title: str = None,
215
+ max_lines: int = None,
216
+ word_wrap: bool = True
217
+ ) -> str:
218
"""
206
- Format content as a code block using backticks.
219
+ Format content as a code block using backticks with full formatting support.
220
221
Args:
222
content: The code to be displayed
210
- language: The programming language for syntax highlighting
223
+ language: The programming language for syntax highlighting (e.g., "python", "typescript")
224
+ display_name: Display name for the language tab (deprecated - use title instead)
225
+ highlight_lines: Lines to highlight (e.g., "25-30" or "5")
226
+ title: Title for the code block (e.g., "Python", "TypeScript")
227
+ max_lines: Maximum number of lines to display
228
+ word_wrap: Whether to wrap long lines
229
+
230
+ Returns:
231
+ Formatted code block MDX string with all attributes
232
+ """
233
+ # Build the code fence header
234
+ header_parts = [language]
235
+
236
+ # Add line highlighting if provided
237
+ if highlight_lines:
238
+ header_parts.append(f"{{{highlight_lines}}}")
239
+
240
+ # Add title if provided (use display_name as fallback)
241
+ title_to_use = title or display_name
242
+ if title_to_use:
243
+ # Escape quotes in title
244
+ safe_title = title_to_use.replace('"', '\\"')
245
+ header_parts.append(f'title="{safe_title}"')
246
+
247
+ # Add max lines if provided
248
+ if max_lines:
249
+ header_parts.append(f"maxLines={max_lines}")
250
+
251
+ # Add word wrap if enabled (default is True)
252
+ if word_wrap:
253
+ header_parts.append("wordWrap")
254
+
255
+ # Join all parts with spaces
256
+ header = " ".join(header_parts)
257
+
258
+ return f"```{header}\n{content}\n```\n"
259
+
260
+ @staticmethod
261
+ def as_code_group(*code_blocks: str) -> str:
262
+ """
263
+ Wrap multiple code blocks in a CodeGroup component.
264
+
265
+ Args:
266
+ *code_blocks: Variable number of code block strings
267
+
268
+ Returns:
269
+ Formatted CodeGroup MDX string containing all code blocks
270
+ """
271
+ return f"<CodeGroup>\n{''.join(code_blocks)}</CodeGroup>\n"
272
+
273
+ @staticmethod
274
+ def _replace_template_variables(content: str, variables: dict) -> str:
275
+ """
276
+ Replace {{variable}} patterns with their values, supporting transformations.
277
+
278
+ Supports patterns like:
279
+ - {{variable}}
280
+ - {{variable|upper}}
281
+ - {{variable|lower}}
282
+ - {{variable|title}}
283
+ - {{variable|default:'fallback value'}}
284
+
285
+ Args:
286
+ content: Template content with {{variable}} placeholders
287
+ variables: Dictionary of variable names to values
288
+
289
+ Returns:
290
+ Content with variables replaced
291
+ """
292
+ def replace_var(match):
293
+ var_name = match.group(1)
294
+ transform = match.group(2)
295
+ default = match.group(3)
296
+
297
+ # Get the value or use default
298
+ value = variables.get(var_name)
299
+ if value is None:
300
+ value = default.strip("'\"") if default else match.group(0)
301
+ else:
302
+ value = str(value)
303
+
304
+ # Apply transformation if specified
305
+ if transform:
306
+ if transform == 'upper':
307
+ value = value.upper()
308
+ elif transform == 'lower':
309
+ value = value.lower()
310
+ elif transform == 'title':
311
+ value = value.capitalize()
312
+
313
+ return value
314
+
315
+ # Pattern matches: {{var_name|transform|default:'value'}}
316
+ pattern = r'\{\{(\w+)(?:\|(\w+))?(?:\|default:[\'"]([^\'"]*)[\'"])?\}\}'
317
+ return re.sub(pattern, replace_var, content)
318
+
319
+ @staticmethod
320
+ def _read_template_file(template_path: str, base_path: t.Optional[Path] = None) -> str:
321
+ """
322
+ Read a template file.
323
+
324
+ Args:
325
+ template_path: Path to template file (can be relative)
326
+ base_path: Base path to resolve relative paths from (defaults to current file's parent)
327
+
328
+ Returns:
329
+ Template content as string
330
+ """
331
+ if base_path is None:
332
+ # Default to the directory containing this file's parent (tool_doc_generator)
333
+ base_path = Path(__file__).parent
334
+
335
+ # Resolve the full path
336
+ if Path(template_path).is_absolute():
337
+ full_path = Path(template_path)
338
+ else:
339
+ full_path = base_path / template_path
340
+
341
+ try:
342
+ with open(full_path, 'r', encoding='utf-8') as f:
343
+ return f.read()
344
+ except FileNotFoundError:
345
+ logger.warning(f"Template not found: {full_path}")
346
+ return f"# Template not found: {template_path}"
347
+
348
+ @staticmethod
349
+ def _detect_language_from_path(file_path: str) -> str:
350
+ """
351
+ Detect programming language from file extension.
352
+
353
+ Args:
354
+ file_path: Path to the file
355
+
356
+ Returns:
357
+ Language identifier for syntax highlighting
358
+ """
359
+ extension_map = {
360
+ '.py': 'python',
361
+ '.js': 'javascript',
362
+ '.ts': 'typescript',
363
+ '.tsx': 'typescript',
364
+ '.jsx': 'javascript',
365
+ '.java': 'java',
366
+ '.cpp': 'cpp',
367
+ '.c': 'c',
368
+ '.go': 'go',
369
+ '.rs': 'rust',
370
+ '.php': 'php',
371
+ '.rb': 'ruby',
372
+ '.swift': 'swift',
373
+ '.kt': 'kotlin',
374
+ '.scala': 'scala',
375
+ '.sh': 'bash',
376
+ '.yml': 'yaml',
377
+ '.yaml': 'yaml',
378
+ '.json': 'json',
379
+ '.xml': 'xml',
380
+ '.html': 'html',
381
+ '.css': 'css',
382
+ '.scss': 'scss',
383
+ '.sql': 'sql',
384
+ }
385
+
386
+ suffix = Path(file_path).suffix.lower()
387
+ return extension_map.get(suffix, 'text')
388
+
389
+ @staticmethod
390
+ def as_code_block_from_template(
391
+ template_path: str,
392
+ template_vars: dict = None,
393
+ language: str = None,
394
+ display_name: str = None,
395
+ highlight_lines: str = None,
396
+ title: str = None,
397
+ max_lines: int = None,
398
+ word_wrap: bool = True,
399
+ base_path: t.Optional[Path] = None
400
+ ) -> str:
401
+ """
402
+ Create a code block from a template file with variable replacement.
403
+
404
+ Args:
405
+ template_path: Path to template file (relative to base_path)
406
+ template_vars: Dictionary of variables to replace in template
407
+ language: Override auto-detected language (e.g., "python", "typescript")
408
+ display_name: Display name for the language tab (deprecated - use title instead)
409
+ highlight_lines: Lines to highlight (e.g., "25-30" or "5")
410
+ title: Title for the code block (e.g., "Python", "TypeScript")
411
+ max_lines: Maximum number of lines to display
412
+ word_wrap: Whether to wrap long lines
413
+ base_path: Base path for resolving template_path
414
415
Returns:
416
Formatted code block MDX string
417
"""
215
- return f"```{language} wordWrap\n{content}\n```\n"
418
+ # Read template file
419
+ content = MDX._read_template_file(template_path, base_path)
420
+
421
+ # Replace variables if provided
422
+ if template_vars:
423
+ content = MDX._replace_template_variables(content, template_vars)
424
+
425
+ # Auto-detect language from file extension if not provided
426
+ if not language:
427
+ language = MDX._detect_language_from_path(template_path)
428
+
429
+ # Use existing as_code_block with all formatting
430
+ return MDX.as_code_block(
431
+ content=content,
432
+ language=language,
433
+ display_name=display_name,
434
+ highlight_lines=highlight_lines,
435
+ title=title,
436
+ max_lines=max_lines,
437
+ word_wrap=word_wrap
438
+ )
439
440
@staticmethod
441
def as_markdown_table(headers: list, rows: list) -> str:
fern/generators/tool_doc_generator/templates/python/api_key.py
new
+32
@@ -0,0 +1,32 @@
1
+from composio import Composio
2
+from composio.types import auth_scheme
3
+
4
+# Replace these with your actual values
5
+{{toolkit_slug}}_auth_config_id = "{{auth_config_id|default:'ac_YOUR_AUTH_CONFIG_ID'}}" # Auth config ID created above
6
+user_id = "0000-0000-0000" # UUID from database/app
7
+
8
+composio = Composio()
9
+
10
+def authenticate_toolkit(user_id: str, auth_config_id: str):
11
+ # Replace this with a method to retrieve an API key from the user.
12
+ # Or supply your own.
13
+ user_api_key = input("[!] Enter API key")
14
+
15
+ connection_request = composio.connected_accounts.initiate(
16
+ user_id=user_id,
17
+ auth_config_id=auth_config_id,
18
+ config={"auth_scheme": "API_KEY", "val": user_api_key}
19
+ )
20
+
21
+ # API Key authentication is immediate - no redirect needed
22
+ print(f"Successfully connected {{toolkit_name}} for user {user_id}")
23
+ print(f"Connection status: {connection_request.status}")
24
+
25
+ return connection_request.id
26
+
27
+
28
+connection_id = authenticate_toolkit(user_id, {{toolkit_slug}}_auth_config_id)
29
+
30
+# You can verify the connection using:
31
+connected_account = composio.connected_accounts.get(connection_id)
32
+print(f"Connected account: {connected_account}")
\ No newline at end of file
fern/generators/tool_doc_generator/templates/python/basic_auth.py
new
+26
@@ -0,0 +1,26 @@
1
+from composio import Composio
2
+from composio.types import auth_scheme
3
+
4
+# Replace these with your actual values
5
+{{toolkit_slug}}_auth_config_id = "{{auth_config_id|default:'ac_YOUR_AUTH_CONFIG_ID'}}"
6
+user_id = "{{user_id|default:'user@example.com'}}"
7
+username = "{{username_placeholder|default:'your_username'}}"
8
+password = "{{password_placeholder|default:'your_password'}}"
9
+
10
+composio = Composio()
11
+
12
+# Create a new connected account for {{toolkit_name}} using Basic Auth
13
+connection_request = composio.connected_accounts.initiate(
14
+ user_id=user_id,
15
+ auth_config_id={{toolkit_slug}}_auth_config_id,
16
+ config=auth_scheme.basic_auth(
17
+ username=username,
18
+ password=password
19
+ )
20
+)
21
+
22
+# Basic authentication is immediate - no redirect needed
23
+print(f"Successfully connected {{toolkit_name}} for user {user_id}")
24
+
25
+# You can verify the connection using:
26
+# connected_account = composio.connected_accounts.get(user_id=user_id, app_id="{{toolkit_slug|upper}}")
\ No newline at end of file
fern/generators/tool_doc_generator/templates/python/bearer_token.py
new
+31
@@ -0,0 +1,31 @@
1
+from composio import Composio
2
+from composio.types import auth_scheme
3
+
4
+# Auth config ID created above
5
+{{toolkit_slug}}_auth_config_id = "{{auth_config_id|default:'ac_YOUR_AUTH_CONFIG_ID'}}"
6
+
7
+# UUID from database/application
8
+user_id = "0000-0000-0000"
9
+
10
+composio = Composio()
11
+
12
+
13
+def authenticate_toolkit(user_id: str, auth_config_id: str):
14
+ # Replace this with a method to retrieve the Bearer Token from the user.
15
+ bearer_token = input("[!] Enter bearer token")
16
+ connection_request = composio.connected_accounts.initiate(
17
+ user_id=user_id,
18
+ auth_config_id=auth_config_id,
19
+ config={"auth_scheme": "BEARER_TOKEN", "val": bearer_token}
20
+ )
21
+ print(f"Successfully connected {{toolkit_name}} for user {user_id}")
22
+ print(f"Connection status: {connection_request.status}")
23
+
24
+ return connection_request.id
25
+
26
+
27
+connection_id = authenticate_toolkit(user_id, {{toolkit_slug}}_auth_config_id)
28
+
29
+# You can verify the connection using:
30
+connected_account = composio.connected_accounts.get(connection_id)
31
+print(f"Connected account: {connected_account}")
\ No newline at end of file
fern/generators/tool_doc_generator/templates/python/google_tools.py
new
+25
@@ -0,0 +1,25 @@
1
+from composio import Composio
2
+from composio_google import GoogleProvider
3
+from google import genai
4
+from google.genai import types
5
+
6
+# Create composio client
7
+composio = Composio(provider=GoogleProvider())
8
+# Create google client
9
+client = genai.Client()
10
+
11
+# User ID must be a valid UUID format
12
+user_id = "0000-0000-0000" # Replace with actual user UUID from your database
13
+
14
+# Get tools for {{toolkit_name}}
15
+tools = composio.tools.get(user_id, toolkits=["{{toolkit_slug|upper}}"])
16
+
17
+print("[!] Tools:", tools)
18
+
19
+# Create genai client config
20
+config = types.GenerateContentConfig(tools=tools)
21
+
22
+# Use the chat interface
23
+chat = client.chats.create(model="gemini-2.0-flash", config=config)
24
+response = chat.send_message("What can you do with {{toolkit_name}}?")
25
+print("[!] Response:", response.text)
\ No newline at end of file
fern/generators/tool_doc_generator/templates/python/oauth2.py
new
+30
@@ -0,0 +1,30 @@
1
+from composio import Composio
2
+from composio.types import auth_scheme
3
+
4
+# Replace these with your actual values
5
+{{toolkit_slug}}_auth_config_id = "{{auth_config_id|default:'ac_YOUR_AUTH_CONFIG_ID'}}" # Auth config ID created above
6
+user_id = "0000-0000-0000" # UUID from database/application
7
+
8
+composio = Composio()
9
+
10
+
11
+def authenticate_toolkit(user_id: str, auth_config_id: str):
12
+ connection_request = composio.connected_accounts.initiate(
13
+ user_id=user_id,
14
+ auth_config_id=auth_config_id,
15
+ )
16
+
17
+ print(
18
+ f"Visit this URL to authenticate {{toolkit_name}}: {connection_request.redirect_url}"
19
+ )
20
+
21
+ # This will wait for the auth flow to be completed
22
+ connection_request.wait_for_connection(timeout=15)
23
+ return connection_request.id
24
+
25
+
26
+connection_id = authenticate_toolkit(user_id, {{toolkit_slug}}_auth_config_id)
27
+
28
+# You can also verify the connection status using:
29
+connected_account = composio.connected_accounts.get(connection_id)
30
+print(f"Connected account: {connected_account}")
\ No newline at end of file
fern/generators/tool_doc_generator/templates/python/openai_tools.py
new
+33
@@ -0,0 +1,33 @@
1
+from composio import Composio
2
+from openai import OpenAI
3
+import json
4
+
5
+openai = OpenAI()
6
+composio = Composio()
7
+
8
+# User ID must be a valid UUID format
9
+user_id = "0000-0000-0000" # Replace with actual user UUID from your database
10
+
11
+tools = composio.tools.get(user_id=user_id, toolkits=["{{toolkit_slug|upper}}"])
12
+
13
+print("[!] Tools:")
14
+print(json.dumps(tools))
15
+
16
+def invoke_llm(task = "What can you do?"):
17
+ completion = openai.chat.completions.create(
18
+ model="gpt-4o",
19
+ messages=[
20
+ {
21
+ "role": "user",
22
+ "content": task, # Your task here!
23
+ },
24
+ ],
25
+ tools=tools,
26
+ )
27
+
28
+ # Handle Result from tool call
29
+ result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30
+ print(f"[!] Completion: {completion}")
31
+ print(f"[!] Tool call result: {result}")
32
+
33
+invoke_llm()
\ No newline at end of file
fern/generators/tool_doc_generator/templates/typescript/anthropic_tools.ts
new
+38
@@ -0,0 +1,38 @@
1
+import { Composio } from '@composio/core';
2
+import { AnthropicProvider } from '@composio/anthropic';
3
+import { Anthropic } from '@anthropic-ai/sdk';
4
+
5
+const composio = new Composio({
6
+ provider: new AnthropicProvider({
7
+ cacheTools: false, // default
8
+ }),
9
+});
10
+
11
+const anthropic = new Anthropic();
12
+
13
+// User ID must be a valid UUID format
14
+const userId = "0000-0000-0000"; // Replace with actual user UUID from your database
15
+
16
+// Get tools for {{toolkit_name}}
17
+const tools = await composio.tools.get(userId, {
18
+ toolkits: ["{{toolkit_slug|upper}}"],
19
+});
20
+
21
+console.log("[!] Tools:", tools);
22
+
23
+// Create a message with the tools
24
+const msg = await anthropic.messages.create({
25
+ model: 'claude-3-5-sonnet-20240620',
26
+ messages: [
27
+ {
28
+ role: 'user',
29
+ content: 'What can you do with {{toolkit_name}}?', // Your task here!
30
+ },
31
+ ],
32
+ tools: tools,
33
+ max_tokens: 1000,
34
+});
35
+
36
+// Handle tool calls if any
37
+const result = await composio.provider.handleToolCalls(userId, msg);
38
+console.log("[!] Result:", result);
\ No newline at end of file
fern/generators/tool_doc_generator/templates/typescript/api_key.ts
new
+38
@@ -0,0 +1,38 @@
1
+import { Composio } from '@composio/core';
2
+
3
+// Replace these with your actual values
4
+const {{toolkit_slug}}_auth_config_id = "{{auth_config_id|default:'ac_YOUR_AUTH_CONFIG_ID'}}"; // Auth config ID created above
5
+const userId = "{{user_id|default:'user@example.com'}}"; // User ID from database/application
6
+
7
+const composio = new Composio();
8
+
9
+async function authenticateToolkit(userId: string, authConfigId: string) {
10
+ // TODO: Replace this with a method to retrieve the API key from the user.
11
+ // In production, this should be securely retrieved from your database or user input.
12
+ // For example: const userApiKey = await getUserApiKey(userId);
13
+ const userApiKey = "{{api_key_placeholder|default:'your_api_key_here'}}"; // Replace with actual API key
14
+
15
+ const connectionRequest = await composio.connectedAccounts.initiate({
16
+ userId: userId,
17
+ authConfigId: authConfigId,
18
+ config: {
19
+ authScheme: "API_KEY",
20
+ config: {
21
+ api_key: userApiKey
22
+ }
23
+ }
24
+ });
25
+
26
+ // API Key authentication is immediate - no redirect needed
27
+ console.log(`Successfully connected {{toolkit_name}} for user ${userId}`);
28
+ console.log(`Connection status: ${connectionRequest.status}`);
29
+
30
+ return connectionRequest.id;
31
+}
32
+
33
+// Authenticate the toolkit
34
+const connectionId = await authenticateToolkit(userId, {{toolkit_slug}}_auth_config_id);
35
+
36
+// You can verify the connection using:
37
+const connectedAccount = await composio.connectedAccounts.get(connectionId);
38
+console.log("Connected account:", connectedAccount);
\ No newline at end of file
fern/generators/tool_doc_generator/templates/typescript/basic_auth.ts
new
+40
@@ -0,0 +1,40 @@
1
+import { Composio } from '@composio/core';
2
+
3
+// Replace these with your actual values
4
+const {{toolkit_slug}}_auth_config_id = "{{auth_config_id|default:'ac_YOUR_AUTH_CONFIG_ID'}}"; // Auth config ID created above
5
+const userId = "{{user_id|default:'user@example.com'}}"; // User ID from database/application
6
+
7
+const composio = new Composio();
8
+
9
+async function authenticateToolkit(userId: string, authConfigId: string) {
10
+ // TODO: Replace these with a method to retrieve credentials from the user.
11
+ // In production, these should be securely retrieved from your database or user input.
12
+ // For example: const { username, password } = await getUserCredentials(userId);
13
+ const username = "{{username_placeholder|default:'your_username'}}"; // Replace with actual username
14
+ const password = "{{password_placeholder|default:'your_password'}}"; // Replace with actual password
15
+
16
+ const connectionRequest = await composio.connectedAccounts.initiate({
17
+ userId: userId,
18
+ authConfigId: authConfigId,
19
+ config: {
20
+ authScheme: "BASIC",
21
+ config: {
22
+ username: username,
23
+ password: password
24
+ }
25
+ }
26
+ });
27
+
28
+ // Basic authentication is immediate - no redirect needed
29
+ console.log(`Successfully connected {{toolkit_name}} for user ${userId}`);
30
+ console.log(`Connection status: ${connectionRequest.status}`);
31
+
32
+ return connectionRequest.id;
33
+}
34
+
35
+// Authenticate the toolkit
36
+const connectionId = await authenticateToolkit(userId, {{toolkit_slug}}_auth_config_id);
37
+
38
+// You can verify the connection using:
39
+const connectedAccount = await composio.connectedAccounts.get(connectionId);
40
+console.log("Connected account:", connectedAccount);
\ No newline at end of file
fern/generators/tool_doc_generator/templates/typescript/bearer_token.ts
new
+38
@@ -0,0 +1,38 @@
1
+import { Composio } from '@composio/core';
2
+
3
+// Replace these with your actual values
4
+const {{toolkit_slug}}_auth_config_id = "{{auth_config_id|default:'ac_YOUR_AUTH_CONFIG_ID'}}"; // Auth config ID created above
5
+const userId = "{{user_id|default:'user@example.com'}}"; // User ID from database/application
6
+
7
+const composio = new Composio();
8
+
9
+async function authenticateToolkit(userId: string, authConfigId: string) {
10
+ // TODO: Replace this with a method to retrieve the Bearer Token from the user.
11
+ // In production, this should be securely retrieved from your database or user input.
12
+ // For example: const bearerToken = await getUserBearerToken(userId);
13
+ const bearerToken = "{{bearer_token_placeholder|default:'your_bearer_token_here'}}"; // Replace with actual bearer token
14
+
15
+ const connectionRequest = await composio.connectedAccounts.initiate({
16
+ userId: userId,
17
+ authConfigId: authConfigId,
18
+ config: {
19
+ authScheme: "BEARER_TOKEN",
20
+ config: {
21
+ token: bearerToken
22
+ }
23
+ }
24
+ });
25
+
26
+ // Bearer token authentication is immediate - no redirect needed
27
+ console.log(`Successfully connected {{toolkit_name}} for user ${userId}`);
28
+ console.log(`Connection status: ${connectionRequest.status}`);
29
+
30
+ return connectionRequest.id;
31
+}
32
+
33
+// Authenticate the toolkit
34
+const connectionId = await authenticateToolkit(userId, {{toolkit_slug}}_auth_config_id);
35
+
36
+// You can verify the connection using:
37
+const connectedAccount = await composio.connectedAccounts.get(connectionId);
38
+console.log("Connected account:", connectedAccount);
\ No newline at end of file
fern/generators/tool_doc_generator/templates/typescript/oauth2.ts
new
+28
@@ -0,0 +1,28 @@
1
+import { Composio } from '@composio/core';
2
+
3
+// Replace these with your actual values
4
+const {{toolkit_slug}}_auth_config_id = "{{auth_config_id|default:'ac_YOUR_AUTH_CONFIG_ID'}}"; // Auth config ID created above
5
+const userId = "{{user_id|default:'user@example.com'}}"; // User ID from database/application
6
+
7
+const composio = new Composio();
8
+
9
+async function authenticateToolkit(userId: string, authConfigId: string) {
10
+ const connectionRequest = await composio.connectedAccounts.initiate({
11
+ userId: userId,
12
+ authConfigId: authConfigId,
13
+ });
14
+
15
+ console.log(`Visit this URL to authenticate {{toolkit_name}}: ${connectionRequest.redirectUrl}`);
16
+
17
+ // This will wait for the auth flow to be completed
18
+ await connectionRequest.waitForConnection(60);
19
+
20
+ return connectionRequest.id;
21
+}
22
+
23
+// Authenticate the toolkit
24
+const connectionId = await authenticateToolkit(userId, {{toolkit_slug}}_auth_config_id);
25
+
26
+// You can also verify the connection status using:
27
+const connectedAccount = await composio.connectedAccounts.get(connectionId);
28
+console.log("Connected account:", connectedAccount);
\ No newline at end of file
fern/generators/tool_doc_generator/templates/typescript/vercel_tools.ts
new
+34
@@ -0,0 +1,34 @@
1
+import { Composio } from '@composio/core';
2
+import { generateText } from 'ai';
3
+import { anthropic } from '@ai-sdk/anthropic';
4
+import { VercelProvider } from '@composio/vercel';
5
+
6
+const composio = new Composio({
7
+ apiKey: process.env.COMPOSIO_API_KEY,
8
+ provider: new VercelProvider(),
9
+});
10
+
11
+// User ID must be a valid UUID format
12
+const userId = "0000-0000-0000"; // Replace with actual user UUID from your database
13
+
14
+// Get tools for {{toolkit_name}}
15
+const tools = await composio.tools.get(userId, {
16
+ toolkits: ["{{toolkit_slug|upper}}"]
17
+});
18
+
19
+console.log("[!] Tools:", tools);
20
+
21
+// Generate text with tools
22
+const { text } = await generateText({
23
+ model: anthropic('claude-3-7-sonnet-20250219'),
24
+ messages: [
25
+ {
26
+ role: 'user',
27
+ content: "What can you do with {{toolkit_name}}?", // Your task here!
28
+ },
29
+ ],
30
+ tools,
31
+ maxSteps: 3,
32
+});
33
+
34
+console.log("[!] Result:", text);
\ No newline at end of file
fern/package.json
+1
-1
@@ -18,7 +18,7 @@
18
"snippets:dev": "bun watch scripts/build-snippets.ts --watch",
19
"add-og": "uv run scripts/add_og_imgs.py",
20
"check": "fern check",
21
- "dev": "bun run scripts/build-snippets.ts --watch & fern docs dev",
21
+ "dev": "fern docs dev",
22
"links": "fern docs broken-links",
23
"build": "echo 'Build orchestrated by Turbo'",
24
"preview": "fern generate --docs --preview --log-level debug",
fern/pages/src/examples/gmail-filterer.mdx
+1
-1
@@ -1,7 +1,7 @@
1
---
2
title: AI Gmail Labeller
3
subtitle: "A Python app that uses your custom LLM prompt to label your Gmail!"
4
-image: "https://og.composio.dev/api/og?title=Full%20Stack%20Chat%20App" # image for socials
4
+image: "https://og.composio.dev/api/og?title=AI%20Gmail%20Labeller" # image for socials
5
keywords: ''
6
hide-nav-links: false
7
---
fern/pages/src/get-started/welcome.mdx
+1
-1
@@ -1,6 +1,6 @@
1
---
2
title: Welcome to Composio
3
-image: 'https://og.composio.dev/api/og?title=Welcome%20to%20Composio' # image for socials
3
+image: "https://og.composio.dev/api/og?title=Welcome%20to%20Composio" # image for socials
4
keywords: ''
5
# subtitle: 'Our API and SDKs enable developers to build AI applications and experiences that are a step above the rest.'
6
hide-nav-links: false
fern/pages/src/mcp/developers.mdx
+1
-1
@@ -1,7 +1,7 @@
1
---
2
title: MCP Servers for developers
3
subtitle: "Guide to create and manage MCP servers"
4
-image: "https://og.composio.dev/api/og?title=Composio%20MCP%20Servers" # image for socials
4
+image: "https://og.composio.dev/api/og?title=MCP%20Servers%20for%20developers" # image for socials
5
keywords: ""
6
hide-nav-links: true
7
---
fern/pages/src/providers/google.mdx
+1
-1
@@ -1,7 +1,7 @@
1
---
2
title: Google Gen AI Provider
3
slug: /providers/google
4
-image: "https://og.composio.dev/api/og?title=Google%20Provider" # image for socials
4
+image: "https://og.composio.dev/api/og?title=Google%20Gen%20AI%20Provider" # image for socials
5
keywords: ""
6
hide-nav-links: false
7
---
fern/pages/src/providers/openai.mdx
+1
-1
@@ -54,7 +54,7 @@ Chat Completion API is the industry standard for building LLM-powered applicatio
54
<CodeGroup>
55
<SnippetCode
56
src="fern/snippets/providers/python/openai-provider.py"
57
- startLine={10}
57
+ startLine={9}
58
endLine={24}
59
/>
60
<SnippetCode
fern/pages/src/providers/py-custom.mdx
+1
-1
@@ -1,6 +1,6 @@
1
---
2
title: Python custom provider
3
-image: "https://og.composio.dev/api/og?title=Python%20Custom%20Provider" # image for socials
3
+image: "https://og.composio.dev/api/og?title=Python%20custom%20provider" # image for socials
4
keywords: ""
5
hide-nav-links: false
6
---
fern/scripts/build-snippets.ts
+82
-1
@@ -40,6 +40,7 @@ interface SnippetCodeProps {
40
relativeHighlightStart?: number;
41
relativeHighlightEnd?: number;
42
path?: string;
43
+ vars?: Record<string, string>;
44
}
45
46
// Parse GitHub URL and extract components
@@ -142,6 +143,40 @@ function ensureDistDir() {
143
fs.mkdirSync(PAGES_DIST_DIR, { recursive: true });
144
}
145
146
+// Replace template variables in content
147
+function replaceTemplateVariables(content: string, vars: Record<string, string> = {}): string {
148
+ // Replace {{variable}} patterns with their values
149
+ return content.replace(/\{\{(\w+)(?:\|(\w+)(?::([^}]+))?)?\}\}/g, (match, varName, transform, defaultValue) => {
150
+ let value = vars[varName];
151
+
152
+ // Use default value if variable not found
153
+ if (value === undefined || value === null) {
154
+ if (defaultValue !== undefined) {
155
+ value = defaultValue.replace(/^["']|["']$/g, ''); // Remove quotes from default value
156
+ } else {
157
+ return match; // Keep original placeholder if no value and no default
158
+ }
159
+ }
160
+
161
+ // Apply transformations
162
+ if (transform) {
163
+ switch (transform.toLowerCase()) {
164
+ case 'lower':
165
+ value = value.toLowerCase();
166
+ break;
167
+ case 'upper':
168
+ value = value.toUpperCase();
169
+ break;
170
+ case 'title':
171
+ value = value.charAt(0).toUpperCase() + value.slice(1).toLowerCase();
172
+ break;
173
+ }
174
+ }
175
+
176
+ return value;
177
+ });
178
+}
179
+
180
function getLanguageFromPath(filePath: string): { syntax: string; displayName: string } {
181
const extension = filePath.split('.').pop()?.toLowerCase();
182
const languageMap: Record<string, { syntax: string; displayName: string }> = {
@@ -185,6 +220,30 @@ function readFileLines(
220
// If the path starts with './' or '../', resolve it relative to the context directory
221
if (filePath.startsWith('./') || filePath.startsWith('../')) {
222
fullPath = path.resolve(contextDir, filePath);
223
+ } else if (filePath.startsWith('fern/')) {
224
+ // For paths starting with 'fern/', we need to find the actual fern directory
225
+ // The MDX file might be in tools/, pages/dist/, etc., but we want to resolve
226
+ // relative to the actual fern directory
227
+
228
+ // Try multiple possible locations for the fern directory
229
+ const possiblePaths = [
230
+ path.resolve(PROJECT_ROOT, '..', filePath), // composio1/fern/...
231
+ path.resolve(PROJECT_ROOT, filePath), // Already in fern/...
232
+ path.resolve(contextDir, '..', '..', filePath), // Relative to context
233
+ ];
234
+
235
+ // Find the first path that exists
236
+ for (const possiblePath of possiblePaths) {
237
+ if (fs.existsSync(possiblePath)) {
238
+ fullPath = possiblePath;
239
+ break;
240
+ }
241
+ }
242
+
243
+ if (!fullPath) {
244
+ // If none found, use the most likely path
245
+ fullPath = path.resolve(PROJECT_ROOT, '..', filePath);
246
+ }
247
} else {
248
// Otherwise, resolve it relative to the project root
249
fullPath = path.resolve(PROJECT_ROOT, filePath);
@@ -198,7 +257,7 @@ function readFileLines(
257
258
return lines.slice(start, end).join('\n');
259
} catch (error) {
201
- console.warn(`⚠️ Failed to read file: ${filePath}`, error);
260
+ console.warn(`⚠️ Failed to read file: ${filePath} (resolved to: ${fullPath})`, error);
261
return `// File not found: ${filePath}`;
262
}
263
}
@@ -285,6 +344,23 @@ async function parseSnippetCodeTags(content: string, contextDir: string): Promis
344
relativeHighlightEndMatch[1] || relativeHighlightEndMatch[2]
345
);
346
347
+ // Extract vars object prop
348
+ const varsMatch = propsString.match(/vars=\{({[^}]*})\}/);
349
+ if (varsMatch) {
350
+ try {
351
+ // Parse the vars object - need to handle JSX syntax
352
+ const varsString = varsMatch[1];
353
+ // Convert JSX object syntax to JSON
354
+ const jsonString = varsString
355
+ .replace(/(\w+):/g, '"$1":') // Add quotes around keys
356
+ .replace(/:\s*"([^"]+)"/g, ':"$1"') // Ensure values are quoted
357
+ .replace(/:\s*'([^']+)'/g, ':"$1"'); // Convert single quotes to double
358
+ props.vars = JSON.parse(`{${jsonString}}`);
359
+ } catch (error) {
360
+ console.warn(`⚠️ Failed to parse vars prop: ${varsMatch[1]}`);
361
+ }
362
+ }
363
+
364
// Extract wordWrap boolean prop
365
const wordWrapMatch = propsString.match(/wordWrap=(?:["']?(true|false)["']?|{(true|false)})/);
366
if (wordWrapMatch) {
@@ -331,6 +407,11 @@ async function parseSnippetCodeTags(content: string, contextDir: string): Promis
407
filePath = props.src!;
408
langInfo = getLanguageFromPath(filePath);
409
}
410
+
411
+ // Apply variable replacements if vars are provided
412
+ if (props.vars && Object.keys(props.vars).length > 0) {
413
+ codeContent = replaceTemplateVariables(codeContent, props.vars);
414
+ }
415
} catch (error) {
416
const errorMessage = error instanceof SnippetCodeError ? error.message : `Unexpected error: ${error.message}`;
417
console.error(`❌ SnippetCode Error: ${errorMessage}`);
fern/turbo.json
+8
-4
@@ -8,8 +8,13 @@
8
"cache": true
9
},
10
11
+ "dev:deps": {
12
+ "dependsOn": ["api:pull", "add-og", "sdkdocs", "tools:generate:dev", "snippets:build"],
13
+ "cache": false
14
+ },
15
+
16
"dev": {
12
- "dependsOn": ["api:pull", "sdkdocs", "tools:generate:dev", "snippets:build"],
17
+ "dependsOn": ["dev:deps"],
18
"persistent": true,
19
"cache": false
20
},
@@ -20,7 +25,6 @@
25
},
26
27
"add-og": {
23
- "dependsOn": ["^build"],
28
"inputs": ["scripts/add_og_imgs.py", "pages/**/*.mdx"],
29
"cache": false
30
},
@@ -39,13 +43,13 @@
43
44
"tools:generate": {
45
"outputs": ["tools/**"],
42
- "inputs": ["generators/tool_doc_generator/**/*.py"],
46
+ "inputs": ["generators/tool_doc_generator/**/*.py", "generators/tool_doc_generator/templates/**/*"],
47
"cache": true,
48
"env": ["COMPOSIO_API_KEY"]
49
},
50
"tools:generate:dev": {
51
"cache": false,
48
- "inputs": ["generators/tool_doc_generator/**/*.py"],
52
+ "inputs": ["generators/tool_doc_generator/**/*.py", "generators/tool_doc_generator/templates/**/*"],
53
"env": ["COMPOSIO_API_KEY", "LIMIT"]
54
},
55
uv.lock
+9
-9
@@ -467,7 +467,7 @@ wheels = [
467
468
[[package]]
469
name = "composio"
470
-version = "1.0.0rc9"
470
+version = "1.0.0rc10"
471
source = { virtual = "python" }
472
dependencies = [
473
{ name = "composio-client" },
@@ -514,7 +514,7 @@ dev = [
514
515
[[package]]
516
name = "composio-anthropic"
517
-version = "1.0.0rc9"
517
+version = "1.0.0rc10"
518
source = { virtual = "python/providers/anthropic" }
519
dependencies = [
520
{ name = "anthropic" },
@@ -546,7 +546,7 @@ wheels = [
546
547
[[package]]
548
name = "composio-crewai"
549
-version = "1.0.0rc9"
549
+version = "1.0.0rc10"
550
source = { virtual = "python/providers/crewai" }
551
dependencies = [
552
{ name = "composio" },
@@ -561,7 +561,7 @@ requires-dist = [
561
562
[[package]]
563
name = "composio-gemini"
564
-version = "1.0.0rc9"
564
+version = "1.0.0rc10"
565
source = { virtual = "python/providers/gemini" }
566
dependencies = [
567
{ name = "composio" },
@@ -576,7 +576,7 @@ requires-dist = [
576
577
[[package]]
578
name = "composio-google"
579
-version = "1.0.0rc9"
579
+version = "1.0.0rc10"
580
source = { virtual = "python/providers/google" }
581
dependencies = [
582
{ name = "composio" },
@@ -591,7 +591,7 @@ requires-dist = [
591
592
[[package]]
593
name = "composio-google-adk"
594
-version = "1.0.0rc9"
594
+version = "1.0.0rc10"
595
source = { virtual = "python/providers/google_adk" }
596
dependencies = [
597
{ name = "composio" },
@@ -606,7 +606,7 @@ requires-dist = [
606
607
[[package]]
608
name = "composio-langchain"
609
-version = "1.0.0rc9"
609
+version = "1.0.0rc10"
610
source = { virtual = "python/providers/langchain" }
611
dependencies = [
612
{ name = "composio" },
@@ -621,7 +621,7 @@ requires-dist = [
621
622
[[package]]
623
name = "composio-openai"
624
-version = "1.0.0rc9"
624
+version = "1.0.0rc10"
625
source = { virtual = "python/providers/openai" }
626
dependencies = [
627
{ name = "composio" },
@@ -636,7 +636,7 @@ requires-dist = [
636
637
[[package]]
638
name = "composio-openai-agents"
639
-version = "1.0.0rc9"
639
+version = "1.0.0rc10"
640
source = { virtual = "python/providers/openai_agents" }
641
dependencies = [
642
{ name = "composio" },