agentstr 0.1.7__py3-none-any.whl → 0.1.8__py3-none-any.whl

agentstr/nostr.py

@@ -1,53 +1,193 @@
+import logging
 from typing import Optional
-from os import getenv
-import logging 
 
-try: 
+try:
     import asyncio
 except ImportError:
-    raise ImportError("`asyncio` not installed. Please install using `pip install asyncio`")
+    raise ImportError(
+        "`asyncio` not installed. Please install using `pip install asyncio`"
+    )
 
 try:
-    from nostr_sdk import Keys, Client, EventBuilder, NostrSigner, SendEventOutput, Event, Metadata
+    from nostr_sdk import (
+        Client,
+        Coordinate,
+        Event,
+        EventBuilder,
+        EventId,
+        Keys,
+        Kind,
+        Metadata,
+        NostrSigner,
+        ProductData,
+        PublicKey,
+        ShippingCost,
+        ShippingMethod,
+        StallData,
+        Tag,
+        Timestamp,
+    )
+
 except ImportError:
-    raise ImportError("`nostr_sdk` not installed. Please install using `pip install nostr_sdk`")
+    raise ImportError(
+        "`nostr_sdk` not installed. Please install using `pip install nostr_sdk`"
+    )
+
+
+class NostrClient:
+    """
+    NostrClient implements the set of Nostr utilities required for higher level functions implementing
+    like the Marketplace.
+
+    Nostr is an asynchronous communication protocol. To hide this, NostrClient exposes synchronous functions.
+    Users of the NostrClient should ignore `_async_` functions which are for internal purposes only.
+    """
 
-class NostrClient():
-   
     logger = logging.getLogger("NostrClient")
     ERROR: str = "ERROR"
     SUCCESS: str = "SUCCESS"
-    
+
     def __init__(
         self,
-        relay: str = None,
-        nsec: str = None,
-    ):
-        """Initialize the Nostr client.
+        relay: str,
+        nsec: str,
+    ) -> None:
+        """
+        Initialize the Nostr client.
 
         Args:
