fastworkflow 2.17.5__tar.gz → 2.17.7__tar.gz

{fastworkflow-2.17.5 → fastworkflow-2.17.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastworkflow
-Version: 2.17.5
+Version: 2.17.7
 Summary: A framework for rapidly building large-scale, deterministic, interactive workflows with a fault-tolerant, conversational UX
 License: Apache-2.0
 Keywords: fastworkflow,ai,workflow,llm,openai

{fastworkflow-2.17.5 → fastworkflow-2.17.7}/fastworkflow/chat_session.py

@@ -467,15 +467,28 @@ class ChatSession:
             self
         )
 
+        # Get available commands for current context and pass to agent.
+        # The CommandsSystemPreludeAdapter will inject these commands into the system 
+        # message, keeping them out of the trajectory to avoid token bloat while still 
+        # providing context-specific command info.
+        from fastworkflow.workflow_agent import _what_can_i_do
+        available_commands = _what_can_i_do(self)
+
         lm = dspy_utils.get_lm("LLM_AGENT", "LITELLM_API_KEY_AGENT")
         from dspy.utils.exceptions import AdapterParseError
+        from fastworkflow.utils.chat_adapter import CommandsSystemPreludeAdapter
+        
+        # Use CommandsSystemPreludeAdapter specifically for workflow agent calls
+        agent_adapter = CommandsSystemPreludeAdapter()
+        
         # Retry logic for AdapterParseError
         max_retries = 2
         for attempt in range(max_retries):
             try:
-                with dspy.context(lm=lm, adapter=dspy.ChatAdapter()):
+                with dspy.context(lm=lm, adapter=agent_adapter):
                     agent_result = self._workflow_tool_agent(
-                        user_query=command_info_and_refined_message_with_todolist
+                        user_query=command_info_and_refined_message_with_todolist,
+                        available_commands=available_commands
                     )
                 break  # Success, exit retry loop
             except AdapterParseError as _:

{fastworkflow-2.17.5 → fastworkflow-2.17.7}/fastworkflow/run_fastapi_mcp/README.md

