Skip to content

How To Use an Emitter

Jump to bottom
Fernando Koch edited this page Mar 30, 2026 · 3 revisions

How To Use An Emitter

Purpose

Use Emitter when you want GraphK to behave like a request/response dispatcher over a registered set of pipelines instead of a manually managed runner.

Emitter works with a Program:

  • Program stores pipelines by id
  • Emitter selects one pipeline by id or by program default
  • Runner is created transiently for each request

When Should You Use It?

Use Emitter when:

  • you want to expose several pipelines behind one public interface
  • you want pipeline storage separated from execution
  • you want a request/response API that feels simpler than managing Runner directly

Prefer Runner when you need lower-level execution control over one pipeline.

Core Methods

request(id=None, session=None)

Purpose:

  • resolve a pipeline id from the program
  • create a session if one is not provided
  • execute the selected pipeline through a transient runner
  • cache the resulting session
  • return that session

Behavior:

  • if id is omitted and the program has one pipeline, that pipeline is used
  • if id is omitted and the program has a configured default, that pipeline is used
  • if the id is unknown, or dispatch is ambiguous, an exception is raised
  • the emitter does not keep or reuse runner instances

response(default=None)

Purpose:

  • read the current response payload from the cached session

reset(session=None)

Purpose:

  • replace the cached session

enable_log(level=graphk.Logger.DEBUG)

Purpose:

  • enable logging on the transient runners created for requests

Smallest Useful Example

import graphk


pipeline = graphk.SequencePipe(nodes=[graphk.demo.EchoNode()])
program = graphk.Program({"echo": pipeline})
emitter = graphk.Emitter(program)

emitter.request("echo", graphk.Session(value=5))

print(emitter.response())

Example With Implicit Default

import graphk


pipeline = graphk.SequencePipe(nodes=[graphk.demo.EchoNode()])
program = graphk.Program({"echo": pipeline})
emitter = graphk.Emitter(program)

session = emitter.request(session=graphk.Session(value=5))

print(session.to_dict())
print(emitter.response())

This works because the program has only one registered pipeline.

Example With Logging

import graphk


pipeline = graphk.SequencePipe(nodes=[graphk.demo.EchoNode()])
program = graphk.Program({"echo": pipeline})
emitter = graphk.Emitter(program)

emitter.enable_log(graphk.Logger.DEBUG)
session = emitter.request("echo", graphk.Session(value=5))

print(session.to_dict())
print(emitter.response())

Example With A Preloaded Session

import graphk


base = graphk.Session(prefix="base", counter=10, value=3)

pipeline = graphk.SequencePipe(
    nodes=[
        graphk.demo.ApplyNode(
            "PrefixEcho",
            fn=lambda session: f"{session.get('prefix', 'ok')}:{session.get('value', 0)}",
            response_key="response",
        )
    ]
)

program = graphk.Program({"prefix": pipeline})
emitter = graphk.Emitter(program)
session = emitter.request("prefix", base)

print(session is base)
print(emitter.response())

How Response Is Stored

By default, the emitter reads the response payload from the cached session key:

  • response key: response

Nodes in the selected pipeline should write their final payload into response if they are intended to feed the emitter response directly.

Good built-in options:

  • EchoNode
  • ApplyNode
  • IncrementNode(..., response=True)
  • ConcatNode(..., response=True)
  • RouteNode

Relationship To Runner

Internally, Emitter is a convenience dispatcher that creates a fresh Runner for each call to request(...).

Use Emitter when:

  • you want the package to feel like a reusable service
  • you want dispatch by pipeline id
  • you want one method call per request

Use Runner when:

  • you need direct start/step/run control
  • you want to inspect execution at a lower level

Common Mistakes

  • Do not initialize Emitter with a raw pipeline; initialize it with a Program.
  • Do not assume a response appears automatically unless nodes write to response.
  • Do not forget that request input now lives in the provided Session.
  • Do not omit id when the program has multiple pipelines unless a default pipeline is configured.
  • Do not reimplement program dispatch when Emitter already matches the use case.

Learn More

Recommended references:

Clone this wiki locally