-            relay: Nostr relay that the client will connect to 
+            relay: Nostr relay that the client will connect to
             nsec: Nostr private key in bech32 format
         """
         # Set log handling
         if not NostrClient.logger.hasHandlers():
             console_handler = logging.StreamHandler()
             console_handler.setLevel(logging.INFO)
-            formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+            formatter = logging.Formatter(
+                "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+            )
             console_handler.setFormatter(formatter)
             NostrClient.logger.addHandler(console_handler)
-       
+
+        # configure relay and keys for the client
         self.relay = relay
         self.keys = Keys.parse(nsec)
         self.nostr_signer = NostrSigner.keys(self.keys)
         self.client = Client(self.nostr_signer)
-            
 
-    async def connect(
-        self
-    ) -> str:
-        
-        """Add relay to the NostrClient instance and connect to it.
+    def delete_event(self, event_id: EventId, reason: Optional[str] = None) -> EventId:
+        """
+        Requests the relay to delete an event. Relays may or may not honor the request.
+
+        Args:
+            event_id: EventId associated with the event to be deleted
+            reason: optional reason for deleting the event
+
+        Returns:
+            EventId: if of the event requesting the deletion of event_id
+
+        Raises:
+            RuntimeError: if the deletion event can't be published
+        """
+        event_builder = EventBuilder.delete(ids=[event_id], reason=reason)
+        # Run the async publishing function synchronously
+        return asyncio.run(self._async_publish_event(event_builder))
+
+    def publish_event(self, event_builder: EventBuilder) -> EventId:
+        """
+        Publish generic Nostr event to the relay
+
+        Returns:
+            EventId: event id if successful or NostrClient.ERROR if unsuccesful
+
+        Raises:
+            RuntimeError: if the product can't be published
+        """
+        # Run the async publishing function synchronously
+        return asyncio.run(self._async_publish_event(event_builder))
+
+    def publish_note(self, text: str) -> EventId:
+        """Publish note with event kind 1
+
+        Args:
+            text: text to be published as kind 1 event
+
+        Returns:
+            EventId: EventId if successful or NostrClient.ERROR if unsuccesful
+
+        Raises:
+            RuntimeError: if the product can't be published
+        """
+        # Run the async publishing function synchronously
+        return asyncio.run(self._async_publish_note(text))
+
+    def publish_product(self, product: ProductData) -> EventId:
+        """
+        Create or update a NIP-15 Marketplace product with event kind 30018
+
+        Args:
+            product: product to be published
+
+        Returns:
+            EventId: event id if successful or NostrClient.ERROR if unsuccesful
+
+        Raises:
+            RuntimeError: if the product can't be published
+        """
+        # Run the async publishing function synchronously
+        return asyncio.run(self._async_publish_product(product))
+
+    def publish_profile(self, name: str, about: str, picture: str) -> EventId:
+        """
+        Publish a Nostr profile with event kind 0
+
+        Args:
+            name: name of the Nostr profile
+            about: brief description about the profile
+            picture: url to a png file with a picture for the profile
+
+        Returns:
+            EventId: event id if successful or NostrClient.ERROR if unsuccesful
+
+        Raises:
+            RuntimeError: if the profile can't be published
+        """
+        # Run the async publishing function synchronously
+        return asyncio.run(self._async_publish_profile(name, about, picture))
+
+    def publish_stall(self, stall: StallData) -> EventId:
+        """Publish a stall to nostr
+
+        Args:
+            stall: stall to be published
+
+        Returns:
+            EventId: event id if successful or NostrClient.ERROR if unsuccesful
+        """
+        try:
+            return asyncio.run(self._async_publish_stall(stall))
+        except Exception as e:
+            self.logger.error(f"Failed to publish stall: {e}")
+            return NostrClient.ERROR
+
+    @classmethod
+    def set_logging_level(cls, logging_level: int) -> None:
+        """Set the logging level for the NostrClient logger.
+
+        Args:
+            logging_level: The logging level (e.g., logging.DEBUG, logging.INFO)
+        """
+        cls.logger.setLevel(logging_level)
+        for handler in cls.logger.handlers:
+            handler.setLevel(logging_level)
+        cls.logger.info(f"Logging level set to {logging.getLevelName(logging_level)}")
+
+    # ----------------------------------------------------------------------------------------------
+    # --*-- async functions for internal use only. Developers should use synchronous functions above
+    # ----------------------------------------------------------------------------------------------
+
+    async def _async_connect(self) -> str:
+        """Asynchronous function to add relay to the NostrClient instance and connect to it.
 
         Returns:
             str: NostrClient.SUCCESS or NostrClient.ERROR
@@ -59,83 +199,129 @@ class NostrClient():
             NostrClient.logger.info("Connected to relay.")
             return NostrClient.SUCCESS
         except Exception as e:
-            NostrClient.logger.error(f"Unable to connect to relay {self.relay}. Exception: {e}.")
+            NostrClient.logger.error(
+                f"Unable to connect to relay {self.relay}. Exception: {e}."
+            )
             return NostrClient.ERROR
-        
-    async def publish_text_note(
-        self,
-        text: str
-    ) -> str:
-        
-        """Publish kind 1 event (text note) to the relay 
 
-        Args:
-            text: text to be published as kind 1 event
+    async def _async_publish_event(self, event_builder: EventBuilder) -> EventId:
+        """
+        Publish generic Nostr event to the relay
 
         Returns:
-            str: event id if successful and "error" string if unsuccesful
+            EventId: event id of the published event
+
+        Raises:
+            RuntimeError: if the event can't be published
         """
-        builder = EventBuilder.text_note(text)
+        connected = await self._async_connect()
+
+        if connected == NostrClient.ERROR:
+            raise RuntimeError("Unable to connect to the relay")
 
         try:
-            output = await self.client.send_event_builder(builder)
-            NostrClient.logger.info(f"Text note published with event id: {output.id.to_bech32()}")
-            return output.id.to_bech32()
+            output = await self.client.send_event_builder(event_builder)
+            if len(output.success) > 0:
+                NostrClient.logger.info(
+                    f"Event published with event id: {output.id.to_bech32()}"
+                )
+                return output.id
+            else:
+                raise RuntimeError("Unable to publish event")
         except Exception as e:
-            NostrClient.logger.error(f"Unable to publish text note to relay {self.relay}. Exception: {e}.")
-            return NostrClient.ERROR
+            NostrClient.logger.error(
+                f"NostrClient instance not properly initialized. Exception: {e}."
+            )
+            raise RuntimeError(
+                f"NostrClient instance not properly initialized. Exception: {e}."
+            )
 
-    async def publish_event(
-        self,
-        builder: EventBuilder
-    ) -> str:
-        
-        """Publish generic Nostr event to the relay
+    async def _async_publish_note(self, text: str) -> EventId:
+        """
+        Asynchronous funcion to publish kind 1 event (text note) to the relay
+
+        Args:
+            text: text to be published as kind 1 event
 
         Returns:
