OpenSearchMemory / Client / create_event

create_event

OpenSearchMemory.Client.create_event(**kwargs)

Submits an event (conversation turns, structured data, or a PDF document stored in Amazon S3) to a session in a space.

The operation returns as soon as the event is saved. GetEvent and ListEvents return it immediately. SearchEvents returns it after it’s indexed. SearchMemories returns memories extracted from it only after a strategy’s extraction trigger fires and the memories are indexed.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren’t allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

response = client.create_event(
    spaceId='string',
    actorId='string',
    sessionId='string',
    eventTimestamp=datetime(2015, 1, 1),
    payload={
        'conversational': {
            'unified': {
                'source': {
                    'object': {
                        'messages': [
                            {
                                'role': 'USER'|'ASSISTANT'|'SYSTEM',
                                'content': {
                                    'text': 'string'
                                }
                            },
                        ]
                    }
                }
            }
        },
        'structuredData': {
            'source': {
                'json': {...}|[...]|123|123.4|'string'|True|None
            }
        },
        'blob': {
            'contentType': 'application/pdf'|'image/png'|'image/jpeg',
            'source': {
                's3Location': {
                    'uri': 'string'
                }
            }
        }
    },
    metadata={
        'string': 'string'
    },
    clientToken='string',
    infer=True|False
)
Parameters:
  • spaceId (string) –

    [REQUIRED]

    The ID of the space that owns the event, for example sp-02864597b164.

  • actorId (string) –

    [REQUIRED]

    The ID of the actor (end user or agent) that the event belongs to.

  • sessionId (string) – The session the event belongs to. Send every event of one conversation with the same session ID, so that SUMMARY strategies summarize the conversation as one session. If you omit it, the service generates a session ID and returns it.

  • eventTimestamp (datetime) – When the event occurred. The default is the time that the service receives the request.

  • payload (dict) –

    [REQUIRED]

    The event content. Set exactly one union member.

    Note

    This is a Tagged Union structure. Only one of the following top level keys can be set: conversational, structuredData, blob.

    • conversational (dict) –

      Conversation turns.

      Note

      This is a Tagged Union structure. Only one of the following top level keys can be set: unified.

      • unified (dict) –

        Conversation turns in the service’s own format.

        • source (dict) – [REQUIRED]

          The conversation.

          Note

          This is a Tagged Union structure. Only one of the following top level keys can be set: object.

          • object (dict) –

            The conversation turns.

            • messages (list) – [REQUIRED]

              The conversation turns, in order. The order matters for extraction.

              • (dict) –

                A conversation turn.

                • role (string) – [REQUIRED]

                  The author of the turn.

                • content (dict) – [REQUIRED]

                  The content of the turn.

                  • text (string) – [REQUIRED]

                    The text of the turn.

    • structuredData (dict) –

      Structured (non-conversational) content, for example a deployment result that an agent should remember.

      • source (dict) – [REQUIRED]

        The structured content.

        Note

        This is a Tagged Union structure. Only one of the following top level keys can be set: json.

        • json (document) –

          The structured content, as a JSON object of at most 1 MiB when serialized as UTF-8, nested at most 10 levels deep.

    • blob (dict) –

      A document stored in Amazon S3, such as a PDF.

      • contentType (string) – [REQUIRED]

        The document’s media type. Only application/pdf is supported. Any other value fails with ValidationException.

      • source (dict) – [REQUIRED]

        The location of the document.

        Note

        This is a Tagged Union structure. Only one of the following top level keys can be set: s3Location.

        • s3Location (dict) –

          The S3 object holding the document.

          • uri (string) – [REQUIRED]

            The object’s S3 URI, for example s3://bucket/key. The bucket must be in the space’s Region. You need s3:GetObject on the object, and kms:Decrypt on its key if the object uses SSE-KMS. The event doesn’t store the object itself.

  • metadata (dict) –

    Metadata tags to store with the event. Memories derived from the event carry the same tags. Keys that begin with x-amz-, the keys documentS3Source and documentS3Url, and other keys that the service uses internally are reserved: a request that sets one fails with ValidationException, and the message names the key.

    A space can use at most 50 distinct metadata keys across all of its events and memories. A request that would add a key beyond that fails with ValidationException. Reuse an existing key instead.

    • (string) –

      A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

      • (string) –

        The value of a metadata entry.

  • clientToken (string) –

    A unique, case-sensitive identifier that makes the request idempotent. Within 2 hours of the first request, a retry with the same token and the same request, including the same sessionId, returns the same event. If you omit sessionId, the service generates a new one on each attempt, so a retry fails with ConflictException. Reusing the token with different request content also fails with ConflictException. eventTimestamp isn’t compared. After 2 hours, the token starts a new event.

    This field is autopopulated if not provided.

  • infer (boolean) – Specifies whether to extract memories from this event. The default is true. Set it to false to store the event without extraction: the service skips strategies that infer memories, and still indexes the event’s turns for SearchEvents. A document submitted as a blob is still extracted.

Return type:

dict

Returns:

Response Syntax

{
    'event': {
        'eventId': 'string',
        'spaceId': 'string',
        'actorId': 'string',
        'sessionId': 'string',
        'eventTimestamp': datetime(2015, 1, 1)
    }
}

Response Structure

  • (dict) –

    • event (dict) –

      The stored event’s identifiers: its ID, session, and timestamp.

      • eventId (string) –

        The event’s ID, assigned by the service. Use it with GetEvent and DeleteEvent.

      • spaceId (string) –

        The ID of the space.

      • actorId (string) –

        The ID of the actor the event belongs to.

      • sessionId (string) –

        The ID of the session the event belongs to, including one the service generated.

      • eventTimestamp (datetime) –

        When the event occurred: the value supplied, or the time the request was received.

Exceptions