@@ -47,12 +47,41 @@ Configure in your environment (loaded at process startup via CLI args or env loa
 | Variable | Description | Required | Default |
 |----------|-------------|----------|---------|
 | `SPEEDDICT_FOLDERNAME` | Base folder for workflow contexts and conversation storage | Yes | - |
+| `--expect_encrypted_jwt` | Enable full JWT signature verification (pass flag to require signed tokens) | No | False (no verification by default) |
 
 Notes:
 - Conversation DBs are stored under `SPEEDDICT_FOLDERNAME/user_conversations` (directory is auto-created).
 - `/conversations` now accepts a `limit` query parameter (default `20`).
 - Shutdown waits up to 30 seconds for active turns (hard-coded).
 
+## JWT Verification Modes
+
+### Default Behavior: No Signature Verification
+By default, the service does NOT verify JWT signatures, accepting unsigned tokens for trusted internal networks where JWT is used purely for data transport:
+
+```bash
+uvicorn services.run_fastapi.main:app --workflow_path /path/to/workflow
+```
+
+**Use cases** (no verification):
+- Controlled internal networks with network-level security
+- Systems where JWT carries non-sensitive routing information
+- Trusted environments where data transport is the primary concern
+
+The service logs a warning on startup when running in this mode.
+
+### Secure Mode: Enable Signature Verification
+For production deployments requiring full RSA signature verification:
+
+```bash
+uvicorn services.run_fastapi.main:app --workflow_path /path/to/workflow --expect_encrypted_jwt
+```
+
+**Secure mode** (with `--expect_encrypted_jwt` flag):
+- JWT tokens are cryptographically verified using RSA signatures
+- Tokens without valid signatures are rejected
+- Recommended for production deployments in untrusted environments
+
 ## API Endpoints (REST)
 
 ### `POST /initialize`

{fastworkflow-2.17.5 → fastworkflow-2.17.7}/fastworkflow/run_fastapi_mcp/__main__.py

@@ -61,6 +61,7 @@ from .jwt_manager import (
     create_access_token,
     create_refresh_token,
     verify_token,
+    set_jwt_verification_mode,
     JWT_ACCESS_TOKEN_EXPIRE_MINUTES
 )
 
@@ -148,6 +149,9 @@ async def lifespan(_app: FastAPI):
         if ARGS.passwords_file_path:
             env_vars.update(dotenv_values(ARGS.passwords_file_path))
         fastworkflow.init(env_vars=env_vars)
+        
+        # Configure JWT verification mode based on CLI parameter
+        set_jwt_verification_mode(ARGS.expect_encrypted_jwt)
 
     async def _active_turn_user_ids() -> list[str]:
         active: list[str] = []
@@ -219,6 +223,8 @@ def load_args():
     parser.add_argument("--project_folderpath", required=False)
     parser.add_argument("--port", type=int, default=8000, help="Port to run the server on (default: 8000)")
     parser.add_argument("--host", default="0.0.0.0", help="Host to bind the server to (default: 0.0.0.0)")
+    parser.add_argument("--expect_encrypted_jwt", action="store_true", default=False,
+                       help="Enable JWT signature verification (default: unsigned tokens accepted for trusted networks)")
     return parser.parse_args()
 
 ARGS = load_args()
@@ -251,13 +257,11 @@ def custom_openapi():
     
     # Enhance the auto-generated Bearer token security scheme with better documentation
     # The HTTPBearer dependency in utils.py creates the base scheme, we just improve it
-    if "components" in openapi_schema and "securitySchemes" in openapi_schema["components"]:
-        if "BearerAuth" in openapi_schema["components"]["securitySchemes"]:
-            # Update the description to be more helpful
-            openapi_schema["components"]["securitySchemes"]["BearerAuth"]["description"] = (
-                "JWT access token from /initialize or /refresh_token endpoint. "
-                "Enter ONLY the token (Swagger UI automatically adds 'Bearer ' prefix)"
-            )
+    if "components" in openapi_schema and "securitySchemes" in openapi_schema["components"] and "BearerAuth" in openapi_schema["components"]["securitySchemes"]:
+        openapi_schema["components"]["securitySchemes"]["BearerAuth"]["description"] = (
+            "JWT access token from /initialize or /refresh_token endpoint. "
+            "Enter ONLY the token (Swagger UI automatically adds 'Bearer ' prefix)"
+        )
     
     # Apply security globally to all endpoints except public ones
     for path, path_item in openapi_schema["paths"].items():
@@ -265,10 +269,8 @@ def custom_openapi():
         if path in ["/initialize", "/refresh_token", "/", "/admin/dump_all_conversations", "/admin/generate_mcp_token"]:
             continue
         for method in path_item:
-            if method in ["get", "post", "put", "delete", "patch"]:
-                # Ensure security is applied (should already be set by HTTPBearer dependency)
-                if "security" not in path_item[method]:
-                    path_item[method]["security"] = [{"BearerAuth": []}]
+            if method in ["get", "post", "put", "delete", "patch"] and "security" not in path_item[method]:
+                path_item[method]["security"] = [{"BearerAuth": []}]
     
     app.openapi_schema = openapi_schema
     return app.openapi_schema

{fastworkflow-2.17.5 → fastworkflow-2.17.7}/fastworkflow/run_fastapi_mcp/jwt_manager.py

@@ -34,6 +34,9 @@ PUBLIC_KEY_PATH = os.path.join(KEYS_DIR, "public_key.pem")
 _private_key: Optional[str] = None
 _public_key: Optional[str] = None
 
+# Flag to control JWT verification behavior (set from CLI)
+EXPECT_ENCRYPTED_JWT = True  # Default to secure mode
+
 
 def ensure_keys_directory() -> None:
     """Create jwt_keys directory if it doesn't exist."""
@@ -129,19 +132,42 @@ def load_or_generate_keys() -> tuple[str, str]:
     return _private_key, _public_key
 
 
+def set_jwt_verification_mode(expect_encrypted: bool) -> None:
+    """
+    Configure JWT verification mode for trusted network scenarios.
+    
+    When expect_encrypted=False, JWT tokens are decoded without signature verification.
+    This mode is ONLY suitable for trusted internal networks where JWT is used for
+    data transport rather than security.
+    
+    WARNING: Disabling signature verification allows any client to forge tokens.
+    Only use in controlled environments.
+    """
+    global EXPECT_ENCRYPTED_JWT
+    EXPECT_ENCRYPTED_JWT = expect_encrypted
+    if not expect_encrypted:
+        logger.warning(
+            "JWT signature verification DISABLED. "
+            "Tokens will be accepted without cryptographic validation. "
+            "Only use in trusted internal networks."
+        )
+
+
 def create_access_token(user_id: str, expires_days: int | None = None) -> str:
     """
     Create a JWT access token for a user.
     
+    Behavior depends on EXPECT_ENCRYPTED_JWT flag:
+    - If True: Creates a signed token using RSA algorithm
+    - If False: Creates an unsigned token for trusted network use
+    
     Args:
         user_id: User identifier
         expires_days: Optional custom expiration in days. If None, uses JWT_ACCESS_TOKEN_EXPIRE_MINUTES (default 60 minutes).
         
     Returns:
-        str: Encoded JWT access token
+        str: Encoded JWT access token (signed or unsigned based on EXPECT_ENCRYPTED_JWT)
     """
-    private_key, _ = load_or_generate_keys()
-    
     now = datetime.now(timezone.utc)
     if expires_days is not None:
         expire = now + timedelta(days=expires_days)
@@ -159,8 +185,17 @@ def create_access_token(user_id: str, expires_days: int | None = None) -> str:
         "aud": JWT_AUDIENCE  # Audience
     }
     