-            str: event id if successful or "error" string if unsuccesful
+            EventId: event id if successful or NostrClient.ERROR if unsuccesful
+
+        Raises:
+            RuntimeError: if the event can't be published
         """
-        try:
-            output = await self.client.send_event_builder(builder)
-            NostrClient.logger.info(f"Event published with event id: {output.id.to_bech32()}")
-            return output.id.to_bech32()
-        except Exception as e:
-            NostrClient.logger.error(f"Unable to publish event to relay {self.relay}. Exception: {e}.")
-            return NostrClient.ERROR
-    
-    async def publish_profile(self, name: str, about: str, picture: str) -> str:
-        """Publish a Nostr profile.
+        event_builder = EventBuilder.text_note(text)
+        return await self._async_publish_event(event_builder)
+
+    async def _async_publish_product(self, product: ProductData) -> EventId:
+        """
+        Asynchronous function to create or update a NIP-15 Marketplace product with event kind 30018
+
+        Args:
+            product: product to publish
+
+        Returns:
+            EventId: event id if successful or NostrClient.ERROR if unsuccesfull
+
+        Raises:
+            RuntimeError: if the product can't be published
+        """
+        coordinate_tag = Coordinate(
+            Kind(30017), self.keys.public_key(), product.stall_id
+        )
+
+        # EventBuilder.product_data() has a bug with tag handling.
+        # We use the function to create the content field and discard the eventbuilder
+        bad_event_builder = EventBuilder.product_data(product)
+
+        # create an event from bad_event_builder to extract the content - not broadcasted
+        bad_event = await self.client.sign_event_builder(bad_event_builder)
+        content = bad_event.content()
+
+        # build a new event with the right tags and the content
+        good_event_builder = EventBuilder(Kind(30018), content).tags(
+            [Tag.identifier(product.id), Tag.coordinate(coordinate_tag)]
+        )
+        self.logger.info("Product event: " + str(good_event_builder))
+        return await self._async_publish_event(good_event_builder)
+
+    async def _async_publish_profile(
+        self, name: str, about: str, picture: str
+    ) -> EventId:
+        """
+        Asynchronous function to publish a Nostr profile with event kind 0
 
         Args:
             name: name of the Nostr profile
             about: brief description about the profile
             picture: url to a png file with a picture for the profile
-        
+
         Returns:
-            str: event id if successful or "error" string if unsuccesful
+            EventId: event id if successful or NostrClient.ERROR if unsuccesful
+
+        Raises:
+            RuntimeError: if the profile can't be published
         """
         metadata_content = Metadata().set_name(name)
         metadata_content = metadata_content.set_about(about)
         metadata_content = metadata_content.set_picture(picture)
 
-        builder = EventBuilder.metadata(metadata_content)
-        try:
-            output = await self.client.send_event_builder(builder)
-            NostrClient.logger.info(f"Profile note published with event id: {output.id.to_bech32()}")
-            return output.id.to_bech32()
-        except Exception as e:
-            NostrClient.logger.error(f"Unable to publish profile to relay {self.relay}. Exception: {e}.")
-            return NostrClient.ERROR
+        event_builder = EventBuilder.metadata(metadata_content)
+        return await self._async_publish_event(event_builder)
 
-    @classmethod
-    def set_logging_level(cls, logging_level: int):
+    async def _async_publish_stall(self, stall: StallData) -> EventId:
         """
-        Set the logging level for the NostrClient logger.
+        Asynchronous function to create or update a NIP-15 Marketplace stall with event kind 30017
 
         Args:
-           logging_level (int): The logging level (e.g., logging.DEBUG, logging.INFO).
+            stall: stall to be published
+
+        Returns:
+            EventId: event id if successful or NostrClient.ERROR if unsuccesfull
+
+        Raises:
+            RuntimeError: if the profile can't be published
         """
-        cls.logger.setLevel(logging_level)
-        for handler in cls.logger.handlers:
-           handler.setLevel(logging_level)
-        cls.logger.info(f"Logging level set to {logging.getLevelName(logging_level)}")
+
+        self.logger.info(f"Stall: {stall}")
+        event_builder = EventBuilder.stall_data(stall)
+        return await self._async_publish_event(event_builder)

{agentstr-0.1.7.dist-info → agentstr-0.1.8.dist-info}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Synvya
+Copyright (c) 2025 Synvya
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

