Data Models

Overview

This module contains the data models used within the Agentstr SDK for handling various data structures and interactions.

High-Level Overview

• NoteFilters: Defines filters for notes, allowing customization of content retrieval based on specific criteria.

• Skill: Represents a specific capability or skill that an agent can possess or utilize.

• AgentCard: Provides a summary or profile card for an agent, including key identifying information.

• User: Models user data, capturing essential information about individuals interacting with the system.

• Message: Encapsulates communication data between agents and users, including content and metadata.

• ChatInput: Structures input data for chat interactions, formatting user or system prompts.

• ChatOutput: Represents the output or response from a chat interaction, including generated content and tool calls.

Reference

pydantic model agentstr.models.NoteFilters

Bases: BaseModel

Filters for filtering Nostr notes/events.

Show JSON schema

{
   "title": "NoteFilters",
   "description": "Filters for filtering Nostr notes/events.",
   "type": "object",
   "properties": {
      "nostr_pubkeys": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Nostr Pubkeys"
      },
      "nostr_tags": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Nostr Tags"
      },
      "following_only": {
         "default": false,
         "title": "Following Only",
         "type": "boolean"
      }
   }
}

Fields:

• following_only (bool)

• nostr_pubkeys (list[str] | None)

• nostr_tags (list[str] | None)

field nostr_pubkeys: list[str] | None = None

Filter by specific public keys

field nostr_tags: list[str] | None = None

Filter by specific tags

field following_only: bool = False

Only show notes from followed users (not implemented)

pydantic model agentstr.models.Skill

Bases: BaseModel

Represents a specific capability or service that an agent can perform.

A Skill defines a discrete unit of functionality that an agent can provide to other agents or users. Skills are the building blocks of an agent’s service offerings and can be priced individually to create a market for agent capabilities.

Show JSON schema

{
   "title": "Skill",
   "description": "Represents a specific capability or service that an agent can perform.\n\nA Skill defines a discrete unit of functionality that an agent can provide to other\nagents or users. Skills are the building blocks of an agent's service offerings and\ncan be priced individually to create a market for agent capabilities.",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "description": {
         "title": "Description",
         "type": "string"
      },
      "satoshis": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Satoshis"
      }
   },
   "required": [
      "name",
      "description"
   ]
}

Fields:

• description (str)

• name (str)

• satoshis (int | None)

field name: str [Required]

field description: str [Required]

field satoshis: int | None = None

pydantic model agentstr.models.AgentCard

Bases: BaseModel

Represents an agent’s profile and capabilities in the Nostr network.

An AgentCard is the public identity and capabilities card for an agent in the Nostr network. It contains essential information about the agent’s services, pricing, and communication endpoints.

Show JSON schema

{
   "title": "AgentCard",
   "description": "Represents an agent's profile and capabilities in the Nostr network.\n\nAn AgentCard is the public identity and capabilities card for an agent in the Nostr\nnetwork. It contains essential information about the agent's services, pricing,\nand communication endpoints.",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "description": {
         "title": "Description",
         "type": "string"
      },
      "skills": {
         "default": [],
         "items": {
            "$ref": "#/$defs/Skill"
         },
         "title": "Skills",
         "type": "array"
      },
      "satoshis": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Satoshis"
      },
      "nostr_pubkey": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Nostr Pubkey"
      },
      "nostr_relays": {
         "default": [],
         "items": {
            "type": "string"
         },
         "title": "Nostr Relays",
         "type": "array"
      }
   },
   "$defs": {
      "Skill": {
         "description": "Represents a specific capability or service that an agent can perform.\n\nA Skill defines a discrete unit of functionality that an agent can provide to other\nagents or users. Skills are the building blocks of an agent's service offerings and\ncan be priced individually to create a market for agent capabilities.",
         "properties": {
            "name": {
               "title": "Name",
               "type": "string"
            },
            "description": {
               "title": "Description",
               "type": "string"
            },
            "satoshis": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Satoshis"
            }
         },
         "required": [
            "name",
            "description"
         ],
         "title": "Skill",
         "type": "object"
      }
   },
   "required": [
      "name",
      "description"
   ]
}

Fields:

• description (str)

• name (str)

• nostr_pubkey (str | None)

• nostr_relays (list[str])

• satoshis (int | None)

• skills (list[agentstr.models.Skill])

field name: str [Required]

field description: str [Required]

field skills: list[Skill] = []

field satoshis: int | None = None

field nostr_pubkey: str | None = None

field nostr_relays: list[str] = []

pydantic model agentstr.models.User

Bases: BaseModel

Simple user model persisted by the database layer.

Show JSON schema

{
   "title": "User",
   "description": "Simple user model persisted by the database layer.",
   "type": "object",
   "properties": {
      "user_id": {
         "title": "User Id",
         "type": "string"
      },
      "available_balance": {
         "default": 0,
         "title": "Available Balance",
         "type": "integer"
      },
      "current_thread_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Current Thread Id"
      }
   },
   "required": [
      "user_id"
   ]
}

Fields:

• available_balance (int)

• current_thread_id (str | None)

• user_id (str)

field user_id: str [Required]

field available_balance: int = 0

field current_thread_id: str | None = None

pydantic model agentstr.models.Message

Bases: BaseModel

Represents a message in a chat interaction. This should only be retrieved from the Database, not created manually.

Show JSON schema

{
   "title": "Message",
   "description": "Represents a message in a chat interaction. This should only be retrieved from the Database, not created manually.",
   "type": "object",
   "properties": {
      "agent_name": {
         "title": "Agent Name",
         "type": "string"
      },
      "thread_id": {
         "title": "Thread Id",
         "type": "string"
      },
      "user_id": {
         "title": "User Id",
         "type": "string"
      },
      "idx": {
         "title": "Idx",
         "type": "integer"
      },
      "message": {
         "title": "Message",
         "type": "string"
      },
      "content": {
         "title": "Content",
         "type": "string"
      },
      "role": {
         "enum": [
            "user",
            "agent",
            "tool"
         ],
         "title": "Role",
         "type": "string"
      },
      "kind": {
         "enum": [
            "request",
            "requires_payment",
            "tool_message",
            "requires_input",
            "final_response",
            "error"
         ],
         "title": "Kind",
         "type": "string"
      },
      "satoshis": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Satoshis"
      },
      "extra_inputs": {
         "additionalProperties": true,
         "default": {},
         "title": "Extra Inputs",
         "type": "object"
      },
      "extra_outputs": {
         "additionalProperties": true,
         "default": {},
         "title": "Extra Outputs",
         "type": "object"
      },
      "created_at": {
         "format": "date-time",
         "title": "Created At",
         "type": "string"
      }
   },
   "required": [
      "agent_name",
      "thread_id",
      "user_id",
      "idx",
      "message",
      "content",
      "role",
      "kind"
   ]
}

Fields:

• agent_name (str)

• content (str)

• created_at (datetime.datetime)

• extra_inputs (dict[str, Any])

• extra_outputs (dict[str, Any])

• idx (int)

• kind (Literal['request', 'requires_payment', 'tool_message', 'requires_input', 'final_response', 'error'])

• message (str)

• role (Literal['user', 'agent', 'tool'])

• satoshis (int | None)

• thread_id (str)

• user_id (str)

field agent_name: str [Required]

field thread_id: str [Required]

field user_id: str [Required]

field idx: int [Required]

field message: str [Required]

field content: str [Required]

field role: Literal['user', 'agent', 'tool'] [Required]

field kind: Literal['request', 'requires_payment', 'tool_message', 'requires_input', 'final_response', 'error'] [Required]

field satoshis: int | None = None

field extra_inputs: dict[str, Any] = {}

field extra_outputs: dict[str, Any] = {}

field created_at: datetime [Optional]

classmethod from_row(row: Any) → Message

pydantic model agentstr.models.ChatInput

Bases: BaseModel

Represents input data for an agent chat interaction.

Show JSON schema