-    token = jwt.encode(payload, private_key, algorithm=JWT_ALGORITHM)
-    logger.debug(f"Created access token for user_id: {user_id}, expires: {expire.isoformat()}")
+    if EXPECT_ENCRYPTED_JWT:
+        # Secure mode: create signed token
+        private_key, _ = load_or_generate_keys()
+        token = jwt.encode(payload, private_key, algorithm=JWT_ALGORITHM)
+        logger.debug(f"Created signed access token for user_id: {user_id}, expires: {expire.isoformat()}")
+    else:
+        # Trusted network mode: create unsigned token using HS256 with empty key
+        # This creates a JWT that can be decoded without verification
+        token = jwt.encode(payload, "", algorithm="HS256")
+        logger.debug(f"Created unsigned access token for user_id: {user_id}, expires: {expire.isoformat()}")
+    
     return token
 
 
@@ -168,14 +203,16 @@ def create_refresh_token(user_id: str) -> str:
     """
     Create a JWT refresh token for a user.
     
+    Behavior depends on EXPECT_ENCRYPTED_JWT flag:
+    - If True: Creates a signed token using RSA algorithm
+    - If False: Creates an unsigned token for trusted network use
+    
     Args:
         user_id: User identifier
         
     Returns:
-        str: Encoded JWT refresh token
+        str: Encoded JWT refresh token (signed or unsigned based on EXPECT_ENCRYPTED_JWT)
     """
-    private_key, _ = load_or_generate_keys()
-    
     now = datetime.now(timezone.utc)
     expire = now + timedelta(days=JWT_REFRESH_TOKEN_EXPIRE_DAYS)
     
@@ -190,15 +227,29 @@ def create_refresh_token(user_id: str) -> str:
         "aud": JWT_AUDIENCE  # Audience
     }
     
-    token = jwt.encode(payload, private_key, algorithm=JWT_ALGORITHM)
-    logger.debug(f"Created refresh token for user_id: {user_id}, expires: {expire.isoformat()}")
+    if EXPECT_ENCRYPTED_JWT:
+        # Secure mode: create signed token
+        private_key, _ = load_or_generate_keys()
+        token = jwt.encode(payload, private_key, algorithm=JWT_ALGORITHM)
+        logger.debug(f"Created signed refresh token for user_id: {user_id}, expires: {expire.isoformat()}")
+    else:
+        # Trusted network mode: create unsigned token using HS256 with empty key
+        # This creates a JWT that can be decoded without verification
+        token = jwt.encode(payload, "", algorithm="HS256")
+        logger.debug(f"Created unsigned refresh token for user_id: {user_id}, expires: {expire.isoformat()}")
+    
     return token
 
 
 def verify_token(token: str, expected_type: str = "access") -> dict:
+    # sourcery skip: extract-duplicate-method
     """
     Verify and decode a JWT token.
     
+    Behavior depends on EXPECT_ENCRYPTED_JWT flag:
+    - If True (default): Full cryptographic verification with signature check
+    - If False: Extract payload without verification (trusted network mode)
+    
     Args:
         token: JWT token string
         expected_type: Expected token type ("access" or "refresh")
@@ -209,8 +260,25 @@ def verify_token(token: str, expected_type: str = "access") -> dict:
     Raises:
         JWTError: If token is invalid, expired, or type mismatch
     """