agentstr-0.1.8.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.2
+Name: agentstr
+Version: 0.1.8
+Summary: Nostr extension for Phidata AI agents
+Project-URL: Homepage, https://github.com/synvya/agentstr
+Project-URL: Documentation, https://github.com/synvya/agentstr#readme
+Project-URL: BugTracker, https://github.com/synvya/agentstr/issues
+Requires-Python: <3.13,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: phidata>=2.7.0
+Requires-Dist: openai>=1.50.0
+Requires-Dist: packaging>=24.0
+Requires-Dist: nostr-sdk>=0.38.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: python-dotenv>=1.0; extra == "dev"
+
+# AgentStr
+
+AgentStr is an extension of [Phidata](https://www.phidata.com) AI agents that enables peer-to-peer agent communication using the Nostr protocol.
+
+## Overview
+
+AgentStr allows AI agents operated by different organizations to communicate and collaborate. For example:
+- Agent A from Company A can coordinate with Agent B from Company B to execute a transaction
+- Agents can discover and interact with each other through the decentralized Nostr network
+- No central authority or intermediary required
+
+## Project Structure
+
+```
+agentstr/
+├── src/              # Source code
+│   └── agentstr/
+│       ├── __init__.py
+│       ├── marketplace.py
+│       └── nostr.py
+├── tests/            # Test files
+├── docs/             # Documentation
+├── examples/         # Example implementations
+└── ...
+```
+
+## Features
+
+### Current Features
+- Create Merchant agents with Nostr identities
+- Publish and manage merchant products using [NIP-15](https://github.com/nostr-protocol/nips/blob/master/15.md) marketplace protocol
+- Create merchant stalls to organize products
+- Handle shipping zones and costs
+- Secure communication using Nostr keys
+
+### Roadmap
+- [ ] Create marketplace with stalls
+- [ ] Create Buyer agents
+- [ ] Enable merchants to define products
+- [ ] Add customer toolkit for buyers
+- [ ] Support additional Nostr NIPs
+- [ ] Add more agent interaction patterns
+
+## Installation
+
+```bash
+# Create a new python environment
+python3 -m venv ~/.venvs/aienv
+source ~/.venvs/aienv/bin/activate
+
+# Install agentstr
+pip install --upgrade pip
+pip install agentstr
+```
+
+## Examples
+
+See our [examples directory](examples/) for complete working implementations:
+
+- [Basic CLI Agent](examples/basic_cli/main.py) - A complete example showing:
+  - Setting up merchant profiles
+  - Creating stalls with shipping methods
+  - Defining products with shipping costs
+  - Configuring the agent with the merchant toolkit
+  - Running an interactive CLI application
+
+
+## Documentation
+
+For more detailed documentation and examples, see [Docs](docs/docs.md) 
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+- Development setup
+- Testing instructions
+- Contribution guidelines
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- [Phidata](https://www.phidata.com) - For their AI agent framework
+- [Rust-Nostr](https://rust-nostr.org) - For their Python Nostr SDK
+- [Nostr Protocol](https://github.com/nostr-protocol/nips) - For the protocol specification
+

agentstr-0.1.8.dist-info/RECORD

@@ -0,0 +1,8 @@
+agentstr/__init__.py,sha256=bPXCN4fDtqII9UtDCwhWhkR6bi1LR4w0rR0vGeKPNoI,567
+agentstr/marketplace.py,sha256=CavX0WQaCiz1sQhVs-PaHZ4YYUdcabW5V5eXrhtbT5A,40406
+agentstr/nostr.py,sha256=PId6477VuShPq7nKgansgyJhJNNy9S8ycCf_3niizg4,11242
+agentstr-0.1.8.dist-info/LICENSE,sha256=20H0yoEDN5XO1xPXyZCyJjvSTP0YiarRMKWPfiaBhQY,1063
+agentstr-0.1.8.dist-info/METADATA,sha256=iHwN1hOoezYlYtYLAETT1evku9GAOzWthol7K7roYfs,3376
+agentstr-0.1.8.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+agentstr-0.1.8.dist-info/top_level.txt,sha256=KZObFRHppZvKUGYB_m9w5HhLwps7jj7w6Xrw73dH2ss,9
+agentstr-0.1.8.dist-info/RECORD,,

agentstr-0.1.7.dist-info/METADATA

@@ -1,111 +0,0 @@
-Metadata-Version: 2.2
-Name: agentstr
-Version: 0.1.7
-Summary: A library for collaborative AI agents
-Author-email: Alejandro Gil <info@synvya.com>
-License: MIT
-Project-URL: Homepage, https://github.com/synvya/agentstr
-Project-URL: Documentation, https://github.com/synvya/agentstr#readme
-Project-URL: BugTracker, https://github.com/synvya/agentstr/issues
-Keywords: AI,agents,collaboration,library
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: <3.13,>=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: phidata>=2.7.0
-Requires-Dist: openai>=1.50.0
-Requires-Dist: packaging>=24.0
-Requires-Dist: nostr-sdk>=0.38.0
-
-AgentStr
-========
-AgentStr is an extension of [Phidata](https://www.phidata.com) AI agents that allows for agents to communicate with other agents in separate computers using the Nostr communication protocol.
-
-The goal is for Agent A operated by Company A to be able to work with Agent B operated by Company B to achieve a common goal. For example: Company A wants to buy a product sold by Company B so Agent A and Agent B can coordinate and execute the transaction. 
-
-The basic communication tools are implemented in `agentstr/nostr.py`. 
-
-As a first example, AgentStr provides the tools to create and operate a marketplace using the [NIP-15](https://github.com/nostr-protocol/nips/blob/master/15.md) Nostr Marketplace as its foundation. The file `agentstr/marketplace.py` includes NIP-15 `merchant` and `customer` profiles implemented each as a Phidata Toolkit. 
-
-# License
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
-
-# Current status
-The library is in its infancy.
-
-Done:
-- Workflow to package and distribute the library
-- Users can create a Merchant profile and create an agent with the `merchant` toolkit that acts on behalf of the Merchant profile
-
-
-To be done:
-- Create a `marketplace` with `stalls`
-- Merchants to define `products`
-- Create a `customer` Toolkit
-
-# Installation
-AgentStr is offered as a python library available at https://pypi.org/project/agentstr/. 
-
-Here is an example on how to use the library:
-
-1. Create a new python environment for your app
-    ```
-    cd ~/
-    python3 -m venv ~/.venvs/aienv
-    source ~/.venvs/aienv/bin/activate
-    ```
-2. Install the agentstr library
-    ```
-    pip install --upgrade pip
-    pip install agentstr
-    mkdir ~/mysampleapp
-    cd ~/mysampleapp
-    ```
-3. Create a new python file
-    ```
-    touch main.py
-    ```
-4. Copy paste this code to the main.py file
-    ```
-    from dotenv import load_dotenv
-    from os import getenv
-    from phi.agent import Agent 
-    from phi.model.openai import OpenAIChat
-    from agentstr.marketplace import MerchantProfile, Merchant
-
-
-    profile = MerchantProfile(
-        "Synvya",
-        "Testing stuff",
-        "https://i.nostr.build/ocjZ5GlAKwrvgRhx.png",
-        getenv("NSEC_KEY")
-    )
-
-    agent = Agent(
-        name="Merchant Assistant",
-        model=OpenAIChat(id="gpt-4o"),
-        tools=[Merchant(merchant_profile=profile, relay="wss://relay.damus.io")],
-        show_tool_calls=True,
-        markdown=True,
-        debug_mode=True
-    )
-    
-    agent.print_response("Publish the merchant information and tell me full URL where I can find it")
-    ```
-5. Export your OpenAI key and optionally a Nostr private key before running the code
-    ```
-    export OPENAI_API_KEY="sk-***"
-    export NSEC_KEY="nsec***"
-    python main.py
-    ```
-
-This example will attempt to load a Nostr private key defined as NSEC_KEY in bech32 format. If a private key is not provided, the `MerchantProfile` class initializer will assign it a new one. 
-
-# Contributing
-Refer to [CONTRIBUTING.md](CONTRIBUTING.md) for specific instructions on installation instructions for developers and how to contribute.
-
-# Acknowledgments
-- [Phidata](https://www.phidata.com) - For building robust AI agents.
-- [Rust-Nostr](https://rust-nostr.org/index.html) - For providing a python based Nostr SDK.

agentstr-0.1.7.dist-info/RECORD

@@ -1,8 +0,0 @@
-agentstr/__init__.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
-agentstr/marketplace.py,sha256=XYF2ZrF6MpmxgCEOz3uN436cj7F4VHyUATFk8gmr7Zg,5245
-agentstr/nostr.py,sha256=C5zMWKBbXLkarZxBoTydJCZVzqGoCogBd_9v8Gll0VU,5012
-agentstr-0.1.7.dist-info/LICENSE,sha256=xF8akIKB07gOtkhjENT0xVbWGdFp4-srDKpZKjD03Js,1063
-agentstr-0.1.7.dist-info/METADATA,sha256=gz4B0qomWjGErWCDqZi2B5j4rEpa0mT7kY03WLThGXg,4092
-agentstr-0.1.7.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-agentstr-0.1.7.dist-info/top_level.txt,sha256=KZObFRHppZvKUGYB_m9w5HhLwps7jj7w6Xrw73dH2ss,9
-agentstr-0.1.7.dist-info/RECORD,,