Skip to content

trading_agent.journal.journal_reader

Reads the events a journal folder holds for one India date.

Typical usage example:

reader = JournalReader(layout.desk_directory('general') / 'journal') events = reader.events(reader.today(), ['order', 'fill'])

JournalReader 

JournalReader(folder, clock=None)

The journal files of one desk, or of the gateway.

Creates the reader without reading anything.

Parameters:

Name Type Description Default
folder Path

The journal folder, holding one YYYY-MM-DD.jsonl file per India date.

 required
clock Callable[[], datetime] | None

Returns the current time; None uses the system clock.

 None
Source code in src/trading_agent/journal/journal_reader.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
def __init__(
    self,
    folder: Path,
    clock: Callable[[], datetime.datetime] | None = None,
):
    """Creates the reader without reading anything.

    Args:
        folder (Path): The journal folder, holding one YYYY-MM-DD.jsonl file per India date.
        clock (Callable[[], datetime.datetime] | None): Returns the current time; None uses the system clock.
    """
    self._folder = folder
    self._clock = clock

today 

today()

Today's India date, as the name its journal file uses.

Returns:

Type Description
str

The date, such as "2026-10-19".
Source code in src/trading_agent/journal/journal_reader.py 
36
37
38
39
40
41
42
43
44
45
46
def today(self) -> str:
    """Today's India date, as the name its journal file uses.

    Returns:
        str: The date, such as "2026-10-19".
    """
    if self._clock is None:
        now = datetime.datetime.now(_INDIA)
    else:
        now = self._clock().astimezone(_INDIA)
    return now.date().isoformat()

events 

events(day, kinds=None)

Reads one day's events, oldest first, skipping lines that are not JSON.

Parameters:

Name Type Description Default
day str

The India date, such as "2026-10-19".

 required
kinds Collection[str] | None

The event kinds to keep, such as "order"; None keeps every kind.

 None

Returns:

Type Description
list[dict[str, Any]]

The events, each with kind, desk, payload and created_at. The list is empty when the day has no file.
Source code in src/trading_agent/journal/journal_reader.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def events(
    self,
    day: str,
    kinds: Collection[str] | None = None,
) -> list[dict[str, Any]]:
    """Reads one day's events, oldest first, skipping lines that are not JSON.

    Args:
        day (str): The India date, such as "2026-10-19".
        kinds (Collection[str] | None): The event kinds to keep, such as "order"; None keeps every kind.

    Returns:
        list[dict[str, Any]]: The events, each with kind, desk, payload and created_at. The list is empty when the day has no file.
    """
    path = self._folder / f'{day}.jsonl'
    if not path.is_file():
        return []
    events = []
    for line in path.read_text(encoding='utf-8').splitlines():
        try:
            event = json.loads(line)
        except ValueError:
            continue
        if kinds is None or event.get('kind') in kinds:
            events.append(event)
    return events