+    if not EXPECT_ENCRYPTED_JWT:
+        # Trusted network mode: decode without verification (accepts both unsigned and signed tokens)
+        try:
+            # Use unverified decoding - works for any JWT regardless of algorithm or signing
+            payload = jwt.get_unverified_claims(token)
+        except Exception as e:
+            logger.warning(f"Token decoding failed: {e}")
+            raise JWTError(f"Failed to decode token: {e}") from e
+        
+        # Validate token type for consistency (outside try-except to allow JWTError to propagate)
+        if payload.get("type") != expected_type:
+            raise JWTError(f"Invalid token type: expected {expected_type}, got {payload.get('type')}")
+        
+        logger.debug(f"Token decoded (unverified mode): user_id={payload.get('sub')}, type={expected_type}")
+        return payload
+
+    # Standard mode: full verification (existing code)
     _, public_key = load_or_generate_keys()
-    
+
     try:
         # Decode and verify token
         payload = jwt.decode(
@@ -220,14 +288,14 @@ def verify_token(token: str, expected_type: str = "access") -> dict:
             issuer=JWT_ISSUER,
             audience=JWT_AUDIENCE
         )
-        
+
         # Verify token type
         if payload.get("type") != expected_type:
             raise JWTError(f"Invalid token type: expected {expected_type}, got {payload.get('type')}")
-        
+
         logger.debug(f"Token verified successfully: user_id={payload.get('sub')}, type={expected_type}")
         return payload
-        
+
     except JWTError as e:
         logger.warning(f"Token verification failed: {e}")
         raise
@@ -247,8 +315,7 @@ def get_token_expiry(token: str) -> Optional[datetime]:
     try:
         # Decode without verification (just to inspect claims)
         payload = jwt.get_unverified_claims(token)
-        exp_timestamp = payload.get("exp")
-        if exp_timestamp:
+        if exp_timestamp := payload.get("exp"):
             return datetime.fromtimestamp(exp_timestamp, tz=timezone.utc)
     except Exception as e:
         logger.debug(f"Failed to get token expiry: {e}")

{fastworkflow-2.17.5 → fastworkflow-2.17.7}/fastworkflow/run_fastapi_mcp/utils.py

