Psychic

psychicapi is the python client library for Psychic.

What is Psychic?

Psychic is a platform for integrating with your customer’s SaaS tools like Notion, Zendesk, Confluence, and Google Drive via OAuth and syncing documents from these applications to your SQL or vector database. You can think of it like Plaid for unstructured data. Psychic is easy to set up - you use it by importing the react library and configuring it with your Psychic API key, which you can get from the Psychic dashboard. When your users connect their applications, you can view these connections from the dashboard and retrieve data using the server-side libraries.

Quick start

1. Create an account in the dashboard.
2. Use the react library to add the Psychic link modal to your frontend react app. Users will use this to connect their SaaS apps. Or, use the playground to connect your own data sources.
3. Use psychicapi to retrieve documents from your active connections.

Usage

Initialization

from psychicapi import ConnectorId, Psychic 
psychic = Psychic(secret_key="secret-key")

Get active connections

# Get all active connections and optionally filter by connector id and/or account id
connections = psychic.get_connections(account_id="account_id")

Retrieve documents from a connection

page_cursor = None
all_docs = []
while True:
    docs_response = psychic.get_documents(account_id="account_id", connector_id=ConnectorId.notion, page_cursor=page_cursor, page_size=100)
    if docs_response is None:
        break
    all_docs.extend(docs_response.documents)
    page_cursor = docs_response.next_page_cursor
    if page_cursor is None:
        break
print(all_docs)

Retrieve messages from a connection

To retrieve messages from connectors like slack and gmail, use the get_conversations function.

page_cursor = None
all_messages = []
while True:
    messages_response = psychic.get_conversations(account_id="account_id", connector_id=ConnectorId.gmail, page_cursor=page_cursor)
    if messages_response is None:
        break
    all_messages.extend(messages_response.messages)
    page_cursor = messages_response.next_page_cursor
    if page_cursor is None:
        break
print(all_messages)

Retrieve tickets from a connection

To retrieve messages from connectors like zendesk, use the get_tickets function.

page_cursor = None
all_tickets = []
while True:
    tickets_response = psychic.get_tickets(account_id="account_id", connector_id=ConnectorId.zendesk, redact_pii=True, page_cursor=page_cursor)
    if tickets_response is None:
        break
    all_tickets.extend(tickets_response.tickets)
    page_cursor = tickets_response.next_page_cursor
    if page_cursor is None:
        break
print(all_tickets)

Advanced Filtering

Filtering by section(s)

Most file storage, CRM and helpdesk apps have documents organized in sections. Confluence calls them spaces, Zendesk calls them sections, Google Drive calls them folders. Psychic allows you to define filters based on these sections using the SectionFilter class. You can define and query sections as follows:

from psychicapi import Psychic, ConnectorId, Section, SectionFilter

client = Psychic("YOUR-SECRET-KEY")
connections = client.get_connections(connector_id=ConnectorId.notion, account_id="test")
connection = connections[0]

# get existing section filters
existing_filters = connection.section_filters

# get all available sections from the connection. these will be folders, sections, spaces, etc. depending on the connector
sections = connection.sections

# have the user pick one or more sections
i = 0
filter = SectionFilter(id='index1', sections=[sections[i]])

# add the section filter to the connection
client.add_section_filter(connector_id=ConnectorId.notion, account_id="test", section_filter=filter)

# get documents from the sections in the filter
client.get_documents(account_id="test", connector_id=ConnectorId.notion, section_filter_id="index1")

Filtering by uri

Every document returned by Psychic has a uri. If you want to query a document by uri instead of retrieving all documents in a connection, you can use the optional uris parameter in get_documents

client.get_documents(
    account_id="test", 
    connector_id=ConnectorId.notion, 
    uris=["https://docs.google.com/document/d/document-id-1/edit?usp=drivesdk", "https://drive.google.com/file/d/document-id-2/view?usp=drivesdk"]
)

Local development

To run the python package locally, use the following command:

pip install -e /path/to/package