@devries-cameron20 / composio Mirror · read-only / commits / b304cb0f5
Fork 0

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("<", "&lt;").replace(">", "&gt;")
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" },