add_to_wishlist
ChatGPTAdd a pressing to the signed-in user's wishlist with a Desire level. The pressing is one from Needl's catalogue that they do not own: a catalog entry from show_artist or show_record. Call it only when the user asks to add it. If it is already on the wishlist its Desire level is brought up to date, and if they already own that pressing nothing is added and their copy is returned: read notice and say which happened. Nothing is bought; this is a list.
get_last_pick
ChatGPTThe record Shuffle last picked for the signed-in user, here or in the app, and when. Use it for "what was the last record I picked", "what did Shuffle give me". A pick is a selection, not a listen: never say the record was played because it was picked. record null with an album means the picked record is no longer in the collection; picked_at null means there is no pick on record.
get_listening_history
ChatGPTList what the signed-in user played in a period, newest first: vinyl (songs Needl recognised while a record played, and records the user logged), plus Apple Music and Spotify plays Needl has synced. Use it for "what did I play yesterday", "what was I listening to an hour ago", or to see the plays behind a summary. It returns data for you to read; to show the user their listening, use show_listening instead. Work out the period from the user's own time zone. An empty list means Needl saw no plays, not that the user listened to nothing. Results are paged: pass next_cursor back as cursor.
get_listening_summary
ChatGPTSummarise what the signed-in user listened to in a period: plays and estimated minutes per source (vinyl, Apple Music, Spotify), and their top artists, albums and songs. It returns data for you to read and reason with; to show the user their listening, use show_listening or show_top_artists instead. Work out the period from the user's own time zone (for "this month": the first of the month at 00:00 local time until now). Read the result honestly: minutes are track and record lengths, not time spent listening, and are missing for most recognised vinyl songs (see plays_without_duration); a logged record counts as one play; and has_any_history false means that source is not connected to Needl, not that the user did not listen.
get_now_playing
ChatGPTWhat is playing on the signed-in user's turntable right now: the song Needl most recently recognised in the Listen session running on their device, shown in the chat. Call it whenever the user means the music playing now without naming it: "what's on my turntable", "what's playing", "tell me about this song", "what should I play after this". Read status before answering: only "live" means a song was heard in the last few minutes. "listening" means a session is running but nothing has been recognised yet. "stale", "ended" and "none" mean nothing is known to be playing now: say so, and if you mention the last song, say when it was heard (last_heard_at). record is the one of the user's own records the Needl app confirmed this song is playing from: when it is set, name it plainly. When it is null the app has not tied the song to a record, and owned_matches are only the user's records by that artist (the same album first when it is known): say which it is likely to be rather than stating it as fact, and never name a pressing or a colour for it. This never changes Shuffle or the listening history, and a Shuffle pick is never evidence of what is playing.
get_record
ChatGPTRead one record from the signed-in user's own Needl collection by its id, as returned by search_my_records. Use it when you need the facts about a specific copy without showing it: condition, notes, what was paid, and the pressing (label, catalog number, country, pressing year, edition) where Needl knows them. To show the record, use show_record instead.
mark_as_bought
ChatGPTMove an entry from the signed-in user's wishlist into their collection: the app's Mark as Bought. It records that they now own it. It does NOT buy anything, and no price, purchase date or rating is made up. The entry leaves the wishlist. Call it only when the user says they bought or got the record. If they already own that pressing, nothing is created and their existing copy is returned: read notice and say which happened.
search_my_records
ChatGPTSearch the signed-in user's own Needl record collection (records they own, not their wishlist). Use it for questions like "do I own…", "what do I have by…", or to list the collection. Every filter is optional and they combine; with no filters it lists everything, sorted by artist. Results are paged: pass next_cursor back as cursor for the next page. Returns one entry per copy owned, so two copies of an album appear twice. To show records in the chat, pass their ids to show_records or show_record; for the user's top records (most played, highest rated, latest), use show_top_records, which ranks and shows in one step.
search_my_wishlist
ChatGPTSearch the signed-in user's own Needl wishlist: records they want but do not own yet. Use it for "what's on my wishlist", "do I want…", or to pick something to buy. Every filter is optional; with none it lists the whole wishlist, most wanted first. Each entry has a Desire level (Someday, Nice to Have, Must Have, Holy Grail). Results are paged: pass next_cursor back as cursor for the next page.
set_desire
ChatGPTChange how much the signed-in user wants a record on their wishlist: its Desire level (Someday, Nice to Have, Must Have, Holy Grail). Call it only when the user asks for the change and names the level. It changes that one entry in Needl, and in the app once it syncs.
show_artist
ChatGPTShow everything the signed-in user has by one artist, in three groups: records they own, entries on their wishlist, and albums Needl's catalogue has by that artist that they have neither. Use it for "what do I have by…", "show me my … albums", "more by…". Pass the artist's name as the user's records spell it. not_owned is what Needl's catalogue happens to hold, not a full discography: never call it complete, and never say the user is missing only those. A group that is empty has no matching records. wishlist null means the wishlist is not shared with you, not that it is empty.
show_listening
ChatGPTShow the signed-in user what they listened to in a period. Listening has two sectors, and sector picks the view: "physical" is vinyl and CD (listening sessions, the albums in them, session time); "streaming" is Apple Music and Spotify (recorded track plays, with albums, artists and tracks); "combined" puts both side by side. Use physical for "what did I listen to on vinyl", "my sessions this week"; streaming for "what did I stream", "my top albums on Apple Music"; combined for a plain "what did I listen to last month". For a calendar month's recap by name ("my Pressed for September") use show_pressed. Work out the period from the user's own time zone and write the times with its offset: last month is the first of that month 00:00 to the first of this month 00:00; this week runs to now, so leave end out. Read the result honestly and say it the same way: a physical figure is sessions and session time, a streaming figure is track plays (never album listens, never listening time), each service is counted on its own, and a period still running is "so far". has_any_history false means that source is not connected to Needl, not that nothing was played. A session with no album was not tied to a record: do not guess one.
show_listening_session
ChatGPTShow one of the signed-in user's vinyl or CD listening sessions: when it was, how long, and the songs Needl identified in it. Pass a session id from show_listening. Song lengths are the tracks' own, not time spent; a session with no album was not tied to a record.
show_pressed
ChatGPTShow the signed-in user's Pressed recap for one calendar month: their physical listening (sessions, albums, session time), the most-streamed album on each streaming service, and how many records they picked with Shuffle. Use it when they ask for Pressed, or for a month's recap or wrap-up. The month is taken in the user's own time zone. Each source is counted on its own: physical in sessions, streaming in recorded track plays. Shuffle picks are selections, not listens. For any other period, use show_listening.
show_record
ChatGPTShow one record in the chat: the cover with the record itself drawn in the colour of its pressing, and a button that opens it full screen with its pressing details and (for an owned record) how often it has been played. The view keeps to a few facts: the label, catalogue number, edition and the rest of pressing are yours to give when the user asks. On that page, tapping the record opens its centre label up close, side by side, with the tracks cut into each side as Discogs lists them (label): use it for "what's on side B", and say the user can tap the record to see it. from says where the id is from: "collection" and "wishlist" for ids from the search tools, "catalog" for a pressing the user has neither (ids in not_owned from show_artist). When all you have is a name (listening results name albums and carry no ids), pass album and artist instead of an id: Needl opens the user's own copy if they have one, their wishlist entry if not, and otherwise the pressing in its catalogue. Call it when the user asks to see, open or look up one record. If two copies match, use the year, format and colour the user gave to pick. The card stays short on purpose: use also_show only for what this request is about, and answer the question in your reply as well. Read the result honestly. Prices: the only one here is card.price_paid, what the user paid for their own copy. Needl gives assistants no market value, asking price or sold price: if the user asks what a record is worth, say Needl shows market value in its app but does not share it here, give what they paid when it is recorded, and never estimate a value yourself. pressing: a false flag or a null means not recorded, not no. label.sides empty means Needl has no tracklist for this pressing: say so, never recite one from memory. card.color null means the colour is unknown, not black. The label details and the tracklist are Discogs' data: when you quote them, add "Data provided by Discogs" with a link to pressing.discogs_url. Afterwards add one short line at most.
show_records
ChatGPTShow records from the signed-in user's collection or wishlist in the chat. Call it after search_my_records or search_my_wishlist, passing the ids worth showing, whenever the user would want to see the records: browsing, "what do I have by…", picks, or recommendations from their own shelf or wishlist. The view lays itself out by how many there are: one record as a large card with its disc, two side by side, a few as a list, six to eight as a row of covers to swipe, and more as the first four with a button that opens them all. Pass every record that answers the request, up to 50, in the order to show them. The user can open any record for its pressing details and how often it has been played, so afterwards add one short line at most instead of repeating what the view shows. For one record the user asked about by name, show_record gives the view more to work with.
show_top_artists
ChatGPTShow the signed-in user's top artists as a row of portraits. sector says what "top" counts: "combined" is every play Needl recorded in the period (turntable, logged records and both streaming services, added together); "physical" is vinyl and CD only; "streaming" is Apple Music and Spotify (or the one service named); "collection" is the artists the user owns the most records by, which needs no period. Use combined for a plain "who are my top artists", with the period the user gave or the last 30 days. Say what was counted: plays are recorded plays, not hours; a combined figure adds different kinds of play together, and sources says where each artist's came from.
show_top_records
ChatGPTRank the signed-in user's own records and show them in the chat, in one step. Use it when the user asks for their top, best, favourite, most played or latest records. "Top" has to mean something: by is "rating" (their own star ratings, highest first), "plays" (recorded plays, most first), "recently_bought" or "recently_added". Take it from what the user said; if they only said "top" and nothing suggests which, ask them in one short question rather than guessing. Read the result honestly: ratings are the user's own and many records have none; plays are what Needl recorded (songs it recognised on the turntable and records logged), not full listens; a record with no recorded plays was not necessarily never played. When empty is set there was nothing to rank: say so plainly, as the view does, and offer the other orders.
shuffle_records
ChatGPTPick 1 to 8 records at random from the signed-in user's collection with Needl's Shuffle, and show them. This is the same Shuffle as in the app and it CHANGES its state: a picked record is out of the pool until every record has had its turn, here and in the app. So call it only when the user asks for a pick: "shuffle", "pick something to spin", "surprise me", "what should I play", "shuffle again". For suggestions, options or browsing that should not use up picks, use search_my_records and show_records instead. Each call makes new picks, so never call it twice for one request, and do not call it again to "check". Filters narrow the pool; if nothing left in this round matches, nothing is picked and note says why: tell the user and offer a broader pick rather than retrying on your own. A picked record is only picked. Never say it is playing, and do not log it as listened to.
