scout-types 1.0.0

package/src/types/JurisdictionDocument.ts

@@ -0,0 +1,48 @@
+export class JurisdictionDocument {
+    readonly jurisdiction_id : number
+    readonly document_id : string
+    readonly media_id : string
+    readonly origin : string
+    readonly s3_filename? : string
+    readonly time? : string
+    readonly title : string
+    readonly type : string
+    readonly url : string
+    readonly vector_keys? : string[]
+    readonly location? : string
+
+    constructor(jurisdiction_document : any) {
+        if (!JurisdictionDocument.is(jurisdiction_document)) {
+            throw Error("Invalid input.")
+        }
+        this.jurisdiction_id = jurisdiction_document.jurisdiction_id
+        this.document_id = jurisdiction_document.document_id
+        this.media_id = jurisdiction_document.media_id
+        this.origin = jurisdiction_document.origin
+        this.s3_filename = jurisdiction_document.s3_filename
+        this.time = jurisdiction_document.time
+        this.title = jurisdiction_document.title
+        this.type = jurisdiction_document.type
+        this.url = jurisdiction_document.url
+        this.vector_keys = jurisdiction_document.vector_keys
+        this.location = jurisdiction_document.location
+    }
+
+    static is(jurisdiction_document : any) : jurisdiction_document is JurisdictionDocument {
+        return (
+            jurisdiction_document !== undefined &&
+            typeof jurisdiction_document.jurisdiction_id === "number" &&
+            typeof jurisdiction_document.document_id === "string" &&
+            typeof jurisdiction_document.media_id === "string" &&
+            typeof jurisdiction_document.origin === "string" &&
+            (jurisdiction_document.s3_filename === undefined || typeof jurisdiction_document.s3_filename === "string") &&
+            (jurisdiction_document.time === undefined || typeof jurisdiction_document.time === "string") &&
+            typeof jurisdiction_document.title === "string" &&
+            typeof jurisdiction_document.type === "string" &&
+            typeof jurisdiction_document.url === "string" &&
+            (jurisdiction_document.vector_keys === undefined || Array.isArray(jurisdiction_document.vector_keys) &&
+            jurisdiction_document.vector_keys.every((vector_key : any) => typeof vector_key === "string")) &&
+            (jurisdiction_document.location === undefined || typeof jurisdiction_document.location === "string")
+        )
+    }
+}

package/src/types/Message.ts

@@ -0,0 +1,73 @@
+import { Sources } from "./Sources"
+
+export class Fragment {
+    readonly text : string
+    readonly sources : Sources
+
+    constructor(fragment : any) {
+        if (!Fragment.is(fragment)) {
+            throw Error("Invalid input.")
+        }
+        this.text = fragment.text
+        this.sources = fragment.sources
+    }
+
+    static is(fragment : any) : fragment is Fragment {
+        return (
+            fragment !== undefined &&
+            typeof fragment.text === "string" &&
+            Sources.is(fragment.sources)
+        )
+    }
+}
+
+export class Message {
+    readonly user_id : string
+    readonly message_id : string
+    readonly scout_id : string
+    readonly conversation_id : string
+    readonly time : string
+    readonly mode : "chat" | "write"
+    readonly role : "user" | "scout"
+    readonly system_prompt? : string
+    readonly grok_text? : string
+    readonly fragments? : Fragment[]
+    readonly sources? : Sources
+    readonly text : string
+
+    constructor(message : any) {
+        if (!Message.is(message)) {
+            throw Error("Invalid input.")
+        }
+        this.user_id = message.user_id
+        this.message_id = message.message_id
+        this.scout_id = message.scout_id
+        this.conversation_id = message.conversation_id
+        this.time = message.time
+        this.mode = message.mode
+        this.role = message.role
+        this.system_prompt = message.system_prompt
+        this.grok_text = message.grok_text
+        this.fragments = message.fragments
+        this.sources = message.sources
+        this.text = message.text
+    }
+
+    static is(message : any) : message is Message {
+        return (
+            message !== undefined &&
+            typeof message.user_id === "string" &&
+            typeof message.message_id === "string" &&
+            typeof message.scout_id === "string" &&
+            typeof message.conversation_id === "string" &&
+            typeof message.time === "string" &&
+            ["chat", "write"].includes(message.mode) &&
+            ["user", "scout"].includes(message.role) &&
+            (message.system_prompt === undefined || typeof message.system_prompt === "string") &&
+            (message.grok_text === undefined || typeof message.grok_text === "string") &&
+            (message.fragments === undefined || Array.isArray(message.fragments) && message.fragments.every(Fragment.is)) &&
+            (message.sources === undefined || Sources.is(message.sources)) &&
+            typeof message.text === "string"
+        )
+    }
+}