{
   "title": "ChatInput",
   "description": "Represents input data for an agent chat interaction.",
   "type": "object",
   "properties": {
      "message": {
         "title": "Message",
         "type": "string"
      },
      "thread_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Thread Id"
      },
      "user_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "User Id"
      },
      "extra_inputs": {
         "additionalProperties": true,
         "default": {},
         "title": "Extra Inputs",
         "type": "object"
      },
      "history": {
         "default": [],
         "items": {
            "$ref": "#/$defs/Message"
         },
         "title": "History",
         "type": "array"
      }
   },
   "$defs": {
      "Message": {
         "description": "Represents a message in a chat interaction. This should only be retrieved from the Database, not created manually.",
         "properties": {
            "agent_name": {
               "title": "Agent Name",
               "type": "string"
            },
            "thread_id": {
               "title": "Thread Id",
               "type": "string"
            },
            "user_id": {
               "title": "User Id",
               "type": "string"
            },
            "idx": {
               "title": "Idx",
               "type": "integer"
            },
            "message": {
               "title": "Message",
               "type": "string"
            },
            "content": {
               "title": "Content",
               "type": "string"
            },
            "role": {
               "enum": [
                  "user",
                  "agent",
                  "tool"
               ],
               "title": "Role",
               "type": "string"
            },
            "kind": {
               "enum": [
                  "request",
                  "requires_payment",
                  "tool_message",
                  "requires_input",
                  "final_response",
                  "error"
               ],
               "title": "Kind",
               "type": "string"
            },
            "satoshis": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Satoshis"
            },
            "extra_inputs": {
               "additionalProperties": true,
               "default": {},
               "title": "Extra Inputs",
               "type": "object"
            },
            "extra_outputs": {
               "additionalProperties": true,
               "default": {},
               "title": "Extra Outputs",
               "type": "object"
            },
            "created_at": {
               "format": "date-time",
               "title": "Created At",
               "type": "string"
            }
         },
         "required": [
            "agent_name",
            "thread_id",
            "user_id",
            "idx",
            "message",
            "content",
            "role",
            "kind"
         ],
         "title": "Message",
         "type": "object"
      }
   },
   "required": [
      "message"
   ]
}

Fields:

• extra_inputs (dict[str, Any])

• history (list[agentstr.models.Message])

• message (str)

• thread_id (str | None)

• user_id (str | None)

field message: str [Required]

field thread_id: str | None = None

field user_id: str | None = None

field extra_inputs: dict[str, Any] = {}

field history: list[Message] = []

pydantic model agentstr.models.ChatOutput

Bases: BaseModel

Represents output data for an agent chat interaction.

Show JSON schema

{
   "title": "ChatOutput",
   "description": "Represents output data for an agent chat interaction.",
   "type": "object",
   "properties": {
      "message": {
         "title": "Message",
         "type": "string"
      },
      "content": {
         "title": "Content",
         "type": "string"
      },
      "thread_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Thread Id"
      },
      "user_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "User Id"
      },
      "role": {
         "default": "agent",
         "enum": [
            "agent",
            "tool"
         ],
         "title": "Role",
         "type": "string"
      },
      "kind": {
         "default": "final_response",
         "enum": [
            "requires_payment",
            "tool_message",
            "requires_input",
            "final_response",
            "error"
         ],
         "title": "Kind",
         "type": "string"
      },
      "satoshis": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Satoshis"
      },
      "extra_outputs": {
         "additionalProperties": true,
         "default": {},
         "title": "Extra Outputs",
         "type": "object"
      }
   },
   "required": [
      "message",
      "content"
   ]
}

Fields:

• content (str)

• extra_outputs (dict[str, Any])

• kind (Literal['requires_payment', 'tool_message', 'requires_input', 'final_response', 'error'])

• message (str)

• role (Literal['agent', 'tool'])

• satoshis (int | None)

• thread_id (str | None)

• user_id (str | None)

field message: str [Required]

field content: str [Required]

field thread_id: str | None = None

field user_id: str | None = None

field role: Literal['agent', 'tool'] = 'agent'

field kind: Literal['requires_payment', 'tool_message', 'requires_input', 'final_response', 'error'] = 'final_response'

field satoshis: int | None = None

field extra_outputs: dict[str, Any] = {}

See Also

• Nostr Agent — The nostr agent uses these models for configuration.

• Database Interface — The database layer uses these models for persisting user data and chat history.