initial commit

.env.example

@@ -0,0 +1,9 @@
+# LLM configuration for local testing
+LLM_PROVIDER=OPENAI
+LLM_MODEL=gpt-4.1
+LLM_API_KEY=sk-proj-
+# end LLM configuration
+
+# MCP server configuration for local testing
+MCP_SERVER_URL=https://dpc-restapi-mcp-server-75k7y.ondigitalocean.app/mcp/
+#MCP_SERVER_URL=http://0.0.0.0:8000/mcp/

.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env
+.idea/
+.vscode/
+.ruff_cache/

.python-version

@@ -0,0 +1 @@
+3.13

README.md

@@ -0,0 +1,93 @@
+# DPC MCP Client
+
+Bu proje, LangChain MCP Client kullanarak FASTMC-Server'ın streamablehttp protokolü üzerinden Product Catalog API'lerini çağırmak için tasarlanmış bir Gradio tabanlı chatbot uygulamasıdır.
+
+## 🚀 Özellikler
+
+- LangChain MCP Client entegrasyonu
+- Gradio tabanlı kullanıcı arayüzü
+- StreamableHTTP protokolü desteği
+- Product Catalog API entegrasyonu
+- Astral/UV paket yöneticisi desteği
+- Python 3.13 uyumluluğu
+
+## 📋 Gereksinimler
+
+- Python 3.13 veya üzeri
+- UV paket yöneticisi
+- Aşağıdaki çevre değişkenleri:
+
+```env
+AGENT_DEBUG=true
+LLM_PROVIDER=OPENAI
+LLM_API_KEY=your_api_key_here
+LLM_MODEL=your_model_name_here
+MCP_SERVER_URL=your_mcp_server_url_here
+```
+
+## 🛠️ Kurulum
+
+1. Projeyi klonlayın:
+```bash
+git clone https://github.com/yourusername/dpc_mcp_client.git
+cd dpc_mcp_client
+```
+
+2. UV ile bağımlılıkları yükleyin:
+```bash
+uv venv
+source .venv/bin/activate  # Linux/Mac
+# veya
+.venv\Scripts\activate  # Windows
+uv pip install -e .
+```
+
+## 🚀 Kullanım
+
+Uygulamayı başlatmak için:
+
+```bash
+uv run app.py
+```
+
+Uygulama başlatıldığında, tarayıcınızda Gradio arayüzü otomatik olarak açılacaktır. Bu arayüz üzerinden Product Catalog API'lerini sorgulayabilirsiniz.
+
+## 📁 Proje Yapısı
+
+```
+dpc_mcp_client/
+├── app.py              # Gradio UI ve ana uygulama
+├── mcp_client.py       # MCP Client implementasyonu
+├── resources/          # Kaynak dosyaları
+│   ├── instruction.txt
+│   └── dpc_restapi_summary.txt
+├── pyproject.toml      # Proje bağımlılıkları
+└── README.md
+```
+
+## 🔧 Bağımlılıklar
+
+- environs>=14.2.0
+- gradio>=5.32.1
+- langchain-mcp-adapters>=0.1.4
+- langchain-openai>=0.3.19
+- langgraph>=0.4.8
+- loguru>=0.7.3
+
+## 🤝 Katkıda Bulunma
+
+1. Bu depoyu fork edin
+2. Yeni bir özellik dalı oluşturun (`git checkout -b feature/amazing-feature`)
+3. Değişikliklerinizi commit edin (`git commit -m 'Add some amazing feature'`)
+4. Dalınıza push yapın (`git push origin feature/amazing-feature`)
+5. Bir Pull Request oluşturun
+
+## 📝 Lisans
+
+Bu proje MIT lisansı altında lisanslanmıştır. Daha fazla bilgi için `LICENSE` dosyasına bakın.
+
+## 📞 İletişim
+
+Proje Sahibi - [@yourusername](https://github.com/yourusername)
+
+Proje Linki: [https://github.com/yourusername/dpc_mcp_client](https://github.com/yourusername/dpc_mcp_client)

app.py

@@ -0,0 +1,62 @@
+# Gradio UI for local chatbot testing with MCP client
+import logging
+import asyncio
+import gradio as gr
+
+from mcp_client import MCPClient
+
+logger = logging.getLogger(__name__)
+
+async def initialize_client():
+    client = MCPClient()
+    await client.initialize()
+    return client
+
+def launch_ui():
+    with gr.Blocks(title="MCP Chatbot UI", fill_height=True, fill_width=True) as demo:
+        gr.Markdown("## Dnext Product Catalog AI Assistant")
+        gr.Markdown("Please wait while the AI assistant is initializing...")
+
+        chatbot = gr.Chatbot(height=600, label="Chatbot", type="messages")
+        msg = gr.Textbox(
+            label="Enter your request",
+            placeholder="Type your message here...",
+            lines=2
+        )
+        submit_btn = gr.Button("Submit")
+        clear_btn = gr.Button("Clear Chat")
+
+        async def respond(user_message):
+            bot_response = await client.invoke(user_message)
+            return [
+                {"role": "user", "content": user_message},
+                {"role": "assistant", "content": bot_response}
+            ]
+
+        def clear_chat():
+            return [], []
+
+        submit_btn.click(
+            fn=respond,
+            inputs=[msg],
+            outputs=[chatbot]
+        )
+        
+        clear_btn.click(
+            fn=clear_chat,
+            inputs=[],
+            outputs=[chatbot, msg]
+        )
+
+    return demo
+
+async def main():
+    global client
+    client = await initialize_client()
+    demo = launch_ui()
+    demo.launch(share=False)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+# uv run app.py

mcp_client.py

@@ -0,0 +1,111 @@
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.prebuilt import create_react_agent
+from langchain_mcp_adapters.tools import load_mcp_tools
+from langchain_openai import ChatOpenAI
+
+from environs import Env
+from loguru import logger
+
+env = Env()
+env.read_env()
+
+AGENT_DEBUG = env.bool("AGENT_DEBUG", True)
+LLM_PROVIDER = env.str("LLM_PROVIDER", "OPENAI")
+LLM_API_KEY = env.str("LLM_API_KEY")
+LLM_MODEL = env.str("LLM_MODEL")
+MCP_SERVER_URL = env.str("MCP_SERVER_URL")
+
+
+def get_llm():
+    if LLM_PROVIDER == "OPENAI":
+        return ChatOpenAI(model=LLM_MODEL, api_key=LLM_API_KEY)
+    elif LLM_PROVIDER == "GEMINI":
+        raise NotImplementedError("Gemini is not supported yet")
+    else:
+        raise ValueError(f"Unsupported LLM provider: {LLM_PROVIDER}")
+
+
+class MCPClient:
+    _instance = None
+
+    def __new__(cls):
+        logger.info("Creating MCP client instance...")
+        if cls._instance is None:
+            cls._instance = super(MCPClient, cls).__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        logger.info("Initializing MCP client instance...")
+        if self._initialized:
+            return
+
+        self.llm = get_llm()
+        self.tools = None
+        self.agent = None
+        self.instruction = ""
+        self.api_description = ""
+        self.system_message = ""
+        self._initialized = True
+        self.checkpointer = InMemorySaver()
+        self.load_instruction()
+        self.load_api_description()
+
+    def load_instruction(self) -> str:
+        logger.info("Loading instruction...")
+        try:
+            with open("resources/instruction.txt", "r") as file:
+                self.instruction = file.read()
+        except FileNotFoundError:
+            logger.error("Instruction file not found")
+            raise FileNotFoundError("Instruction file not found")
+
+    def load_api_description(self) -> str:
+        logger.info("Loading api description...")
+        try:
+            with open("resources/dpc_restapi_summary.txt", "r") as file:
+                self.api_description = file.read()
+        except FileNotFoundError:
+            logger.error("API description file not found")
+            raise FileNotFoundError("API description file not found")
+
+    async def initialize(self):
+        logger.info("Initializing MCP client...")
+        self.system_message = "".join([self.instruction, "\n\n", self.api_description])
+
+    async def invoke(self, input_messages):
+        logger.info(f"Invoking agent with input: {input_messages}")
+        async with streamablehttp_client(MCP_SERVER_URL) as (read, write, _):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                logger.info("Loading tools...")
+                self.tools = await load_mcp_tools(session)
+                logger.info("Creating agent...")
+                self.agent = create_react_agent(
+                    model=self.llm,
+                    tools=self.tools,
+                    prompt=self.system_message,
+                    checkpointer=self.checkpointer,
+                    debug=AGENT_DEBUG,
+                )
+                logger.info("Invoking agent...")
+                config = {"configurable": {"thread_id": "conversation_123"}}
+                result = await self.agent.ainvoke(input={"messages": input_messages}, config=config)
+                logger.info(f"Agent result: {result}")
+                logger.info("========================================================")
+                last_message = result["messages"][-1]
+                logger.info(f"Last message: {last_message.content}")
+                return last_message.content
+
+# Agent result: {'messages': 
+# [HumanMessage(content='hi', additional_kwargs={}, response_metadata={}, id='205d9484-c4f0-4e9e-962f-218d2e82bc03'),
+# AIMessage(content='This is just a greeting, so no API call is required. If you have any tasks or requests related to product catalog operations, please let me know how I can assist you!', 
+# additional_kwargs={'refusal': None}, 
+# response_metadata={'token_usage': {'completion_tokens': 37, 'prompt_tokens': 27124, 'total_tokens': 27161, 
+# 'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}, 
+# 'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 27008}}, 'model_name': 'gpt-4.1-2025-04-14', 
+# 'system_fingerprint': 'fp_799e4ca3f1', 'id': 'chatcmpl-BejXD72NDlc9UqrJiobIA6tQbuNaj', 'service_tier': 'default', 'finish_reason': 'stop', 'logprobs': None}, id='run--dee9f47d-99f9-40a6-b8c7-241668e6ac38-0', 
+# usage_metadata={'input_tokens': 27124, 'output_tokens': 37, 'total_tokens': 27161, 'input_token_details': {'audio': 0, 'cache_read': 27008}, 'output_token_details': {'audio': 0, 'reasoning': 0}})]}            

pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "dpc-mcp-client"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "environs>=14.2.0",
+    "gradio>=5.32.1",
+    "langchain-mcp-adapters>=0.1.4",
+    "langchain-openai>=0.3.19",
+    "langgraph>=0.4.8",
+    "loguru>=0.7.3",
+]

resources/dpc_restapi_summary.txt

@@ -0,0 +1,331 @@
+====================================================
+**API_DESCRIPTION_BEGIN** section is provided below.
+
+**Description:** Dnext Product Catalog API, which is compliant with the TMF620 Product Catalog Management standard.
+This API allows users to manage key catalog elements such as product offerings, specifications, characteristics, and pricing. 
+It meets TMF620 minimum requirements while incorporating Dnext-specific fields or validations.
+
+**API Base URL:**
+`https://learning.test.orbitant.dev/api/productCatalogManagement/v4`
+
+**Allowed Constant Enum Values**: Use these valid values for specific fields when constructing tool inputs.
+* **General Constant Enum Values:**
+    - lifecycleStatus: "In study", "In design", "In test", "Active", "Launched", "Retired", "Obsolete", "Rejected", "None"
+    - valueType: "string", "number", "date", "true/false", "integer", "time", "macAddress"
+    - unitOfMeasure: "Second", "Minute", "Hour", "Day", "Week", "Month", "Year", "M", "Mm", "Cm", "Km", "Kg", "Pound", "Bps", "Mbps", "Gbps", "Question", "Byte", "Mb", "Gb", "Tb", "None", "Address", "Color", "Duration", "Joule", "Number", "Phone Number", "Size", "Currency"
+    - characteristicType: "Simple Value", "Range", "Choice"
+    - rangeInterval: "Open", "Closed", "Closed Bottom", "Closed Top"
+    - relationshipType: "aggregation", "migration", "substitution", "dependency", "exclusivity"
+
+* **ProductSpecification Constant Enum Values:**
+    - operationType: "add", "delete", "modify", "modify.Migration", "modify.Relocation", "modify.Takeover", "statusChange", "statusChange.Resume", "statusChange.Suspend"
+    - relation: "reliesOn", "uses"
+
+* **ProductOffering Constant Enum Values:**
+    - operationType: same as ProductSpecification
+    - relation: "reliesOn"
+
+* **ProductOfferingPrice Constant Enum Values:**
+    - priceType: "One time charge", "Data tariff charge", "Simple usage charge", "Recurring charge", "Per line charge", "Parametric charge", "Per contract charge", "Voice tariff charge", "Simple usage discount", "Recurring discount", "Voice tariff discount", "One time discount", "One time allowance", "Recurring allowance", "Weekend allowance", "Weekend voice allowance", "Weekend data allowance", "Data commitment", "Threshold commitment", "Usage commitment", "Penalty", "Deposit", "Cost", "Upfront payment"
+    - Money.unit: "ALL", "AUD", "CHF", "GBP", "EUR", "USD", "JPY", "CAD", "CNY", "HKD", "NZD", "TRY"
+
+**Core API Entities and Their Attributes:**
+**1. ProductCatalog**
+* **Description:** The central organizing entity for product-related data. It groups `ProductOffering`s and `Category` objects.
+* **API Endpoints:**
+    * `POST /productCatalog`: Create a new product catalog.
+* **Fields (`ProductCatalogCreate` for POST):**
+    * `name` (string): **Mandatory**. The name of the catalog.
+    * `description` (string): Optional. Description of this catalog.
+    * `lifecycleStatus` (string): Optional. Used to indicate the current lifecycle status (e.g., "Active", "Retired", "Draft").
+    * `version` (string): Optional. Version of the catalog.
+    * `validFor` (`TimePeriod` object): Optional. The period for which the catalog is valid.
+    * `category` (array of `CategoryRef`): Optional. List of root categories contained in this catalog.
+    * `relatedParty` (array of `RelatedParty`): Optional. List of parties involved in this catalog.
+    * `@baseType`, `@schemaLocation`, `@type`: Optional meta-attributes for extension.
+
+**2. Category**
+* **Description:** Used for logically grouping product offerings. Categories can have a hierarchical structure (sub-categories).
+* **API Endpoints:**
+    * `POST /category`: Create a new category.
+* **Fields (`CategoryCreate` for POST):**
+    * `name` (string): **Mandatory**. The name of the category.
+    * `description` (string): Optional. Description of this category.
+    * `isRoot` (boolean): Optional. Indicates if this is a root category (default: `false`).
+    * `lifecycleStatus` (string): Optional. Used to indicate the current lifecycle status.
+    * `version` (string): Optional. Version of the category.
+    * `validFor` (`TimePeriod` object): Optional. The period for which the category is valid.
+    * `parent` (`CategoryRef` object): Optional. Reference to the parent category if this is a sub-category.
+    * `productCatalog` (array of `ProductCatalogRef`): Optional. References to the catalogs this category belongs to.
+    * `productOffering` (array of `ProductOfferingRef`): Optional. References to product offerings associated with this category.
+    * `relatedParty` (array of `RelatedParty`): Optional. Parties involved in this category.
+    * `@baseType`, `@schemaLocation`, `@type`: Optional meta-attributes.
+
+**3. ProductCharacteristic**
+* **Description:** Represents a characteristic (attribute) of a product or product specification.
+* **Usage:** Typically nested within `ProductSpecification` or `ProductOffering`.
+* **Fields:**
+    * `id` (string): Optional. Unique identifier.
+    * `name` (string): Optional. Name of the characteristic.
+    * `valueType` (string): Optional. Categorization of the value (e.g., "string", "integer", "boolean").
+    * `defaultValue` (object): Optional. The default value for this characteristic.
+    * `configurable` (boolean): Optional. True if configurable (default: false).
+    * `extensible` (boolean): Optional. True if extensible (default: false).
+    * `isUnique` (boolean): Optional. True if unique (default: false).
+    * `maxCardinality` (integer): Optional. Max instances.
+    * `minCardinality` (integer): Optional. Min instances.
+    * `regex` (string): Optional. Regex to validate the value.
+    * `validFor` (`TimePeriod` object): Optional. Period of validity.
+    * `productCharValue` (array of `ProductCharacteristicValue`): Optional. List of possible values.
+    * `@baseType`, `@schemaLocation`, `@type`: Optional meta-attributes.
+
+**4. ProductSpecification**
+* **Description:** Defines the technical details and attributes of a product or service.
+* **API Endpoints:**
+    * `POST /productSpecification`: Create a new product specifications.
+* **Fields (used when referencing or viewing):**
+    * `id` (string): **Mandatory** when referencing (e.g., in ProductOffering). Unique identifier.
+    * `href` (string): Optional. URL to the resource.
+    * `description` (string): Optional. Description.
+    * `isBundle` (boolean): Optional. True if a bundle specification.
+    * `lifecycleStatus` (string): Optional. Lifecycle status.
+    * `name` (string): Optional. Name of the specification.
+    * `productNumber` (string): Optional. Product number.
+    * `version` (string): Optional. Version.
+    * `validFor` (`TimePeriod` object): Optional. Period of validity.
+    * `productSpecCharacteristic` (array of `ProductCharacteristic`): Optional. List of characteristics for this specification.
+    * `serviceSpecification` (array of `ServiceSpecificationRef`): Optional. References to related service specifications.
+    * `resourceSpecification` (array of `ResourceSpecificationRef`): Optional. References to related resource specifications.
+    * `productSpecificationRelationship` (array of `ProductSpecificationRelationship`): Optional. Relationships with other specs.
+    * `attachment` (array of `AttachmentRefOrValue`): Optional. Related attachments.
+    * `relatedParty` (array of `RelatedParty`): Optional. Involved parties.
+    * `targetProductSchema` (`TargetProductSchema` object): Optional. Schema reference.
+    * `@baseType`, `@schemaLocation`, `@type`: Optional meta-attributes.
+
+**5. ProductOfferingPrice**
+* **Description:** Details the pricing information for a `ProductOffering`.
+* **API Endpoints:**
+    * `POST /productOfferingPrice`: Create a new product offering price.
+* **Fields (`ProductOfferingPriceCreate` for POST):**
+    * `name` (string): **Mandatory**. Name of the price (e.g., "Monthly Fee", "One-Time Setup").
+    * `description` (string): Optional. Description of the price.
+    * `priceType` (string): **Mandatory**. Type of price (e.g., "recurring", "one time", "usage").
+    * `validFor` (`TimePeriod` object): Optional. Period of validity for the price.
+    * `price` (`Money` object): **Mandatory**. The monetary value.
+        * `price.value` (number): **Mandatory**. Numeric price value.
+        * `price.unit` (string): **Mandatory**. Currency unit (e.g., "USD", "TRY").
+    * `recurringChargePeriod` (string): Optional. Period for recurring charges (e.g., "monthly", "annually").
+    * `unitOfMeasure` (`Quantity` object): Optional. Unit of measure if applicable (e.g., for usage-based).
+    * `taxIncluded` (boolean): Optional. True if tax is included.
+    * `taxRate` (number): Optional. Tax rate.
+    * `channel` (array of `ChannelRef`): Optional. Channels.
+    * `place` (array of `PlaceRef`): Optional. Places.
+    * `prodSpecCharValueUse` (array of `ProdSpecCharValueUse`): Optional. How characteristics influence price.
+    * `productOffering` (array of `ProductOfferingRef`): Optional. References to associated `ProductOffering`s.
+    * `productOfferingPriceRelationship` (array of `ProductOfferingPriceRelationship`): Optional. Relationships with other prices.
+    * `popRelationship` (array of `ProductOfferingPriceRelationship`): Optional. Alias for `productOfferingPriceRelationship`.
+    * `constraint` (array of `ConstraintRef`): Optional. Constraints.
+    * `pricingLogicAlgorithm` (array of `PricingLogicAlgorithmRef`): Optional. Pricing algorithms.
+    * `@baseType`, `@schemaLocation`, `@type`: Optional meta-attributes.
+
+**6. ProductOffering**
+* **Description:** Represents a product or service offered to customers, linking specifications, pricing, and catalog organization.
+* **API Endpoints:**
+    * `POST /productOffering`: Create a new product offering.
+* **Fields (`ProductOfferingCreate` for POST):**
+    * `name` (string): **Mandatory**. Name of the product offering.
+    * `description` (string): Optional. Description.
+    * `lifecycleStatus` (string): Optional. Lifecycle status (e.g., "Active", "Retired", "Pending").
+    * `statusReason` (string): Optional. Reason for current status.
+    * `isBundle` (boolean): Optional. True if a bundle (default: false).
+    * `isSellable` (boolean): Optional. True if sellable.
+    * `version` (string): Optional. Version.
+    * `validFor` (`TimePeriod` object): Optional. Period of validity.
+    * `category` (array of `CategoryRef`): References to categories this offering belongs to.
+    * `productSpecification` (`ProductSpecificationRef` object): **Mandatory**. Reference to the underlying product specification.
+    * `productOfferingPrice` (array of `ProductOfferingPriceRef`): Optional. References to associated prices.
+    * `channel` (array of `ChannelRef`): Optional. Channels.
+    * `place` (array of `PlaceRef`): Optional. Places.
+    * `agreement` (array of `AgreementRef`): Optional. Agreements.
+    * `bundledProductOffering` (array of `BundledProductOffering`): Optional. If `isBundle` is true, lists contained offerings.
+    * `resourceCandidate` (`ResourceCandidateRef` object): Optional. Resource candidate.
+    * `serviceCandidate` (`ServiceCandidateRef` object): Optional. Service candidate.
+    * `prodSpecCharValueUse` (array of `ProdSpecCharValueUse`): Optional. Defines char usage.
+    * `attachment` (array of `AttachmentRefOrValue`): Optional. Attachments.
+    * `relatedParty` (array of `RelatedParty`): Optional. Involved parties.
+    * `@baseType`, `@schemaLocation`, `@type`: Optional meta-attributes.
+
+**Common Referenced Objects:**
+* **`TimePeriod`:** `{ "startDateTime": "string (date-time)", "endDateTime": "string (date-time)" }`
+* **`Money`:** `{ "value": "number", "unit": "string" }`
+* **`Quantity`:** `{ "amount": "number", "unit": "string" }`
+* **Reference Objects (`ProductCatalogRef`, `CategoryRef`, `ProductSpecificationRef`, `ProductOfferingPriceRef`, etc.):**
+    * Typically contain `id` (string), `href` (string), `name` (string), and `@referredType` (string).
+    * Example: `{"id": "some-id", "href": "path/to/resource/some-id", "name": "Resource Name", "@referredType": "ProductCatalog"}`
+* **`RelatedParty`:** `{ "id": "string", "href": "string", "name": "string", "role": "string", ...}`
+
+**Creating an Offer Process Documentation (Sequential Steps with Payloads):**
+To create a complete product offer in the system, you need to follow these sequential steps, making a POST request for each. Note that the IDs generated in previous steps are often used as references in subsequent steps.
+
+**Step 1: Create a Product Characteristic**
+* **Description:** Defines a unique attribute of a product, like speed or storage.
+* **Request URL:** `POST https://learning.test.orbitant.dev/api/productCatalogManagement/v4/productCharacteristic`
+* **Example Payload:**
+    ```json
+    {
+        "characteristicType": "Simple Value",
+        "configurable": false,
+        "extensible": false,
+        "isUnique": false,
+        "isVisible": false,
+        "isModifiable": false,
+        "mandatory": false,
+        "minCardinality": 0,
+        "maxCardinality": 1,
+        "name": "testSaturn",
+        "productCharacteristicValue": [
+            {
+                "isDefault": false,
+                "unitOfMeasure": "MBPS",
+                "value": "1000",
+                "valueType": "string"
+            }
+        ],
+        "valueType": "string"
+    }
+    ```
+    * **Explanation:** This payload creates a characteristic named 'testSaturn' with a value of '1000 MBPS', defining its behavior (e.g., not configurable, not mandatory). You would typically obtain the `id` from the response of this call for use in subsequent steps.
+
+**Step 2: Create a Product Offering Price**
+* **Description:** Defines the pricing structure for a product, including its value, type, and unit of measure.
+* **Request URL:** `POST https://learning.test.orbitant.dev/api/productCatalogManagement/v4/productOfferingPrice`
+* **Example Payload:**
+    ```json
+    {
+        "name": "testSaturnPrice",
+        "version": "0",
+        "priceType": "One time charge",
+        "unitOfMeasure": {
+            "units": "Day",
+            "amount": 1
+        },
+        "recurringChargePeriodType": "monthly",
+        "recurringChargePeriodLength": 0,
+        "isBundle": false,
+        "lifecycleStatus": "In study",
+        "price": {
+            "value": 100,
+            "unit": "USD"
+        },
+        "percentage": 0
+    }
+    ```
+    * **Explanation:** This payload defines a one-time price of 100 USD for a product offering. It specifies the price type, currency, and any recurring charge details. You would typically obtain the `id` from the response of this call.
+
+**Step 3: Create a Product Specification**
+* **Description:** Ties product characteristics and their values together to define the technical details of a product.
+* **Request URL:** `POST https://learning.test.orbitant.dev/api/productCatalogManagement/v4/productSpecification`
+* **Example Payload:**
+    ```json
+    {
+        "name": "testSaturnSpec",
+        "isBundle": false,
+        "lifecycleStatus": "In study",
+        "version": "0",
+        "productSpecCharacteristic": [
+            {
+                "id": "GENERATED_PRODUCT_CHARACTERISTIC_ID_FROM_STEP1",
+                "name": "testSaturn",
+                "characteristicType": "Simple Value",
+                "valueType": "string",
+                "configurable": false,
+                "isVisible": false,
+                "mandatory": false,
+                "extensible": false,
+                "minCardinality": 0,
+                "maxCardinality": 1,
+                "isUnique": false,
+                "productSpecCharacteristicValue": [
+                    {
+                        "valueType": "string",
+                        "value": "1000",
+                        "unitOfMeasure": "MBPS",
+                        "isDefault": false
+                    }
+                ],
+                "@type": "ProductCharacteristic",
+                "@baseType": "ProductCharacteristic"
+            }
+        ]
+    }
+    ```
+    * **Explanation:** This payload creates a product specification. It includes the `id` of the `ProductCharacteristic` created in Step 1, associating that characteristic with this specification. You would typically obtain the `id` from the response of this call.
+
+**Step 4: Create a Product Offering**
+* **Description:** Combines the product specification and pricing to form a complete, sellable offer.
+* **Request URL:** `POST https://learning.test.orbitant.dev/api/productCatalogManagement/v4/productOffering`
+* **Example Payload:**
+    ```json
+    {
+        "name": "testSaturnOffer",
+        "isBundle": false,
+        "lastUpdate": "2025-05-28T11:57:27.670Z",
+        "lifecycleStatus": "In study",
+        "version": "0",
+        "isSellable": false,
+        "productSpecification": {
+            "id": "GENERATED_PRODUCT_SPECIFICATION_ID_FROM_STEP3",
+            "href": "/api/productCatalogManagement/v4/productSpecification/GENERATED_PRODUCT_SPECIFICATION_ID_FROM_STEP3:(version=0)",
+            "name": "testSaturnSpec",
+            "version": "0"
+        },
+        "productOfferingPrice": [
+            {
+                "id": "GENERATED_PRODUCT_OFFERING_PRICE_ID_FROM_STEP2",
+                "href": "/api/productCatalogManagement/v4/productOfferingPrice/GENERATED_PRODUCT_OFFERING_PRICE_ID_FROM_STEP2:(version=0)",
+                "name": "testSaturnPrice",
+                "version": "0",
+                "@type": "ProductOfferingPrice",
+                "@referredType": "Product Offering Price"
+            }
+        ],
+        "prodSpecCharValueUse": [
+            {
+                "productSpecCharacteristicValue": [
+                    {
+                        "isDefault": false,
+                        "unitOfMeasure": "MBPS",
+                        "value": "1000",
+                        "valueType": "string"
+                    }
+                ],
+                "name": "testSaturn",
+                "characteristicType": "Simple Value",
+                "valueType": "string",
+                "minCardinality": 0,
+                "maxCardinality": 1,
+                "productSpecification": {
+                    "id": "GENERATED_PRODUCT_SPECIFICATION_ID_FROM_STEP3",
+                    "href": "/api/productCatalogManagement/v4/productSpecification/GENERATED_PRODUCT_SPECIFICATION_ID_FROM_STEP3:(version=0)",
+                    "name": "testSaturnSpec",
+                    "version": "0"
+                },
+                "configurable": false,
+                "isVisible": false,
+                "mandatory": false
+            }
+        ],
+        "category": [
+             // MANDATORY: Add a CategoryRef here (e.g., after creating a category via /category endpoint)
+             // Example: {"id": "category-id", "href": "/api/productCatalogManagement/v4/category/category-id", "name": "Category Name", "@referredType": "Category"}
+        ],
+        "productCatalog": [
+            // MANDATORY: Add a ProductCatalogRef here (e.g., after creating a catalog via /productCatalog endpoint)
+            // Example: {"id": "catalog-id", "href": "/api/productCatalogManagement/v4/productCatalog/catalog-id", "name": "Catalog Name", "@referredType": "ProductCatalog"}
+        ]
+    }
+    ```
+    * **Explanation:** This payload defines the complete `ProductOffering`. It references the `ProductSpecification` (from Step 3) and `ProductOfferingPrice` (from Step 2) using their generated IDs. It also re-iterates the product characteristic details for clarity within the offer. **Crucially, it requires `category` and `productCatalog` references which would need to be created via their respective endpoints first, if not already existing.**
+
+**API_DESCRIPTION_END**
+====================================================

resources/instruction.txt

@@ -0,0 +1,36 @@
+# Role
+You are a reasoning and planning agent that translates natural language inputs into structured API requests.
+
+# Goal
+Your goal is to interpret user prompts and return an API call plan targeting the **DNext Product Catalog Management API(TMF620)**.
+
+# Capability
+- Understand user intent expressed in natural language.
+- Identify the appropriate endpoint from the TMF620 OpenAPI spec.
+- Determine the correct HTTP method.
+- Extract path parameters, query parameters, and body payload as needed.
+- Return a structured plan (do not execute the API).
+- Ask clarifying questions if critical information is missing.
+
+# Input Format
+Users will input natural language requests related to product catalog operations.
+
+# Output Format
+Respond with:
+1. A short reasoning trace (in English) that explains your decision.
+2. A structured API call in JSON with fields: `method`, `endpoint`, `path_params`, `query_params`, `payload`.
+
+# Constraint
+- Do not fabricate endpoint names or parameters.
+- If unsure, ask a follow-up question.
+- Do not include any irrelevant information or execute the request.
+
+# Sample UseCase
+1- When the user asks you to create a new product offering, **use the previously stored `id` and `href` values** to populate the required links to the:
+- product specification,
+- product offering price,
+- product characteristics
+
+# API Description
+Api description is provided below between **API_DESCRIPTION_BEGIN** and **API_DESCRIPTION_END**. Use this description to understand the API, its endpoints, and the parameters for each endpoint.
+