package/src/types/OfficeClass.ts

@@ -0,0 +1,150 @@
+import { JurisdictionLevel } from "./Jurisdiction"
+
+const office_class_ids = ["ORG", "USH", "USS", "STG", "STH", "STS", "STB", "COG", "CIG", "LOB"] as const
+
+export type OfficeClassID = typeof office_class_ids[number]
+
+export function is_office_class_id(office_class_id : any) : office_class_id is OfficeClassID {
+    return office_class_ids.includes(office_class_id)
+}
+
+export interface OfficeClass {
+    office_class_id : OfficeClassID,
+    name : string,
+    type : "candidate" | "organization",
+    office_id_template : string,
+    jurisdiction_level? : JurisdictionLevel,
+    jurisdictions_mutable : Boolean,
+    require_district : Boolean,
+    require_initial_jurisdiction : Boolean,
+    office_names? : string[]
+
+}
+
+export const office_classes_by_office_class_id : Record<OfficeClassID, OfficeClass> = {
+    "ORG" : {
+        office_class_id : "ORG",
+        name : "Organization",
+        type : "organization",
+        office_id_template : "O-[state_id]",
+        jurisdictions_mutable : true,
+        require_district : false,
+        require_initial_jurisdiction : false
+    },
+    "USH" : {
+        office_class_id : "USH",
+        name : "U.S. House",
+        type : "candidate",
+        office_id_template : "H-[state_id]",
+        jurisdictions_mutable : true,
+        require_district : true,
+        require_initial_jurisdiction : false
+    },
+    "USS" : {
+        office_class_id : "USS",
+        name : "U.S. Senate",
+        type : "candidate",
+        office_id_template : "S-[state_id]",
+        jurisdiction_level : JurisdictionLevel.STATE,
+        jurisdictions_mutable : false,
+        require_district : false,
+        require_initial_jurisdiction : false
+    },
+    "STG" : {
+        office_class_id : "STG",
+        name : "State (Executive) Government",
+        type : "candidate",
+        office_id_template : "[state_id]-G",
+        jurisdiction_level : JurisdictionLevel.STATE,
+        jurisdictions_mutable : false,
+        require_district : false,
+        require_initial_jurisdiction : false,
+        office_names : [
+            "Governor",
+            "Lieutenant Governor",
+            "Secretary of State",
+            "Treasurer",
+            "Auditor",
+            "Attorney General"
+        ]
+    },
+    "STH" : {
+        office_class_id : "STH",
+        name : "State House",
+        type : "candidate",
+        office_id_template : "[state_id]-H",
+        jurisdictions_mutable : true,
+        require_district : true,
+        require_initial_jurisdiction : false
+    },
+    "STS" : {
+        office_class_id : "STS",
+        name : "State Senate",
+        type : "candidate",
+        office_id_template : "[state_id]-S",
+        jurisdictions_mutable : true,
+        require_district : true,
+        require_initial_jurisdiction : false
+    },
+    "STB" : {
+        office_class_id : "STB",
+        name : "State School Board",
+        type : "candidate",
+        office_id_template : "[state_id]-B",
+        jurisdiction_level : JurisdictionLevel.SCHOOL,
+        jurisdictions_mutable : true,
+        require_district : true,
+        require_initial_jurisdiction : true,
+        office_names : [
+            "Board Member"
+        ]
+    },
+    "COG" : {
+        office_class_id : "COG",
+        name : "County Government",
+        type : "candidate",
+        office_id_template : "[state_id]-C",
+        jurisdiction_level : JurisdictionLevel.COUNTY,
+        jurisdictions_mutable : true,
+        require_district : false,
+        require_initial_jurisdiction : true,
+        office_names : [
+            "Mayor",
+            "Councillor",
+            "Commissioner",
+            "Clerk",
+            "Recorder",
+            "Auditor",
+            "Surveyor",
+            "District Attorney",
+            "Sheriff"
+        ]
+    },
+    "CIG" : {
+        office_class_id : "CIG",
+        name : "City Government",
+        type : "candidate",
+        office_id_template : "[state_id]-M",
+        jurisdiction_level : JurisdictionLevel.CITY,
+        jurisdictions_mutable : true,
+        require_district : false,
+        require_initial_jurisdiction : true,
+        office_names : [
+            "Mayor",
+            "Councillor"
+        ]
+    },
+    "LOB" : {
+        office_class_id : "LOB",
+        name : "Local School Board",
+        type : "candidate",
+        office_id_template : "[state_id]-E",
+        jurisdiction_level : JurisdictionLevel.SCHOOL,
+        jurisdictions_mutable : true,
+        require_district : false,
+        require_initial_jurisdiction : true,
+        office_names : [
+            "Board Member"
+        ]
+    }
+}