@@ -169,11 +169,11 @@ def get_session_from_jwt(
     """
     # Extract token from credentials (already validated by HTTPBearer)
     token = credentials.credentials
-    
+
     # Verify and decode token
     try:
         payload = verify_token(token, expected_type="access")
-        
+
         # Extract session data from payload
         return SessionData(
             user_id=payload["sub"],
@@ -182,19 +182,19 @@ def get_session_from_jwt(
             expires_at=payload["exp"],
             jti=payload["jti"]
         )
-        
+
     except JWTError as e:
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail=f"Invalid or expired token: {str(e)}",
-            headers={"WWW-Authenticate": "Bearer"}
-        )
+            headers={"WWW-Authenticate": "Bearer"},
+        ) from e
     except KeyError as e:
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail=f"Token missing required claim: {str(e)}",
-            headers={"WWW-Authenticate": "Bearer"}
-        )
+            headers={"WWW-Authenticate": "Bearer"},
+        ) from e
 
 
 async def ensure_user_runtime_exists(

fastworkflow-2.17.7/fastworkflow/utils/chat_adapter.py

@@ -0,0 +1,99 @@
+"""
+ChatAdapter wrapper for injecting context-specific available commands into system messages.
+
+Design Overview:
+---------------
+This module implements a ChatAdapter wrapper that dynamically injects workflow command information
+into the system message at runtime, avoiding the need to rebuild ReAct agent modules per context.
+
+Key Benefits:
+- Single shared agent: No per-context module caching required
+- Dynamic updates: Commands refresh per call based on current workflow context
+- Token efficiency: Commands appear in system (not repeated in trajectory/history)
+- Zero rebuild cost: Signature and modules remain stable across context changes
+
+Usage:
+------
+The adapter is used specifically for workflow agent calls via dspy.context():
+
+    from fastworkflow.utils.chat_adapter import CommandsSystemPreludeAdapter
+    
+    agent_adapter = CommandsSystemPreludeAdapter()
+    available_commands = _what_can_i_do(chat_session)
+    
+    with dspy.context(lm=lm, adapter=agent_adapter):
+        agent_result = agent(
+            user_query="...",
+            available_commands=available_commands
+        )
+
+The adapter intercepts the format call and prepends commands to the system message,
+keeping them out of the trajectory to prevent token bloat across iterations.
+This scoped approach ensures the adapter only affects workflow agent calls, not other
+DSPy operations in the system.
+"""
+import dspy
+
+
+class CommandsSystemPreludeAdapter(dspy.ChatAdapter):
+    """
+    Wraps a base DSPy ChatAdapter to inject available commands into the system message.
+    
+    This adapter intercepts the render process and prepends a "Available commands" section
+    to the system message when `available_commands` is present in inputs. This ensures
+    commands are visible to the model at each step without being added to the trajectory
+    or conversation history.
+    
+    Args:
+        base: The underlying ChatAdapter to wrap. Defaults to dspy.ChatAdapter() if None.
+        title: The header text for the commands section. Defaults to "Available commands".
+    
+    Example:
+        >>> import dspy
+        >>> from fastworkflow.utils.chat_adapter import CommandsSystemPreludeAdapter
+        >>> dspy.settings.adapter = CommandsSystemPreludeAdapter()
+    """
+    
+    def __init__(self, base: dspy.ChatAdapter | None = None, title: str = "Available commands"):
+        super().__init__()
+        self.base = base or dspy.ChatAdapter()
+        self.title = title
+    
+    def format(self, signature, demos, inputs):
+        """
+        Format the inputs for the model, injecting available_commands into system message.
+        
+        This method wraps the base adapter's format method and modifies the result
+        to include available commands in the system message if present in inputs.
+        
+        Args:
+            signature: The DSPy signature defining the task
+            demos: List of demonstration examples
+            inputs: Dictionary of input values, may include 'available_commands'
+            
+        Returns:
+            Formatted messages with commands injected into system message
+        """
+        # Call the base adapter's format method
+        formatted = self.base.format(signature, demos, inputs)
+        
+        # Check if available_commands is in inputs
+        cmds = inputs.get("available_commands")
+        if not cmds:
+            return formatted
+        
+        # Inject commands into the system message
+        prelude = f"{self.title}:\n{cmds}".strip()
+        
+        # Formatted output is a list of messages, first may be system
+        # Find and modify the system message, or prepend one
+        if formatted and formatted[0].get("role") == "system":
+            # Prepend to existing system message
+            existing_content = formatted[0].get("content", "")
+            formatted[0]["content"] = f"{prelude}\n\n{existing_content}".strip()
+        else:
+            # No system message exists, prepend one
+            formatted.insert(0, {"role": "system", "content": prelude})
+        
+        return formatted
+

{fastworkflow-2.17.5 → fastworkflow-2.17.7}/fastworkflow/utils/react.py

@@ -67,13 +67,17 @@ class fastWorkflowReAct(Module):
             args={},
         )
 
-        for idx, tool in enumerate(tools.values()):
-            instr.append(f"({idx + 1}) {tool}")
+        instr.extend(f"({idx + 1}) {tool}" for idx, tool in enumerate(tools.values()))
         instr.append("When providing `next_tool_args`, the value inside the field must be in JSON format")
 
+        # Build the ReAct signature with trajectory and available_commands inputs.
+        # available_commands is injected into system message by CommandsSystemPreludeAdapter
+        # (see fastworkflow/utils/chat_adapter.py) and is NOT included in the trajectory
+        # formatting to avoid token bloat across iterations.
         react_signature = (
             dspy.Signature({**signature.input_fields}, "\n".join(instr))
             .append("trajectory", dspy.InputField(), type_=str)
+            .append("available_commands", dspy.InputField(), type_=str)
             .append("next_thought", dspy.OutputField(), type_=str)
             .append("next_tool_name", dspy.OutputField(), type_=Literal[tuple(tools.keys())])
             .append("next_tool_args", dspy.OutputField(), type_=dict[str, Any])
@@ -82,7 +86,7 @@ class fastWorkflowReAct(Module):
         fallback_signature = dspy.Signature(
             {**signature.input_fields, **signature.output_fields},
             signature.instructions,
-        ).append("trajectory", dspy.InputField(), type_=str)
+        ).append("trajectory", dspy.InputField(), type_=str).append("available_commands", dspy.InputField(), type_=str)
 
         self.tools = tools
         self.react = dspy.Predict(react_signature)

{fastworkflow-2.17.5 → fastworkflow-2.17.7}/pyproject.toml

@@ -9,7 +9,7 @@ repository = "https://github.com/radiantlogicinc/fastworkflow"
 
 [tool.poetry]
 name = "fastworkflow"
-version = "2.17.5"
+version = "2.17.7"
 description = "A framework for rapidly building large-scale, deterministic, interactive workflows with a fault-tolerant, conversational UX"
 authors = ["Dhar Rawal <drawal@radiantlogic.com>"]
 license = "Apache-2.0"