pygeai 0.1.51b3__py3-none-any.whl → 0.6.0b15__py3-none-any.whl

pygeai/_docs/source/content/ai_lab/runner.rst

@@ -0,0 +1,253 @@
+Runner
+======
+
+The `Runner` class in the PyGEAI SDK's `lab` module provides a straightforward, asynchronous interface for executing AI agent tasks within the Globant Enterprise AI Lab's runtime environment. It enables developers to run agents with flexible input formats and customizable language model (LLM) settings, facilitating both testing and production use cases. The `Runner` class abstracts the complexity of chat completion requests, handling message processing and LLM configuration to deliver a `ProviderResponse` object containing the agent’s response and metadata.
+
+Overview
+--------
+
+The `Runner` class is designed to execute agent tasks by invoking the Lab’s chat completion API. It supports multiple input types—strings, `ChatMessage`, or `ChatMessageList`—allowing developers to interact with agents in various contexts, from simple text inputs to structured conversation histories. The class also accepts optional LLM settings to fine-tune the agent's behavior, such as temperature, token limits, and penalties, ensuring precise control over task execution.
+
+The `Runner` is particularly useful for:
+
+- **Testing Agents**: Validate agent behavior during development by running tasks with different inputs and configurations.
+- **Production Execution**: Integrate agent execution into applications, leveraging the Lab’s runtime for scalable task processing.
+- **Flexible Input Handling**: Support diverse use cases by accepting raw text, single messages, or multi-message conversation contexts.
+
+Key Features
+------------
+
+- **Asynchronous Execution**: Uses `asyncio` for non-blocking task execution, suitable for high-performance applications.
+- **Flexible Input Types**:
+  - **String**: Simple text input, automatically converted to a user message.
+  - **ChatMessage**: A single message with a specified role (e.g., "user") and content.
+  - **ChatMessageList**: A list of messages, enabling conversation history or system prompts.
+- **Customizable LLM Settings**: Accepts `LlmSettings` or dictionary-based configurations to adjust parameters like temperature, max tokens, and penalties.
+- **Error Handling**: Raises `WrongArgumentError` for invalid input types, ensuring robust validation.
+- **Integration with AILabManager**: Works seamlessly with agents created and managed via the `AILabManager` class.
+
+Usage
+-----
+
+The `Runner` class is invoked via its asynchronous `run` method, which takes an `Agent` instance, user input, and optional LLM settings. The method returns a `ProviderResponse` object containing the agent’s response, usage details, and metadata. Below are examples demonstrating its usage with different input types, based on a scenario where an agent translates text into ancient French.
+
+### Example: Creating and Running an Agent
+
+First, an agent is created using the `AILabManager` to translate modern text into ancient French. The agent is then executed using the `Runner` class with various input formats.
+
+.. code-block:: python
+
+    import asyncio
+    from pygeai.lab.runners import Runner
+    from pygeai.lab.managers import AILabManager
+    from pygeai.lab.models import Agent, AgentData, Prompt, PromptExample, PromptOutput, LlmConfig, Sampling, Model, ModelList
+    from pygeai.core.models import ChatMessageList, ChatMessage, LlmSettings
+
+    manager = AILabManager()
+    project_id = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+
+    # Track created entities for rollback
+    created_entities = {"agent_id": None}
+
+    def rollback():
+        """Deletes created entities to clean up."""
+        print("\n=== Initiating Rollback ===")
+        if created_entities["agent_id"]:
+            print(f"Deleting agent {created_entities['agent_id']}...")
+            result = manager.delete_agent(project_id=project_id, agent_id=created_entities["agent_id"])
+            print(f"Rollback: {result}")
+        print("Rollback complete.")
+
+    def create_translation_agent():
+        """Creates and publishes an agent for translating text into ancient French."""
+        print("\n=== Agent Creation Flow ===")
+        print("Creating agent 'AncientFrenchTranslator' as draft...")
+        agent = Agent(
+            name="AncientFrenchTranslatorTest",
+            access_scope="private",
+            public_name="ancient_french_translator_test",
+            job_description="Translates modern text into ancient French",
+            avatar_image="https://example.com/ancient_french_avatar.png",
+            description="An agent for translating text into ancient French",
+            agent_data=AgentData(
+                prompt=Prompt(
+                    instructions="Translate the provided text into ancient French, using vocabulary and grammar consistent with medieval French (circa 12th-14th century). Ensure the tone is formal and historically appropriate.",
+                    inputs=["text"],
+                    outputs=[
+                        PromptOutput(key="translated_text", description="Text translated into ancient French")
+                    ],
+                    examples=[
+                        PromptExample(
+                            input_data="Text: Hello, how are you today?",
+                            output='{"translated_text": "Salvete, comment estes-vous or?"}'
+                        ),
+                        PromptExample(
+                            input_data="Text: I am going to the market.",
+                            output='{"translated_text": "Je vais au marchié."}'
+                        )
+                    ]
+                ),
+                llm_config=LlmConfig(
+                    max_tokens=1000,
+                    timeout=60,
+                    sampling=Sampling(temperature=0.6, top_k=50, top_p=0.95)
+                ),
+                models=ModelList(models=[
+                    Model(name="gpt-4-turbo"),
+                    Model(name="mistral-7b")
+                ]),
+                resource_pools=None
+            ),
+            is_draft=True,
+            revision=1,
+            status="pending"
+        )
+
+        # Create, update, and publish the agent
+        create_agent_result = manager.create_agent(project_id=project_id, agent=agent, automatic_publish=False)
+        if isinstance(create_agent_result, Agent):
+            created_entities["agent_id"] = create_agent_result.id
+            agent = create_agent_result
+            agent.description = "Specialized agent for accurate ancient French translations"
+            manager.update_agent(project_id=project_id, agent=agent, automatic_publish=False)
+            manager.publish_agent_revision(project_id=project_id, agent_id=created_entities["agent_id"], revision="1")
+            return manager.get_agent(project_id=project_id, agent_id=created_entities["agent_id"])
+        else:
+            rollback()
+            raise Exception("Agent creation failed")
+
+    async def test_translation_agent(agent):
+        """Tests the ancient French translation agent with different input types."""
+        print("\n=== Testing Ancient French Translation Agent ===")
+
+        # Test 1: String Input
+        print("Test 1: Translating a string input...")
+        user_input = "Good morning, my friend!"
+        try:
+            response = await Runner.run(
+                agent=agent,
+                user_input=user_input,
+                llm_settings={
+                    "temperature": 0.6,
+                    "max_tokens": 200,
+                    "frequency_penalty": 0.1,
+                    "presence_penalty": 0.2
+                }
+            )
+            print(f"Input: {user_input}")
+            print(f"Response: {response}")
+        except Exception as e:
+            print(f"Error in Test 1: {e}")
+
+        # Test 2: ChatMessage Input
+        print("\nTest 2: Translating a ChatMessage input...")
+        chat_message = ChatMessage(
+            role="user",
+            content="I am traveling to a distant land."
+        )
+        try:
+            response = await Runner.run(
+                agent=agent,
+                user_input=chat_message,
+                llm_settings=LlmSettings(
+                    temperature=0.7,
+                    max_tokens=300,
+                    frequency_penalty=0.0,
+                    presence_penalty=0.0
+                )
+            )
+            print(f"Input: {chat_message.content}")
+            print(f"Response: {response}")
+        except Exception as e:
+            print(f"Error in Test 2: {e}")
+
+        # Test 3: ChatMessageList Input
+        print("\nTest 3: Translating a ChatMessageList input...")
+        chat_message_list = ChatMessageList(messages=[
+            ChatMessage(role="system", content="Translate the following into ancient French with a formal tone."),
+            ChatMessage(role="user", content="The sun rises slowly over the hills.")
+        ])
+        try:
+            response = await Runner.run(
+                agent=agent,
+                user_input=chat_message_list
+                # Using default LLM settings
+            )
+            print(f"Input: System: {chat_message_list.messages[0].content}\nUser: {chat_message_list.messages[1].content}")
+            print(f"Response: {response}")
+        except Exception as e:
+            print(f"Error in Test 3: {e}")
+
+    async def main():
+        try:
+            agent = create_translation_agent()
+            await test_translation_agent(agent)
+            print("\n=== Translation Agent Testing Completed Successfully ===")
+            rollback()
+        except Exception as e:
+            rollback()
+            print(f"\n# Critical error: {e}")
+
+    if __name__ == "__main__":
+        asyncio.run(main())
+
+### Output Explanation
+
+The `run` method returns a `ProviderResponse` object, which includes:
+
+- **choices**: A list of `Choice` objects, each containing a `ChatMessage` with the agent’s response (e.g., translated text).
+- **usage**: A `UsageDetails` object detailing token counts, costs, and currency.
+- **model**: The LLM model used (e.g., `gpt-4-turbo-2024-04-09`).
+- **created**: A timestamp for when the response was generated.
+- **id**: A unique identifier for the chat completion request (optional).
+- **system_fingerprint**: A unique identifier for the system configuration (optional).
+- **service_tier**: The service tier used for the request (optional).
+- **object**: A string indicating the response type, typically `chat.completion` (optional).
+
+For example, in the string input test (`"Good morning, my friend!"`):
+
+- The response includes a `ChatMessage` with content: `"Salut, amis mien! Bon matin à vous!"`.
+- Usage details show `completion_tokens=15`, `prompt_tokens=312`, and `total_cost=0.00357` USD.
+- Metadata includes `model='gpt-4-turbo-2024-04-09'`, `created=1745598637`, and `id='chatcmpl-BQGEfS8w0z3ly6OZfRKZbN1VxQyFs'`.
+
+### Input Flexibility
+
+The `Runner` class’s ability to handle multiple input types is a key strength, enabling developers to tailor interactions to specific use cases:
+
+- **String Input**: Ideal for quick tests or simple interactions. The input is automatically wrapped as a `ChatMessage` with the "user" role.
+- **ChatMessage Input**: Allows specification of the message role (e.g., "user", "system") and content, useful for structured single-message interactions.
+- **ChatMessageList Input**: Supports conversation history or multi-message contexts, such as including a system prompt followed by user input, enabling complex dialogues.
+
+This flexibility ensures the `Runner` can accommodate both lightweight prototyping and sophisticated conversational workflows.
+
+### LLM Settings Customization
+
+The `llm_settings` parameter accepts either a dictionary or an `LlmSettings` object, allowing developers to fine-tune the agent’s behavior. Key parameters include:
+
+- `temperature`: Controls randomness (e.g., 0.6 for balanced outputs).
+- `max_tokens`: Limits the response length (e.g., 200 or 300 tokens).
+- `frequency_penalty` and `presence_penalty`: Adjusts token repetition tendencies.
+
+If no `llm_settings` are provided, the `Runner` applies default settings (`temperature=0.6`, `max_tokens=800`, `frequency_penalty=0.1`, `presence_penalty=0.2`).
+
+Error Handling
+--------------
+
+The `Runner` class validates input types and raises a `WrongArgumentError` if the `user_input` is not a string, `ChatMessage`, or `ChatMessageList`. Developers should handle exceptions to ensure robust execution, as shown in the example’s try-except blocks.
+
+Integration with AILabManager
+-----------------------------
+
+The `Runner` integrates seamlessly with the `AILabManager` class, which is used to create, manage, and retrieve agents. In the example, the `AILabManager` creates and publishes the agent, which is then passed to the `Runner` for execution. This workflow ensures agents are properly configured before runtime execution.
+
+Best Practices
+--------------
+
+- **Input Validation**: Always validate input types before passing to `Runner.run` to avoid `WrongArgumentError`.
+- **Asynchronous Execution**: Use `await` in async functions or `asyncio.run` for top-level execution to handle the `Runner`’s asynchronous nature.
+- **Rollback Mechanism**: Implement rollback logic (as shown in the example) to clean up created entities during testing or error scenarios.
+- **LLM Tuning**: Experiment with `llm_settings` to optimize agent responses for specific tasks, balancing creativity and precision.
+- **Testing with Multiple Inputs**: Test agents with all supported input types to ensure robustness across use cases.
+- **Response Processing**: Extract the agent’s response from the `ProviderResponse` object’s `choices` list (e.g., `response.choices[0].message.content`) for further processing.
+
+The `Runner` class is a powerful tool for executing AI agents within the Globant Enterprise AI Lab, offering flexibility, ease of use, and seamless integration with the broader PyGEAI SDK ecosystem.