package/src/types/Party.ts

@@ -0,0 +1,36 @@
+const party_ids = ["DEM", "REP", "NON", "ETC"] as const
+
+export type PartyID = typeof party_ids[number]
+
+export function is_party_id(party_id : any) : party_id is PartyID {
+    return party_ids.includes(party_id)
+}
+
+export interface Party {
+    party_id : PartyID,
+    name : string,
+    adjective : string
+}
+
+export const parties_by_party_id : Record<PartyID, Party> = {
+    DEM : {
+        party_id : "DEM",
+        name : "Democratic Party",
+        adjective : "Democratic"
+    },
+    REP : {
+        party_id : "REP",
+        name : "Republican Party",
+        adjective : "Republican"
+    },
+    ETC : {
+        party_id : "ETC",
+        name : "Other Party",
+        adjective : "Third-Party"
+    },
+    NON : {
+        party_id : "NON",
+        name : "Nonpartisan",
+        adjective : "Nonpartisan"
+    }
+}

package/src/types/Scout.ts

@@ -0,0 +1,83 @@
+import { is_office_class_id, OfficeClassID } from "./OfficeClass"
+import { Jurisdiction } from "./Jurisdiction"
+import { is_state_id, StateID } from "./State"
+import { is_party_id, PartyID } from "./Party"
+
+export class Scout {
+    readonly office_id : string
+    readonly number : string
+    readonly scout_id : string
+    readonly name : string
+    readonly active : boolean
+    readonly state_id : StateID
+    readonly district? : number
+    readonly party_id : PartyID
+    readonly tone_description_refresh : boolean
+    readonly jurisdiction_ids : number[]
+    readonly office_class_id : OfficeClassID
+    readonly office_name? : string
+    readonly [x : string] : any
+
+    constructor(scout : any) {
+        if (!Scout.is(scout)) {
+            throw Error("Invalid input.")
+        }
+        this.office_id = scout.office_id
+        this.number = scout.number
+        this.scout_id = scout.scout_id
+        this.name = scout.name
+        this.active = scout.active
+        this.state_id = scout.state_id
+        this.district = scout.district
+        this.party_id = scout.party_id
+        this.tone_description_refresh = scout.tone_description_refresh
+        this.jurisdiction_ids = scout.jurisdiction_ids
+        this.office_class_id = scout.office_class_id
+        this.office_name = scout.office_name
+    }
+
+    static is(scout : any) : scout is Scout {
+        return (
+            scout !== undefined &&
+            typeof scout.office_id === "string" &&
+            typeof scout.number === "string" &&
+            typeof scout.scout_id === "string" &&
+            typeof scout.name === "string" &&
+            typeof scout.active === "boolean" &&
+            is_state_id(scout.state_id) &&
+            (scout.district === undefined || typeof scout.district === "number") &&
+            is_party_id(scout.party_id) &&
+            typeof scout.tone_description_refresh === "boolean" &&
+            Array.isArray(scout.jurisdiction_ids) &&
+            scout.jurisdiction_ids.every((jurisdiction_id : any) => typeof jurisdiction_id === "number") &&
+            is_office_class_id(scout.office_class_id) &&
+            (scout.office_name === undefined || typeof scout.office_name === "string")
+        )
+    }
+}
+
+export class ScoutAux extends Scout {
+    readonly jurisdictions : Jurisdiction[]
+    readonly photo_download_url? : string
+    readonly tone_description? : string
+
+    constructor(scout : any) {
+        if (!ScoutAux.is(scout)) {
+            throw Error("Invalid input.")
+        }
+        super(scout)
+        this.jurisdictions = scout.jurisdictions
+        this.photo_download_url = scout.photo_download_url
+        this.tone_description = scout.tone_description
+    }
+
+    static is(scout : any) : scout is ScoutAux {
+        return (
+            Scout.is(scout) &&
+            Array.isArray(scout.jurisdictions) &&
+            scout.jurisdictions.every(Jurisdiction.is) &&
+            (scout.photo_download_url === undefined || typeof scout.photo_download_url === "string") &&
+            (scout.tone_description === undefined || typeof scout.tone_description === "string")
+        )
+    }
+}

