Needl

Show 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

Show 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_artists

Rank 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.

show_top_records

Show 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_listening_session

Show 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_record

Show 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_records

Pick 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.

shuffle_records

Summarise 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_listening_summary

What 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_now_playing