circuits-agent
Safe HaskellNone
LanguageGHC2024

Circuit.Agent.Query

Description

Generic query-to-shard adapters.

Turns any Text -> IO Text boundary into a Shard that consumes addressed posts and emits reply posts. The functions here know nothing about external CLI processes, session files, or concrete binaries — that operational layer lives in Free.Agent.Cli.

Synopsis

Session assembly and reply building

sessionPrompt :: [Post Text] -> Text Source #

Session assembly for the opaque seat: bodies, oldest-first, one per line.

This is the discoverable side of the boundary (data). How the query folds it is not.

replyPosts :: Text -> [Post Text] -> [PostId] -> Text -> [Post Text] Source #

Build reply posts from a cleaned agent response.

Addresses the last input's sender, preserves any other names on the original wire (e.g. the bus channel), and threads onto the last input's PostId when one is supplied. Empty reply → no posts (quiet).

The caller passes one PostId per input post in the same order. If the ids are missing or misaligned, the reply is still addressed correctly but carries no thread edge (see mkPost) — the honest fallback when a shard does not have access to the stamped log.

synthesisPosts :: Text -> [Post Text] -> [PostId] -> Text -> [Post Text] Source #

Build one synthesis post from a cleaned agent response.

The honest twin of replyPosts for seats that fold every input into their answer: ancestry cites every input's PostId (see synthesis), and the audience is every input's sender and wire name, minus self. Empty reply or no inputs → no posts (quiet).

The caller passes one PostId per input post. If ids are missing the synthesis is still addressed correctly but carries no thread edge.

Shard adapters

queryShard :: Text -> (Text -> IO Text) -> IO (Shard IO [Post Text] [Post Text]) Source #

Opaque evaluate seat: any Text -> IO Text behind list ends.

Commit assembles a session prompt from the input posts; emit is replyPosts of the query result (empty = quiet).

TODO: this generic seat does not have access to stamped log ids, so emitted replies carry no thread edge. Callers that need provenance should use a variant that supplies parent ids.

queryShardWith :: (Text -> [Post Text] -> [PostId] -> Text -> [Post Text]) -> Text -> (Text -> IO Text) -> IO (Shard IO [Post Text] [Post Text]) Source #

queryShard parameterised on the reply-to-posts builder.

synthShard :: Text -> (Text -> IO Text) -> IO (Shard IO [Post Text] [Post Text]) Source #

Opaque synthesis seat: like queryShard, but the emit cites every input's sender as ancestry (synthesisPosts). For seats that fold the whole input into one answer — the honest-provenance twin of queryShard.

TODO: like queryShard, the generic seat has no ids and therefore emits syntheses without thread edges.

echoShard :: Text -> IO (Shard IO [Post Text] [Post Text]) Source #

Mock seat: reply body is the session prompt (echo).

Demonstrates the living-agent path without a real query.

runShardIO :: Shard IO [Post Text] [Post Text] -> [Post Text] -> IO [Post Text] Source #

One closed shard turn: commit ins, emit replies.