package/src/types/ScoutConfig.ts

@@ -0,0 +1,28 @@
+export interface ScoutUtilsConfig {
+    region : string,
+    scraping_bee_api_key? : string,
+    xai_api_key? : string,
+    citizenportal_api_key? : string,
+    [key : string]: any
+}
+
+export interface ScoutConfig extends ScoutUtilsConfig {
+    port : number,
+    api_url : string,
+    client_url : string,
+    auth_url : string,
+    cognito_user_pool_id : string,
+    cognito_client_id : string,
+    cognito_client_secret : string,
+    secret_key : string,
+    admin_key : string,
+    dynamodb_scouts : string,
+    dynamodb_scout_documents : string,
+    dynamodb_conversations : string,
+    dynamodb_jurisdictions : string,
+    dynamodb_jurisdiction_documents : string,
+    dynamodb_messages : string,
+    dynamodb_users : string,
+    s3_bucket : string,
+    s3vectors_bucket : string
+}

package/src/types/ScoutDocument.ts

@@ -0,0 +1,43 @@
+import { Tweet } from "./Tweet"
+
+export class ScoutDocument {
+    readonly scout_id : string
+    readonly document_id : string
+    readonly type : "URL" | "TWEET" | "TWITTER"
+    readonly s3_filename? : string
+    readonly url? : string
+    readonly username? : string
+    readonly vector_keys? : string[]
+    readonly tweet? : Tweet
+    readonly text? : string
+
+    constructor(scout_document : any) {
+        if (!ScoutDocument.is(scout_document)) {
+            throw Error("Invalid input.")
+        }
+        this.scout_id = scout_document.scout_id
+        this.document_id = scout_document.document_id
+        this.type = scout_document.type
+        this.s3_filename = scout_document.s3_filename
+        this.url = scout_document.url
+        this.username = scout_document.username
+        this.vector_keys = scout_document.vector_keys
+        this.tweet = scout_document.tweet
+        this.text = scout_document.text
+    }
+
+    static is(scout_document : any) : scout_document is ScoutDocument {
+        return (
+            scout_document !== undefined &&
+            typeof scout_document.scout_id === "string" &&
+            typeof scout_document.document_id === "string" &&
+            typeof scout_document.type === "string" &&
+            (scout_document.s3_filename === undefined || typeof scout_document.s3_filename === "string") &&
+            (scout_document.url === undefined || typeof scout_document.url === "string") &&
+            (scout_document.username === undefined || typeof scout_document.username === "string") &&
+            (scout_document.vector_keys === undefined || Array.isArray(scout_document.vector_keys) && scout_document.vector_keys.every((vector_key : any) => typeof vector_key === "string")) &&
+            (scout_document.tweet === undefined || Tweet.is(scout_document.tweet)) &&
+            (scout_document.text === undefined || typeof scout_document.text === "string")
+        )
+    }
+}

package/src/types/Sources.ts

