fastworkflow 2.16.0__tar.gz → 2.17.0__tar.gz

{fastworkflow-2.16.0 → fastworkflow-2.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastworkflow
-Version: 2.16.0
+Version: 2.17.0
 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.16.0 → fastworkflow-2.17.0}/fastworkflow/_workflows/command_metadata_extraction/_commands/IntentDetection/what_can_i_do.py

@@ -8,6 +8,7 @@ import json
 
 import fastworkflow
 from fastworkflow.train.generate_synthetic import generate_diverse_utterances
+from fastworkflow.command_context_model import get_workflow_info
 from fastworkflow.command_metadata_api import CommandMetadataAPI
 
 class Signature:
@@ -139,23 +140,27 @@ class ResponseGenerator:
         with contextlib.suppress(Exception):
             if fastworkflow.chat_session:
                 is_agent_mode = fastworkflow.chat_session.run_as_agent
-        
+
         app_workflow = workflow.context["app_workflow"]
-        response = CommandMetadataAPI.get_command_display_text(
+        
+        # Get workflow definition
+        workflow_info = get_workflow_info(app_workflow.folderpath)
+        workflow_def_text = CommandMetadataAPI.get_workflow_definition_display_text(workflow_info)
+        
+        # Get available commands in current context
+        commands_text = CommandMetadataAPI.get_command_display_text(
             subject_workflow_path=app_workflow.folderpath,
             cme_workflow_path=workflow.folderpath,
             active_context_name=app_workflow.current_command_context_name,
             for_agents=is_agent_mode,
         )
+        
+        response = f"{workflow_def_text}\n\n{commands_text}"
 
-        # Check if the NLU pipeline stage is intent detection
-        success = False
         nlu_pipeline_stage = workflow.context.get(
             "NLU_Pipeline_Stage", 
             fastworkflow.NLUPipelineStage.INTENT_DETECTION)
-        if nlu_pipeline_stage == fastworkflow.NLUPipelineStage.INTENT_DETECTION:
-            success = True
-
+        success = nlu_pipeline_stage == fastworkflow.NLUPipelineStage.INTENT_DETECTION
         return fastworkflow.CommandOutput(
             workflow_id=workflow.id,
             command_responses=[

{fastworkflow-2.16.0 → fastworkflow-2.17.0}/fastworkflow/chat_session.py

@@ -495,6 +495,7 @@ class ChatSession:
         # Create CommandOutput with the agent's response
         command_response = fastworkflow.CommandResponse(response=result_text)
 
+        conversation_traces = None
         conversation_summary = message
         # Attach actions captured during agent execution as artifacts if available
         if os.path.exists("action.jsonl"):

{fastworkflow-2.16.0 → fastworkflow-2.17.0}/fastworkflow/command_context_model.py

@@ -2,11 +2,12 @@ from __future__ import annotations
 
 import json
 from dataclasses import dataclass, field
+from typing import Any
+import os
 from pathlib import Path
-from typing import Any, Optional, Type
 
 import fastworkflow
-from fastworkflow.command_directory import CommandDirectory, get_cached_command_directory
+from fastworkflow.command_directory import get_cached_command_directory
 from fastworkflow.utils import python_utils
 
 """Utility for loading and traversing the single-file workflow command context model.
@@ -152,10 +153,10 @@ class CommandContextModel:
         hierarchy_model_path = Path(self._workflow_path) / "context_hierarchy_model.json"
         if not hierarchy_model_path.is_file():
             return {}
-        
+
         with hierarchy_model_path.open("r") as f:
             hierarchy_data = json.load(f)
-            
+
         return hierarchy_data
 
     def _resolve_ancestry(self, hierarchy: dict[str, dict[str, list[str]]]) -> None:
@@ -205,10 +206,10 @@ class CommandContextModel:
             all_ancestors.add(parent)
             grandparents = self.get_ancestor_contexts(parent, visiting.copy(), _hierarchy)
             all_ancestors.update(grandparents)
-        
+
         final_ancestors = sorted(list(all_ancestors))
         self._resolved_ancestors[context_name] = final_ancestors
-        
+
         visiting.remove(context_name)
 
         return final_ancestors
@@ -228,7 +229,7 @@ class CommandContextModel:
             # or by being part of a command inheritance structure. If it's not
             # in _command_contexts, it's an unknown/invalid context.
             raise CommandContextModelValidationError(f"Context '{context_name}' not found in model.")
-            
+
         if visiting is None:
             visiting = set()
 
@@ -294,3 +295,68 @@ class CommandContextModel:
             return getattr(module, context_metadata.context_class, None)
         else:
             return None
+
+
+# ---------------------------------------------------------------------
+# Workflow info helper (module-level)
+# ---------------------------------------------------------------------
+
+def get_workflow_info(chat_session_or_path: fastworkflow.ChatSession | str) -> dict[str, Any]:
+    """
+    Return workflow-level metadata for the active workflow in the given chat session or workflow path.
+
+    Shape:
+    {
+      "workflow_name": str,
+      "available_contexts": list[str],
+      "context_inheritance_model": dict,
+      "context_hierarchy_model": dict
+    }
+
+    Notes:
+    - available_contexts are derived from CommandContextModel.load(workflow_path)
+      so they reflect filesystem + inheritance.
+    - current context and purpose/description are intentionally omitted.
+    - Raw JSON for inheritance (from _commands/context_inheritance_model.json)
+      and hierarchy (from context_hierarchy_model.json) is returned verbatim when present.
+    """
+    if isinstance(chat_session_or_path, str):
+        workflow_path_str = chat_session_or_path
+    else:
+        workflow_path_str = chat_session_or_path.get_active_workflow().folderpath
+    workflow_name = os.path.basename(os.path.abspath(workflow_path_str))
+
+    available_contexts: list[str]
+    inheritance_json: dict[str, Any] = {}
+    hierarchy_json: dict[str, Any] = {}
+
+    try:
+        # Derive contexts via consolidated model
+        context_model = CommandContextModel.load(workflow_path_str)
+        # Do not normalize names beyond keeping what the model exposes
+        available_contexts = sorted([key for key in context_model._command_contexts.keys() if key != 'IntentDetection'])
+    except Exception:
+        available_contexts = ["/"]
+
+    # Load raw context inheritance model (if present)
+    try:
+        inheritance_path = Path(workflow_path_str) / "_commands" / "context_inheritance_model.json"
+        if inheritance_path.is_file():
+            inheritance_json = json.loads(inheritance_path.read_text())
+    except Exception:
+        inheritance_json = {}
+
+    # Load raw context hierarchy model (if present)
+    try:
+        hierarchy_path = Path(workflow_path_str) / "context_hierarchy_model.json"
+        if hierarchy_path.is_file():
+            hierarchy_json = json.loads(hierarchy_path.read_text())
+    except Exception:
+        hierarchy_json = {}
+
+    return {
+        "workflow_name": workflow_name,
+        "available_contexts": available_contexts,
+        "context_inheritance_model": inheritance_json,
+        "context_hierarchy_model": hierarchy_json,
+    }

{fastworkflow-2.16.0 → fastworkflow-2.17.0}/fastworkflow/command_metadata_api.py

@@ -480,6 +480,58 @@ class CommandMetadataAPI:
 
         return f"{indent_str}{value}"
 
+    @staticmethod
+    def get_workflow_definition_display_text(workflow_info: Dict[str, Any]) -> str:
+        """
+        Convert workflow definition dict to human-readable text display.
+        
+        Args:
+            workflow_info: Workflow info dict from get_workflow_info()
+                {
+                    "workflow_name": str,
+                    "available_contexts": list[str],
+                    "context_inheritance_model": dict,
+                    "context_hierarchy_model": dict
+                }
+        
+        Returns:
+            Human-readable text representation of workflow definition
+        """
+        lines: List[str] = ["Workflow Definition:"]
+        
+        # Workflow name
+        if workflow_name := workflow_info.get("workflow_name"):
+            lines.append(f"  name: {workflow_name}")
+        
+        # Available contexts
+        if contexts := workflow_info.get("available_contexts"):
+            lines.append("  available_contexts:")
+            for ctx in contexts:
+                display_name = "global" if ctx == "*" else ctx
+                lines.append(f"    - {display_name}")
+        
+        # Context inheritance (if present and non-empty)
+        if inheritance := workflow_info.get("context_inheritance_model"):
+            if inheritance:  # Only show if not empty dict
+                lines.append("  context_inheritance:")
+                for ctx, parents in sorted(inheritance.items()):
+                    if parents:  # Only show if has parents
+                        display_ctx = "global" if ctx == "*" else ctx
+                        parent_list = ", ".join(["global" if p == "*" else p for p in parents])
+                        lines.append(f"    {display_ctx}: [{parent_list}]")
+        
+        # Context hierarchy (if present and non-empty)
+        if hierarchy := workflow_info.get("context_hierarchy_model"):
+            if hierarchy:  # Only show if not empty dict
+                lines.append("  context_hierarchy:")
+                for parent, children in sorted(hierarchy.items()):
+                    if children:  # Only show if has children
+                        display_parent = "global" if parent == "*" else parent
+                        children_list = ", ".join(["global" if c == "*" else c for c in children])
+                        lines.append(f"    {display_parent}: [{children_list}]")
+        
+        return "\n".join(lines)
+
     @staticmethod
     def get_command_display_text(
         subject_workflow_path: str,
@@ -499,7 +551,7 @@ class CommandMetadataAPI:
             cme_workflow_path=cme_workflow_path,
             active_context_name=active_context_name,
         )
-        
+
         # Build minimal context info (inheritance/containment if available)
         context_info: Dict[str, Any] = {
             "name": active_context_name,
@@ -529,10 +581,8 @@ class CommandMetadataAPI:
             empty_display = CommandMetadataAPI._prune_empty(empty_display, remove_keys={"default"})
             rendered = CommandMetadataAPI._to_yaml_like(empty_display, omit_command_name=False)
             # Ensure a visible header is present
-            header = "Commands available:"
-            if not rendered.strip():
-                return header
-            return f"{header}\n{rendered}"
+            header = "Commands available in the current context:"
+            return f"{header}\n{rendered}" if rendered.strip() else header
 
         # Build the combined display by stitching per-command strings while keeping
         # a single "Commands available:" header and blank lines between commands
@@ -553,7 +603,7 @@ class CommandMetadataAPI:
             empty_display = CommandMetadataAPI._prune_empty(empty_display, remove_keys={"default"})
             return CommandMetadataAPI._to_yaml_like(empty_display, omit_command_name=False)
 
-        combined_lines: List[str] = ["Commands available:"]
+        combined_lines: List[str] = [f"Commands available in the current context ({context_info['display_name']}):"]
         for idx, text in enumerate(parts):
             lines = text.splitlines()
             if idx > 0:

{fastworkflow-2.16.0 → fastworkflow-2.17.0}/fastworkflow/run/__main__.py

@@ -19,7 +19,6 @@ def run_main(args):
     from rich.table import Table
     from rich.text import Text
     from rich.console import Group
-    from rich.live import Live
     from rich.spinner import Spinner
     from prompt_toolkit import PromptSession
     from prompt_toolkit.patch_stdout import patch_stdout
@@ -27,7 +26,6 @@ def run_main(args):
 
     import fastworkflow
     from fastworkflow.utils.logging import logger
-    from fastworkflow.command_executor import CommandExecutor
 
     # Progress bar helper
     from fastworkflow.utils.startup_progress import StartupProgress
@@ -146,10 +144,6 @@ def run_main(args):
     # ------------------------------------------------------------------
     # Startup progress bar ------------------------------------------------
     # ------------------------------------------------------------------
-    command_info_root = os.path.join(args.workflow_path, "___command_info")
-    subdir_count = 0
-    if os.path.isdir(command_info_root):
-        subdir_count = len([d for d in os.listdir(command_info_root) if os.path.isdir(os.path.join(command_info_root, d))])
 
     # 3 coarse CLI steps + per-directory warm-up (handled inside ChatSession) + 1 global warm-up
     StartupProgress.begin(total=3)

fastworkflow-2.17.0/fastworkflow/run_fastapi_mcp/README.md

@@ -0,0 +1,300 @@
+# FastWorkflow FastAPI + MCP Service
+
+HTTP + MCP interface for FastWorkflow workflows with synchronous and streaming execution.
+
+## Overview
+
+This service exposes FastWorkflow workflows as REST endpoints and as MCP tools, enabling clients to:
+- Initialize workflow sessions per user
+- Submit natural language queries (agent mode)
+- Execute deterministic commands (assistant mode)
+- Perform explicit actions
+- Manage conversations with persistent history
+- Collect feedback on interactions
+
+## Architecture
+
+- **Session Management**: In-memory `UserSessionManager` with per-user `ChatSession` instances
+- **Persistence**: Rdict-backed conversation storage (one DB file per user)
+- **Execution**: Synchronous turn-based processing with queue-based communication
+- **Tracing**: Traces are collected by default and included in synchronous responses or emitted incrementally during streaming
+- **Streaming (REST)**: `/invoke_agent_stream` supports Streamable HTTP via NDJSON by default and SSE when requested in REST initialize
+- **Streaming (MCP)**: MCP transport mounted at `/mcp`; tools stream partials via MCP transport by default or SSE when requested in MCP initialize
+
+See [`docs/fastworkflow_fastapi_spec.md`](../../docs/fastworkflow_fastapi_spec.md) and [`docs/fastworkflow_fastapi_architecture.md`](../../docs/fastworkflow_fastapi_architecture.md) for complete specification and design.
+
+## Running the Service
+
+### Start Server (REST + MCP)
+
+```bash
+uvicorn services.run_fastapi.main:app --host 0.0.0.0 --port 8000
+
+# MCP (auto-mounted via fastapi_mcp) will be available at `/mcp`.
+```
+
+### Access Documentation
+
+Once running, visit:
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+- **Health Check**: http://localhost:8000/
+
+## Environment Variables
+
+Configure in your environment (loaded at process startup via CLI args or env load):
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `SPEEDDICT_FOLDERNAME` | Base folder for workflow contexts and conversation storage | Yes | - |
+
+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).
+
+## API Endpoints (REST)
+
+### `POST /initialize`
+Initialize a session for a user. Workflow configuration is loaded at server startup from CLI args/env.
+
+**Request:**
+```json
+{
+  "user_id": "user-123",
+  "stream_format": "ndjson"  // optional: "ndjson" | "sse" (default "ndjson")
+}
+```
+
+**Important Notes:**
+- `stream_format` controls REST streaming format for `/invoke_agent_stream` (NDJSON default, SSE optional).
+- Workflow configuration is loaded at server startup from CLI args/env, not from the request.
+
+**Response:**
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "bearer",
+  "expires_in": 3600
+}
+
+```
+
+### `POST /invoke_agent`
+Submit a natural language query for agentic processing.
+
+**Request:**
+```json
+{
+  "user_id": "user-123",
+  "user_query": "find orders for user 42",
+  "timeout_seconds": 60
+}
+```
+
+**Response:**
+```json
+{
+  "command_responses": [
+    {
+      "response": "Found 3 orders for user 42",
+      "success": true,
+      "artifacts": {},
+      "next_actions": [],
+      "recommendations": []
+    }
+  ],
+  "workflow_name": "default_workflow",
+  "context": "Order management context",
+  "command_name": "find_orders",
+  "command_parameters": "user_id=42",
+  "traces": [...]
+}
+```
+
+### `POST /invoke_assistant`
+Submit a query for deterministic/assistant execution (no planning).
+
+Same request/response format as `/invoke_agent`.
+
+### `POST /perform_action`
+Execute a specific workflow action directly (bypasses parameter extraction).
+
+**Request:**
+```json
+{
+  "action": {
+    "command_name": "find_orders",
+    "parameters": {"user_id": 42}
+  },
+  "timeout_seconds": 60
+}
+```
+
+**Response:**
+Same format as `/invoke_agent` (CommandOutput with traces).
+
+### `POST /invoke_agent_stream`
+Stream trace events and final `CommandOutput` via Streamable HTTP:
+- NDJSON (default; `Content-Type: application/x-ndjson`)
+- SSE (when REST `stream_format` is set to `sse`; `Content-Type: text/event-stream`)
+
+## Conversation Management (REST)
+
+### `POST /new_conversation`
+Persist current conversation and start a new one.
+
+**Request:**
+```json
+{}
+```
+
+**Response:**
+```json
+{
+  "status": "ok"
+}
+```
+
+### `GET /conversations?user_id={user_id}&limit=20`
+List conversations for a user (most recent first). `limit` is optional; defaults to `20`.
+
+**Response:**
+```json
+[
+  {
+    "conversation_id": 1,
+    "topic": "Order Management",
+    "summary": "...",
+    "created_at": 1234567890000,
+    "updated_at": 1234567890000
+  }
+]
+```
+
+### `POST /activate_conversation`
+Switch to a different conversation by ID.
+
+**Request:**
+```json
+{
+  "conversation_id": 1
+}
+```
+
+### `POST /post_feedback`
+Attach feedback to the latest turn.
+
+**Request:**
+```json
+{
+  "binary_or_numeric_score": true,
+  "nl_feedback": "Helpful response"
+}
+```
+
+At least one of `binary_or_numeric_score` or `nl_feedback` must be provided.
+
+## Admin Endpoints (REST-only; not exposed via MCP)
+
+### `POST /admin/dump_all_conversations`
+Export all conversations to JSONL.
+
+**Request:**
+```json
+{
+  "output_folder": "/path/to/export"
+}
+```
+
+**Response:**
+```json
+{
+  "file_path": "/path/to/export/all_conversations_1234567890.jsonl"
+}
+```
+
+## Usage Examples
+
+### REST initialize
+```python
+import requests
+
+resp = requests.post("http://localhost:8000/initialize", json={
+    "user_id": "alice",
+    "stream_format": "ndjson"
+})
+print(resp.json())  # {"access_token": "...", "refresh_token": "...", "token_type": "bearer", "expires_in": 3600}
+```
+
+### REST sync invoke
+```python
+# First get a token from /initialize
+init_resp = requests.post("http://localhost:8000/initialize", json={
+    "user_id": "alice",
+    "stream_format": "ndjson"
+})
+token_data = init_resp.json()
+access_token = token_data["access_token"]
+
+# Then use the token for authenticated requests
+resp = requests.post("http://localhost:8000/invoke_agent", 
+    headers={"Authorization": f"Bearer {access_token}"},
+    json={
+        "user_query": "list all users",
+        "timeout_seconds": 30
+    }
+)
+result = resp.json()
+print(result["command_responses"])
+print(result.get("traces"))
+```
+
+### MCP Quickstart
+- Mount is available at `/mcp` (auto-exposed by fastapi_mcp).
+- MCP clients use pre-configured long-lived access tokens (generated via `/admin/generate_mcp_token`).
+- No need for initialize or refresh_token tools in MCP context.
+
+MCP invoke agent (streaming):
+
+```bash
+# NDJSON (default for MCP)
+curl -N -X POST http://localhost:8000/mcp/invoke_agent \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/x-ndjson' \
+  -H 'Authorization: Bearer <your-mcp-token>' \
+  -d '{"user_query":"find orders for user 42","timeout_seconds":60}'
+
+# SSE (if stream_format was set to "sse" during MCP setup)
+curl -N -X POST http://localhost:8000/mcp/invoke_agent \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: text/event-stream' \
+  -H 'Authorization: Bearer <your-mcp-token>' \
+  -d '{"user_query":"find orders for user 42","timeout_seconds":60}'
+```
+
+### MCP Prompts
+The MCP mount registers two prompts for client discovery:
+- `format-command(intent, metadata)`
+- `clarify-params(error_message, metadata)`
+
+## Testing
+
+See [`tests/`](../../tests/) for unit and integration tests.
+
+**Key test scenarios:**
+- SessionManager concurrency and lifecycle
+- Env loading from files only
+- CLI argument validation (startup_command vs startup_action)
+- Timeout behavior (504 on no output)
+- Conversation persistence and listing
+- Feedback attachment
+
+## Future Enhancements
+
+- Session TTL and eviction policy
+- Richer observability and structured logging
+- Security: workflow path allow-list, authn/z
+- Conversation history restoration on session resume
+