pygeai/_docs/source/content/ai_lab/spec.rst

@@ -0,0 +1,431 @@
+GEAI CLI - AI Lab - Spec Command Documentation
+==============================================
+
+Name
+----
+
+geai - Command Line Interface for Globant Enterprise AI
+
+Synopsis
+--------
+
+.. code-block:: bash
+
+   geai spec <subcommand> --[flag] [flag.arg]
+
+Description
+-----------
+
+The ``geai spec`` command is a utility within the Globant Enterprise AI (GEAI) CLI, designed to load components (agents, tools, tasks, and agentic processes) into the AI Lab from JSON specification files. It supports the following subcommands:
+
+- ``help`` (or ``h``): Displays help text for the ``geai spec`` command.
+- ``load-agent`` (or ``la``): Loads agent(s) from a JSON specification file.
+- ``load-tool`` (or ``lt``): Loads tool(s) from a JSON specification file.
+- ``load-task`` (or ``ltask``): Loads task(s) from a JSON specification file.
+- ``load-agentic-process`` (or ``lap``): Loads agentic process(es) from a JSON specification file.
+
+Each subcommand accepts specific options to configure the loading process, such as project ID (specified as a UUID), file path, and publication settings.
+
+Subcommands and Options
+-----------------------
+
+The following subcommands are available under ``geai spec``:
+
+help
+~~~~
+
+- **Aliases**: ``help``, ``h``
+- **Description**: Displays help text describing the ``geai spec`` command and its subcommands.
+- **Options**: None
+- **Usage**:
+
+  .. code-block:: bash
+
+     geai spec help
+
+load-agent
+~~~~~~~~~~
+
+- **Aliases**: ``load-agent``, ``la``
+- **Description**: Loads one or more agent specifications from a JSON file into the AI Lab for a specified project, identified by a UUID.
+- **Options**:
+
+  +-------------------------+---------------------------+-------------------------------------------------------------+----------+
+  | Option                  | Aliases                   | Description                                                 | Required |
+  +=========================+===========================+=============================================================+==========+
+  | project_id              | --project-id, --pid       | UUID of the project where the agent will be loaded          | Yes      |
+  +-------------------------+---------------------------+-------------------------------------------------------------+----------+
+  | file                    | --file, -f                | Path to the JSON file containing the agent definition        | Yes      |
+  +-------------------------+---------------------------+-------------------------------------------------------------+----------+
+  | automatic_publish       | --automatic-publish, --ap | Define if agent is published (1) or created as draft (0)     | Yes      |
+  +-------------------------+---------------------------+-------------------------------------------------------------+----------+
+
+- **Usage**:
+
+  .. code-block:: bash
+
+     geai spec load-agent --project-id 123e4567-e89b-12d3-a456-426614174000 --file agent.json --automatic-publish 0
+
+load-tool
+~~~~~~~~~
+
+- **Aliases**: ``load-tool``, ``lt``
+- **Description**: Loads one or more tool specifications from a JSON file into the AI Lab for a specified project, identified by a UUID.
+- **Options**:
+
+  +-------------------------+---------------------------+-----------------------------------------------------------+----------+
+  | Option                  | Aliases                   | Description                                               | Required |
+  +=========================+===========================+===========================================================+==========+
+  | project_id              | --project-id, --pid       | UUID of the project where the tool will be loaded         | Yes      |
+  +-------------------------+---------------------------+-----------------------------------------------------------+----------+
+  | file                    | --file, -f                | Path to the JSON file containing the tool definition      | Yes      |
+  +-------------------------+---------------------------+-----------------------------------------------------------+----------+
+  | automatic_publish       | --automatic-publish, --ap | Define if tool is published (1) or created as draft (0)   | Yes      |
+  +-------------------------+---------------------------+-----------------------------------------------------------+----------+
+
+- **Usage**:
+
+  .. code-block:: bash
+
+     geai spec load-tool --pid 987fcdeb-1a2b-3c4d-5e6f-7890abcd1234 -f tool.json --ap 1
+
+load-task
+~~~~~~~~~
+
+- **Aliases**: ``load-task``, ``ltask``
+- **Description**: Loads one or more task specifications from a JSON file into the AI Lab for a specified project, identified by a UUID.
+- **Options**:
+
+  +-------------------------+---------------------------+-----------------------------------------------------------+----------+
+  | Option                  | Aliases                   | Description                                               | Required |
+  +=========================+===========================+===========================================================+==========+
+  | project_id              | --project-id, --pid       | UUID of the project where the task will be loaded         | Yes      |
+  +-------------------------+---------------------------+-----------------------------------------------------------+----------+
+  | file                    | --file, -f                | Path to the JSON file containing the task definition      | Yes      |
+  +-------------------------+---------------------------+-----------------------------------------------------------+----------+
+  | automatic_publish       | --automatic-publish, --ap | Define if task is published (1) or created as draft (0)   | Yes      |
+  +-------------------------+---------------------------+-----------------------------------------------------------+----------+
+
+- **Usage**:
+
+  .. code-block:: bash
+
+     geai spec load-task --pid 456e7890-f1a2-4b3c-5d6e-8901bcde2345 -f task.json --ap 0
+
+load-agentic-process
+~~~~~~~~~~~~~~~~~~~~
+
+- **Aliases**: ``load-agentic-process``, ``lap``
+- **Description**: Loads one or more agentic process specifications from a JSON file into the AI Lab for a specified project, identified by a UUID.
+- **Options**:
+
+  +-------------------------+---------------------------+---------------------------------------------------------------------+----------+
+  | Option                  | Aliases                   | Description                                                         | Required |
+  +=========================+===========================+=====================================================================+==========+
+  | project_id              | --project-id, --pid       | UUID of the project where the agentic process will be loaded        | Yes      |
+  +-------------------------+---------------------------+---------------------------------------------------------------------+----------+
+  | file                    | --file, -f                | Path to JSON file containing agentic process definition             | Yes      |
+  +-------------------------+---------------------------+---------------------------------------------------------------------+----------+
+  | automatic_publish       | --automatic-publish, --ap | Define if process is published (1) or created as draft (0)          | Yes      |
+  +-------------------------+---------------------------+---------------------------------------------------------------------+----------+
+
+- **Usage**:
+
+  .. code-block:: bash
+
+     geai spec load-agentic-process --project-id 789a0bcd-2e3f-5c4d-6e7f-9012cdef3456 -f process.json --ap 1
+
+Usage Examples
+--------------
+
+Below are example commands demonstrating the usage of ``geai spec`` subcommands, using UUIDs for project IDs.
+
+**Example 1: Display Help**
+
+Display the help text for the ``geai spec`` command.
+
+.. code-block:: bash
+
+   geai spec help
+
+*Output* (example):
+
+.. code-block:: text
+
+   geai spec - Command Line Interface for Globant Enterprise AI
+   Usage: geai spec <subcommand> --[flag] [flag.arg]
+   Subcommands:
+     help, h                    Display help text
+     load-agent, la             Load agent from JSON specification
+     load-tool, lt              Load tool from JSON specification
+     load-task, ltask           Load task from JSON specification
+     load-agentic-process, lap  Load agentic process from JSON specification
+   ...
+
+**Example 2: Load a Single Agent**
+
+Load an agent from a JSON file into project with UUID ``123e4567-e89b-12d3-a456-426614174000`` as a draft.
+
+.. code-block:: bash
+
+   geai spec load-agent --project-id 123e4567-e89b-12d3-a456-426614174000 --file agent.json --automatic-publish 0
+
+*Output* (example):
+
+.. code-block:: text
+
+   Created agent detail:
+   <agent details>
+
+**Example 3: Load and Publish a Tool**
+
+Load a tool from a JSON file into project with UUID ``987fcdeb-1a2b-3c4d-5e6f-7890abcd1234`` and publish it.
+
+.. code-block:: bash
+
+   geai spec load-tool --pid 987fcdeb-1a2b-3c4d-5e6f-7890abcd1234 -f tool.json --ap 1
+
+*Output* (example):
+
+.. code-block:: text
+
+   Created tool detail:
+   <tool details>
+
+**Example 4: Load a Task**
+
+Load a task from a JSON file into project with UUID ``456e7890-f1a2-4b3c-5d6e-8901bcde2345`` as a draft.
+
+.. code-block:: bash
+
+   geai spec load-task --pid 456e7890-f1a2-4b3c-5d6e-8901bcde2345 -f task.json --ap 0
+
+*Output* (example):
+
+.. code-block:: text
+
+   Created task detail:
+   <task details>
+
+**Example 5: Load and Publish an Agentic Process**
+
+Load an agentic process from a JSON file into project with UUID ``789a0bcd-2e3f-5c4d-6e7f-9012cdef3456`` and publish it.
+
+.. code-block:: bash
+
+   geai spec load-agentic-process --project-id 789a0bcd-2e3f-5c4d-6e7f-9012cdef3456 -f process.json --ap 1
+
+*Output* (example):
+
+.. code-block:: text
+
+   Created agentic process detail:
+   <process details>
+
+**Example 6: Missing File Path (Error Case)**
+
+Attempt to load a task without specifying the file path.
+
+.. code-block:: bash
+
+   geai spec load-task --pid 456e7890-f1a2-4b3c-5d6e-8901bcde2345 --ap 0
+
+*Output*:
+
+.. code-block:: text
+
+   Error: Cannot load task definition without specifying path to JSON file.
+
+JSON Specification Formats
+--------------------------
+
+The ``load-agent``, ``load-tool``, ``load-task``, and ``load-agentic-process`` subcommands expect JSON files containing agent, tool, task, or agentic process specifications, respectively. The JSON file can contain a single specification (object) or multiple specifications (array).
+
+**Agent Specification Example**
+
+Below is an example of a single agent specification for a "Public Translator V2x" agent.
+
+.. code-block:: json
+
+   {
+     "name": "Public Translator V2x",
+     "accessScope": "private",
+     "publicName": "com.genexus.geai.public_translator_v2x",
+     "jobDescription": "Translates",
+     "avatarImage": "https://www.shareicon.net/data/128x128/2016/11/09/851442_logo_512x512.png",
+     "description": "Agent that translates from any language to english.",
+     "agentData": {
+       "prompt": {
+         "instructions": "the user will provide a text, you must return the same text translated to english",
+         "inputs": ["text", "avoid slang indicator"],
+         "outputs": [
+           {
+             "key": "translated_text",
+             "description": "translated text, with slang or not depending on the indication. in plain text."
+           },
+           {
+             "key": "summary",
+             "description": "a summary in the original language of the text to be translated, also in plain text."
+           }
+         ],
+         "examples": [
+           {
+             "inputData": "opitiiiis mundo [no-slang]",
+             "output": "{\"translated_text\":\"hello world\",\"summary\":\"saludo\"}"
+           },
+           {
+             "inputData": "esto es una prueba pincheguey [keep-slang]",
+             "output": "{\"translated_text\":\"this is a test pal\",\"summary\":\"prueba\"}"
+           }
+         ]
+       },
+       "llmConfig": {
+         "maxTokens": 5000,
+         "timeout": 0,
+         "sampling": {
+           "temperature": 0.5,
+           "topK": 0,
+           "topP": 0
+         }
+       },
+       "models": [
+         { "name": "gpt-4-turbo-preview" }
+       ]
+     }
+   }
+
+**Tool Specification Example**
+
+Below is an example of a single tool specification for a "Weather Forecaster" tool.
+
+.. code-block:: json
+
+   {
+     "name": "Weather Forecaster",
+     "description": "A builtin tool that provides weather forecasts based on location and date.",
+     "scope": "builtin",
+     "parameters": [
+       {
+         "key": "location_date",
+         "dataType": "String",
+         "description": "Location and date for the weather forecast (e.g., 'New York, 2025-05-22').",
+         "isRequired": true
+       },
+       {
+         "key": "forecast_type",
+         "dataType": "String",
+         "description": "Type of forecast (e.g., daily, hourly), configured statically.",
+         "isRequired": true,
+         "type": "config",
+         "fromSecret": false,
+         "value": "daily"
+       },
+       {
+         "key": "weather_api_key",
+         "dataType": "String",
+         "description": "API key for accessing the weather service, stored in secret manager.",
+         "isRequired": true,
+         "type": "config",
+         "fromSecret": true,
+         "value": "6f7a8b9c-0d1e-2f3a-4b5c-6d7e8f9a0b1c"
+       }
+     ]
+   }
+
+**Task Specification Example**
+
+Below is an example of a single task specification for an "Email Review v1" task.
+
+.. code-block:: json
+
+   {
+     "name": "Email Review v1",
+     "description": "A simple task to review and categorize email content, requiring no tools or prompts.",
+     "titleTemplate": "Email Review Task"
+   }
+
+**Agentic Process Specification Example**
+
+Below is an example of a single agentic process specification for a "Content Moderation Process."
+
+.. code-block:: json
+
+   {
+     "key": "content_moderation_proc",
+     "name": "Content Moderation Process",
+     "description": "A process to review and moderate user-generated content for compliance.",
+     "kb": {
+       "name": "content-moderation-kb",
+       "artifactTypeName": ["content-artifact"]
+     },
+     "agenticActivities": [
+       {
+         "key": "moderate_content",
+         "name": "Moderate Content",
+         "taskName": "content-moderation-task",
+         "agentName": "content-moderator",
+         "agentRevisionId": 0
+       }
+     ],
+     "artifactSignals": [
+       {
+         "key": "artifact.content.upload.1",
+         "name": "content.upload",
+         "handlingType": "C",
+         "artifactTypeName": ["content-artifact"]
+       }
+     ],
+     "userSignals": [
+       {
+         "key": "signal_content_done",
+         "name": "content-moderation-completed"
+       }
+     ],
+     "startEvent": {
+       "key": "artifact.content.upload.1",
+       "name": "content.upload"
+     },
+     "endEvent": {
+       "key": "end",
+       "name": "Done"
+     },
+     "sequenceFlows": [
+       {
+         "key": "step1",
+         "sourceKey": "artifact.content.upload.1",
+         "targetKey": "moderate_content"
+       },
+       {
+         "key": "step2",
+         "sourceKey": "moderate_content",
+         "targetKey": "signal_content_done"
+       },
+       {
+         "key": "stepEnd",
+         "sourceKey": "signal_content_done",
+         "targetKey": "end"
+       }
+     ]
+   }
+
+Error Handling
+--------------
+
+The ``geai spec`` subcommands may raise the following errors:
+
+- **MissingRequirementException**:
+  - Triggered if required options (``--project-id`` or ``--file``) are not provided.
+  - Example: ``Cannot load task definition without specifying path to JSON file.``
+- **File Loading Errors**:
+  - Invalid or inaccessible JSON files will cause errors during loading, logged and displayed to stderr.
+- **Parsing Errors**:
+  - Malformed JSON specifications may fail during parsing, with errors output to stderr.
+
+Notes
+-----
+
+- The ``project_id`` must be a valid UUID (e.g., ``123e4567-e89b-12d3-a456-426614174000``).
+- JSON files must conform to the expected format for agents, tools, tasks, or agentic processes, as shown in the examples above.
+- The ``automatic_publish`` option (0 or 1) determines whether the component is created as a draft or published immediately.
+- Ensure the project UUID exists in the AI Lab and the JSON file path is valid before running the command.
+- Multiple components can be loaded from a single JSON file if it contains an array of specifications.