@@ -0,0 +1,163 @@
+import { ScoutDocument } from "./ScoutDocument"
+import { JurisdictionDocument } from "./JurisdictionDocument"
+import { Bill } from "./Bill"
+
+export class ScoutDocumentSource {
+    readonly chunk_text : string
+    readonly description : string
+    readonly label : string
+    readonly type : string
+    readonly vector_key : string
+    readonly document : ScoutDocument
+
+    constructor(scout_document_source : any) {
+        if (!ScoutDocumentSource.is(scout_document_source)) {
+            throw Error("Invalid input.")
+        }
+        this.chunk_text = scout_document_source.chunk_text
+        this.description = scout_document_source.description
+        this.label = scout_document_source.label
+        this.type = scout_document_source.type
+        this.vector_key = scout_document_source.vector_key
+        this.document = scout_document_source.document
+    }
+
+    static is(scout_document_source : any) : scout_document_source is ScoutDocumentSource {
+        return (
+            scout_document_source !== undefined &&
+            typeof scout_document_source.chunk_text === "string" &&
+            typeof scout_document_source.description === "string" &&
+            typeof scout_document_source.label === "string" &&
+            typeof scout_document_source.type === "string" &&
+            typeof scout_document_source.vector_key === "string" &&
+            ScoutDocument.is(scout_document_source.document)
+        )
+    }
+}
+
+export class JurisdictionDocumentSource {
+    readonly chunk_text : string
+    readonly description : string
+    readonly label : string
+    readonly type : string
+    readonly vector_key : string
+    readonly document : JurisdictionDocument
+
+    constructor(jurisdiction_document_source : any) {
+        if (!JurisdictionDocumentSource.is(jurisdiction_document_source)) {
+            throw Error("Invalid input.")
+        }
+        this.chunk_text = jurisdiction_document_source.chunk_text
+        this.description = jurisdiction_document_source.description
+        this.label = jurisdiction_document_source.label
+        this.type = jurisdiction_document_source.type
+        this.vector_key = jurisdiction_document_source.vector_key
+        this.document = jurisdiction_document_source.document
+    }
+
+    static is(jurisdiction_document_source : any) : jurisdiction_document_source is JurisdictionDocumentSource {
+        return (
+            jurisdiction_document_source !== undefined &&
+            typeof jurisdiction_document_source.chunk_text === "string" &&
+            typeof jurisdiction_document_source.description === "string" &&
+            typeof jurisdiction_document_source.label === "string" &&
+            typeof jurisdiction_document_source.type === "string" &&
+            typeof jurisdiction_document_source.vector_key === "string" &&
+            JurisdictionDocument.is(jurisdiction_document_source.document)
+        )
+    }
+}
+
+export class BillDocumentSource {
+    readonly chunk_text : string
+    readonly description : string
+    readonly label : string
+    readonly type : string
+    readonly vector_key : string
+    readonly bill : Bill
+
+    constructor(bill_document_source : any) {
+        if (!BillDocumentSource.is(bill_document_source)) {
+            throw Error("Invalid input.")
+        }
+        this.chunk_text = bill_document_source.chunk_text
+        this.description = bill_document_source.description
+        this.label = bill_document_source.label
+        this.type = bill_document_source.type
+        this.vector_key = bill_document_source.vector_key
+        this.bill = bill_document_source.bill
+    }
+
+    static is(bill_document_source : any) : bill_document_source is BillDocumentSource {
+        return (
+            bill_document_source !== undefined &&
+            typeof bill_document_source.chunk_text === "string" &&
+            typeof bill_document_source.description === "string" &&
+            typeof bill_document_source.label === "string" &&
+            typeof bill_document_source.type === "string" &&
+            typeof bill_document_source.vector_key === "string" &&
+            Bill.is(bill_document_source.bill)
+        )
+    }
+}
+
+export class GrokSource {
+    readonly title : string
+    readonly url : string
+    readonly start_index : number
+    readonly end_index : number
+    readonly type : string
+
+    constructor(grok_source : any) {
+        if (!GrokSource.is(grok_source)) {
+            throw Error("Invalid input.")
+        }
+        this.title = grok_source.title
+        this.url = grok_source.url
+        this.start_index = grok_source.start_index
+        this.end_index = grok_source.end_index
+        this.type = grok_source.type
+    }
+
+    static is(grok_source : any) : grok_source is GrokSource {
+        return (
+            grok_source !== undefined &&
+            typeof grok_source.title === "string" &&
+            typeof grok_source.url === "string" &&
+            typeof grok_source.start_index === "number" &&
+            typeof grok_source.end_index === "number" &&
+            typeof grok_source.type === "string"
+        )
+    }
+}
+
+export class Sources {
+    readonly B : BillDocumentSource[]
+    readonly S : ScoutDocumentSource[]
+    readonly J : JurisdictionDocumentSource[]
+    readonly G : GrokSource[]
+
+    constructor(sources : any) {
+        if (!Sources.is(sources)) {
+            throw Error("Invalid input.")
+        }
+        this.B = sources.B
+        this.S = sources.S
+        this.J = sources.J
+        this.G = sources.G
+    }
+
+    static is(sources : any) : sources is Sources {
+        return (
+            sources !== undefined &&
+            Array.isArray(sources.B) &&
+            sources.B.every(BillDocumentSource.is) &&
+            Array.isArray(sources.S) &&
+            sources.S.every(ScoutDocumentSource.is) &&
+            Array.isArray(sources.J) &&
+            sources.J.every(JurisdictionDocumentSource.is) &&
+            Array.isArray(sources.G) &&
+            sources.G.every(GrokSource.is)
+        )
+    }
+}