feat: add invoice data retrieval (#247)

Co-authored-by: pratrivedi <[email protected]>

integrations/invoice-data-retrieval/README.md

@@ -0,0 +1,46 @@
+# Invoice Data Retrieval
+
+This demonstrates an Invoice Data Retrieval agent that utilizes the pdf.ai API to upload and retrieve information from an invoice PDF. The agent is designed to handle requests for invoice data, process the PDF, and respond with the extracted information.
+
+## Getting Started
+
+Before using this agent, you need to obtain an API_KEY from pdf.ai. Follow these steps:
+
+1. Visit [pdf.ai](https://pdf.ai/) to sign up and create an account.
+2. After signing in, navigate to your account settings or dashboard to find the API_KEY.
+3. Copy the API_KEY and replace the placeholder `API_KEY` in the script with your actual API_KEY.
+
+# Agent Secrets on Agentverse
+
+1. Go to the Agentverse platform.
+2. Navigate to the Agent Secrets section.
+3. Create an agent and copy the code in it
+4. Add a new secret with the key `API_KEY` and the value as your API KEY.
+
+# Steps to Enroll an Agent as a Service on Agentverse
+
+You can integrate into DeltaV your Agents created on your local computer, IoT devices, in the VMs, or agents created on Agentverse. The steps are the same.
+
+Once your agents are run, the agent protocol manifests are uploaded to the Almanac contract in the form of protocol digests. After uploading the manifests, we take the agent addresses and enroll the agents as a service under the "Services" tab in Agentverse.
+
+## Agent Validation on Agentverse Explorer
+*Note: You can validate the procedure by searching for your agent's address on Agent Explorer, checking if the protocols have been uploaded successfully. If not, you need to wait for some time (1-2 minutes) until the protocols are uploaded successfully.*
+
+## Create a Service Group
+
+1. Start by creating a new service group on Agentverse.
+2. Set up the service group as PRIVATE (you will only be able to see your own agents).
+   - If you set up your service group as Public, anyone will be able to see your agents.
+
+**Service group has been created.**
+
+## Create a Service
+
+1. To register the agents as a service, input a concise title and description for the agent service.
+2. Choose the service group for the agent service that you've created previously.
+3. Fill in the agent address in the Agent field.
+4. Set the task type to Task.
+
+![Image](./image.png)
+
+Now, your agents are enrolled as a service in Agentverse. You can manage and monitor them under the "Services" tab. Ensure that you follow the agent validation steps on Agent Explorer to confirm successful enrollment.

integrations/invoice-data-retrieval/agent.py

@@ -0,0 +1,82 @@
+from ai_engine import UAgentResponse, UAgentResponseType
+import requests
+
+# Define the Invoice Data Request model
+class InvoiceDataRequest(Model):
+    url: str  # URL of the invoice PDF
+    query: str = None  # Optional query about the invoice
+
+# Define the protocol for Invoice Data Retrieval
+invoice_data_protocol = Protocol("Invoice Data Retrieval")
+
+def upload_pdf(url, ctx):
+    """Uploads a PDF from a URL and returns the document ID."""
+    endpoint = "https://pdf.ai/api/v1/upload/url"
+    headers = {"X-API-Key": API_KEY}
+    payload = {"url": url, "isPrivate": False, "ocr": False}
+
+    ctx.logger.info(f"Uploading invoice PDF for URL: {url}")
+    try:
+        response = requests.post(endpoint, json=payload, headers=headers)
+        response.raise_for_status()
+        docId = response.json().get("docId")
+        ctx.logger.info(f"Invoice PDF uploaded successfully, docId: {docId}")
+        return docId
+    except Exception as e:
+        ctx.logger.error(f"Error during invoice PDF upload: {e}")
+        return None
+
+def get_invoice_data(doc_id, query, ctx):
+    """Retrieves invoice data in JSON format using the docId."""
+    endpoint = "https://pdf.ai/api/v1/invoice"
+    headers = {"X-API-Key": API_KEY}
+    payload = {"docId": doc_id, "message": query} if query else {"docId": doc_id}
+
+    ctx.logger.info(f"Retrieving invoice data with docId: {doc_id}")
+    try:
+        response = requests.post(endpoint, json=payload, headers=headers)
+        ctx.logger.info(f"Response Status: {response.status_code}")
+        ctx.logger.info(f"Response Body: {response.text}")
+        response.raise_for_status()
+        content = response.json().get("content")
+        ctx.logger.info(f"content: {content}")
+        return content
+    except Exception as e:
+        ctx.logger.error(f"Error retrieving invoice data: {e}")
+        return None
+
+@invoice_data_protocol.on_message(model=InvoiceDataRequest, replies=UAgentResponse)
+async def on_message(ctx: Context, sender: str, msg: InvoiceDataRequest):
+    ctx.logger.info(f"Received invoice data request from {sender} for URL: {msg.url}")
+
+    try:
+        doc_id = upload_pdf(msg.url, ctx)
+        if not doc_id:
+            raise Exception("Failed to upload invoice PDF.")
+
+        invoice_data = get_invoice_data(doc_id, msg.query, ctx)
+        if invoice_data is None:
+            raise Exception("Failed to retrieve invoice data.")
+
+        invoice_data_str = str(invoice_data)
+
+        await ctx.send(
+            sender,
+            UAgentResponse(
+                message=invoice_data_str,
+                type=UAgentResponseType.FINAL
+            )
+        )
+
+    except Exception as exc:
+        ctx.logger.error(f"An error occurred: {exc}")
+        await ctx.send(
+            sender,
+            UAgentResponse(
+                message=f"Error: {exc}",
+                type=UAgentResponseType.ERROR
+            )
+        )
+
+# Include the Invoice Data Retrieval protocol in your agent
+agent.include(invoice_data_protocol)

integrations/invoice-data-retrieval/project.json

@@ -0,0 +1,5 @@
+{
+    "title": "Invoice Data Retrieval",
+    "description": "This demonstrates an Invoice Data Retrieval agent that utilizes the pdf.ai API to upload and retrieve information from an invoice PDF",
+    "categories":    ["Text Summarization", "Text Generation"]
+}