compass-local 0.0.1__tar.gz

compass_local-0.0.1/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: compass-local
+Version: 0.0.1
+Summary: PyPI compass-local Python Package owned by Circlez.ai
+Home-page: https://github.com/circles-zone/compass-local-python-package
+Author: Circles
+Author-email: info@circlez.ai
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+Requires-Dist: python-sdk-remote
+Requires-Dist: logger-local
+Requires-Dist: database-mysql-local
+Requires-Dist: contact-profile-local
+Requires-Dist: contact-group-local
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: summary
+
+PyPI compass-local Python Package owned by Circlez.ai
+Compass: multi-agent personal-assistant system (local package).
+GHA: https://github.com/circles-zone/compass-local-python-package/actions

compass_local-0.0.1/README.md

@@ -0,0 +1,56 @@
+# compass-local
+
+**Compass** is a multi-agent personal-assistant system built over a person's data
+(events/calendar, contacts, tasks, communications, campaigns). "Compass" is the
+name of the program as a whole; `compass-local` is its **local package** — the
+direct database-access layer (tools + agents) that the assistant is built on.
+
+The system is organized as specialist agents, each owning one data domain, plus
+synthesis and orchestration agents on top. Development starts with the **Calendar
+agent** (events I'm attending, people I'm going to meet, face-to-face vs. remote).
+
+## Structure
+
+```
+compass-local-python-package/     # repo directory (same name as the repo)
+  compass_local/                  # the package
+    src/                          # source: tools, agents, constants, version
+    tests/                        # pytest unit/system tests
+  database/                       # MySQL schema / views / test-data scripts
+  setup.py  pytest.ini  pyproject.toml  requirements*.txt  .flake8
+```
+
+## Install (development)
+
+Use a virtualenv. On Windows, WSL is recommended.
+
+```shell
+python -m venv venv
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+```
+
+## Test
+
+```shell
+pytest
+```
+
+Tests run without a live database where possible: `tests/conftest.py` sets safe
+env defaults and skips tests that need a MySQL host when none is reachable.
+
+## Lint (mandatory before push)
+
+```shell
+flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+```
+
+## Contributing / workflow
+
+Work on a `BU-*` feature branch, keep the feature-branch GitHub Actions workflow
+green with no warnings and coverage above 90%, then open a Pull Request into `dev`.
+
+## Versions
+
+- 0.0.1 — initial Compass package setup (structure, config, calendar agent).

compass_local-0.0.1/compass_local/src/calendaring/__init__.py

@@ -0,0 +1,5 @@
+"""The Calendar agent: deterministic calendar tools + its reasoning layer.
+
+Named ``calendaring`` (not ``calendar``) so it does not shadow the Python
+standard library's ``calendar`` module on the test/runtime path.
+"""

compass_local-0.0.1/compass_local/src/calendaring/calendar_agent.py

@@ -0,0 +1,97 @@
+"""Calendar agent -- a thin RoutingAgent configured for calendar questions.
+
+All the LLM-routing plumbing (prompt build, JSON parse, guarded dispatch, and the
+bad-JSON / unknown-tool / bad-args robustness) lives once in core.routing_agent.
+This module only supplies the calendar specifics: the tool catalog with its
+per-tool result formatters, the CalendarTools binding, and the router's role line.
+"""
+
+from core.routing_agent import RoutingAgent
+from calendaring.calendar_tools import CalendarTools
+
+
+def _format_events(events: list[dict]) -> str:
+    if not events:
+        return "No events found."
+    lines = []
+    for event in events:
+        # Prefer the display name, then name/title. These are the flat-contract
+        # keys the tools emit; calendar_reader maps them from the real schema
+        # (start_datetime <- start_timestamp, location_type <- location view).
+        label = (event.get("display_as") or event.get("name")
+                 or event.get("title") or f"event {event.get('event_id')}")
+        start = event.get("start_datetime") or ""
+        location = event.get("location_type")
+        suffix = f" [{location}]" if location else ""
+        lines.append(f"- {label} ({start}){suffix}".rstrip())
+    return "\n".join(lines)
+
+
+def _format_contacts(contacts: list[dict]) -> str:
+    if not contacts:
+        return "No contacts found."
+    lines = []
+    for contact in contacts:
+        label = (contact.get("display_as") or contact.get("name")
+                 or f"contact {contact.get('contact_id')}")
+        extras = [x for x in (contact.get("role"), contact.get("email1")) if x]
+        suffix = f" ({', '.join(extras)})" if extras else ""
+        lines.append(f"- {label}{suffix}")
+    return "\n".join(lines)
+
+
+# name -> tool description (for the routing prompt) + result formatter. Keys are
+# the exact CalendarTools method names, so dispatch is a guarded getattr.
+_CATALOG: dict[str, dict] = {
+    "get_events_today": {
+        "desc": "events on a given day; args: today (ISO date, optional).",
+        "format": _format_events,
+    },
+    "get_events": {
+        "desc": "events overlapping a datetime range; args: range_start, range_end (ISO-8601).",
+        "format": _format_events,
+    },
+    "get_face_to_face_events": {
+        "desc": "in-person events in a range; args: range_start, range_end.",
+        "format": _format_events,
+    },
+    "get_remote_events": {
+        "desc": "remote events in a range; args: range_start, range_end.",
+        "format": _format_events,
+    },
+    "get_people_i_will_meet": {
+        "desc": "distinct contacts attending any event in a range; args: range_start, range_end.",
+        "format": _format_contacts,
+    },
+    "get_event_attendees": {
+        "desc": "contacts attending an event, with their role; args: event_id (int).",
+        "format": _format_contacts,
+    },
+    "get_meeting_followups": {
+        "desc": "people to follow up with after a meeting; args: event_id (int).",
+        "format": _format_contacts,
+    },
+    "get_contacts_in_group": {
+        "desc": "contacts in a named group, e.g. 2Call1; args: group_name (str).",
+        "format": _format_contacts,
+    },
+}
+
+_ROLE = "You are the Calendar agent's router."
+# English renderings of the failure codes; the code is the contract, not these.
+_NO_TOOL_MESSAGE = "Sorry, I couldn't map that to a calendar action."
+_BAD_CALL_MESSAGE = "Sorry, I couldn't run that calendar action with those details."
+
+
+class CalendarAgent(RoutingAgent):
+    """Answers natural-language calendar questions by routing to one tool."""
+
+    def __init__(self, llm, tools: CalendarTools | None = None) -> None:
+        super().__init__(
+            llm,
+            tools if tools is not None else CalendarTools(),
+            catalog=_CATALOG,
+            role=_ROLE,
+            no_tool_message=_NO_TOOL_MESSAGE,
+            bad_call_message=_BAD_CALL_MESSAGE,
+        )

compass_local-0.0.1/compass_local/src/calendaring/calendar_data_source.py

@@ -0,0 +1,39 @@
+"""The seam between the Calendar tools and wherever the data physically lives.
+
+Implementations return RAW ROWS ONLY -- no filtering, joining or date logic.
+That logic lives in the tools, so it is written and tested exactly once no
+matter which source is plugged in.
+
+Known implementations:
+  - ``FixtureDataSource``        -> the bundled sample dataset (fixture_data_source.py)
+  - ``EventProfileDataSource``   -> the real normalized model (event_profile_data_source.py)
+
+The tools depend on this interface, never on a concrete source, so swapping the
+source touches only the edges.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class CalendarDataSource(ABC):
+    """Interface every calendar data source must satisfy.
+
+    Each method returns a list of row dicts using the real column names (see the
+    package README / data model).
+    """
+
+    @abstractmethod
+    def get_events(self) -> list[dict]:
+        """All event rows (event_table columns + datetime/location)."""
+
+    @abstractmethod
+    def get_contacts(self) -> list[dict]:
+        """All contact rows (contact_table columns)."""
+
+    @abstractmethod
+    def get_event_contacts(self) -> list[dict]:
+        """Event<->contact links: {event_id, contact_id, role}."""
+
+    @abstractmethod
+    def get_group_memberships(self) -> list[dict]:
+        """Contact group links: {contact_id, group_name}."""

compass_local-0.0.1/compass_local/src/calendaring/calendar_reader.py

@@ -0,0 +1,37 @@
+"""The narrow read port over the normalized circlez tables.
+
+Each method returns raw row dicts using the real column names; it performs no
+joins or flattening -- that is the adapter's job (event_profile_data_source.py).
+Keeping the port this thin is what lets all the join/flatten/role/datetime logic
+be unit-tested without a database.
+
+The concrete implementation that talks to the real circlez packages is
+``GenericCrudCalendarReader`` (generic_crud_calendar_reader.py).
+"""
+
+from typing import Protocol
+
+
+class CalendarReader(Protocol):
+    """Narrow read port over the normalized tables.
+
+    ``to_registered_profile_id`` is normalized here (the underlying view exposes
+    it as ``to.registered_profile_id``) so the adapter logic can stay clean.
+    """
+
+    def fetch_events(self) -> list[dict]:
+        """event_view rows for the user: event_id, start_datetime, end_datetime,
+        location_type, day/month/year, and the rest of the event columns."""
+
+    def fetch_contacts(self) -> list[dict]:
+        """contact_view rows: contact_id, display_as, email1, phone1, ..."""
+
+    def fetch_event_profiles(self) -> list[dict]:
+        """event_profile_view rows: event_id, to_registered_profile_id, and the
+        is_* state flags (is_checked_in, is_will_arrive, is_admin, is_invited)."""
+
+    def fetch_contact_profiles(self) -> list[dict]:
+        """contact_profile_view rows: contact_id, profile_id."""
+
+    def fetch_contact_group_memberships(self) -> list[dict]:
+        """Contact-group rows already resolved to a name: contact_id, group_name."""

compass_local-0.0.1/compass_local/src/calendaring/calendar_seed_data.py

@@ -0,0 +1,141 @@
+"""Bundled sample dataset for Compass (invented test/demo data).
+
+Rows are in the flat shape the deterministic tools consume; the real adapter maps
+the normalized model onto this same shape. Field names follow the installed
+schema where they overlap:
+  - contacts -> contact_table (contact-local): contact_id, first_name, last_name,
+    display_as, email1, phone1, updated_timestamp.
+  - events   -> event_view (event package): event_id, name, organizers_profile_id,
+    location_id. The tools read start_datetime / end_datetime / location_type,
+    which the real reader derives from event_view.start_timestamp / end_timestamp
+    and the location_type model; here they are provided directly.
+
+CALENDAR_SEED_EVENT_CONTACTS and CALENDAR_SEED_GROUP_MEMBERSHIPS are flat stand-ins for the profile-mediated
+attendee chain and the contact-group mapping (the reader produces the same rows
+from the real tables).
+
+All rows carry is_test_data=1 so they are trivially separable from real data.
+The user the assistant serves is organizers_profile_id = 1.
+"""
+
+CALENDAR_SEED_USER_PROFILE_ID = 1
+
+# ---------------------------------------------------------------------------
+# contact_table  (real columns; audit columns omitted for readability)
+# ---------------------------------------------------------------------------
+CALENDAR_SEED_CONTACTS = [
+    {"contact_id": 3001, "first_name": "Dana", "last_name": "Levi",
+     "display_as": "Dana Levi", "email1": "dana@acme.vc",
+     "phone1": "+972-50-1112222", "updated_timestamp": "2026-07-01T09:00:00",
+     "is_test_data": 1},
+    {"contact_id": 3002, "first_name": "Omer", "last_name": "Cohen",
+     "display_as": "Omer Cohen", "email1": "omer@beta.io",
+     "phone1": "+972-52-3334444", "updated_timestamp": "2026-06-28T14:00:00",
+     "is_test_data": 1},
+    {"contact_id": 3003, "first_name": "Yael", "last_name": "Barak",
+     "display_as": "Yael Barak", "email1": "yael@northwind.com",
+     "phone1": "+972-54-5556666", "updated_timestamp": "2026-07-04T11:30:00",
+     "is_test_data": 1},
+    {"contact_id": 3004, "first_name": "Noa", "last_name": "Friedman",
+     "display_as": "Noa Friedman", "email1": "noa@zenith.co",
+     "phone1": "+972-58-7778888", "updated_timestamp": "2026-07-05T08:15:00",
+     "is_test_data": 1},
+    {"contact_id": 3005, "first_name": "Itai", "last_name": "Shapira",
+     "display_as": "Itai Shapira", "email1": "itai@quanta.ai",
+     "phone1": "+972-53-9990000", "updated_timestamp": "2026-06-20T16:45:00",
+     "is_test_data": 1},
+    {"contact_id": 3006, "first_name": "Maya", "last_name": "Gold",
+     "display_as": "Maya Gold", "email1": "maya@lumen.dev",
+     "phone1": "+972-50-2223333", "updated_timestamp": "2026-07-06T07:00:00",
+     "is_test_data": 1},
+    {"contact_id": 3007, "first_name": "Eitan", "last_name": "Peretz",
+     "display_as": "Eitan Peretz", "email1": "eitan@orbit.vc",
+     "phone1": "+972-52-4445555", "updated_timestamp": "2026-05-30T10:00:00",
+     "is_test_data": 1},
+    {"contact_id": 3008, "first_name": "Tamar", "last_name": "Azoulay",
+     "display_as": "Tamar Azoulay", "email1": "tamar@delta.io",
+     "phone1": "+972-54-6667777", "updated_timestamp": "2026-07-03T13:20:00",
+     "is_test_data": 1},
+    {"contact_id": 3009, "first_name": "Roi", "last_name": "Mizrahi",
+     "display_as": "Roi Mizrahi", "email1": "roi@sigma.com",
+     "phone1": "+972-58-8889999", "updated_timestamp": "2026-06-15T09:45:00",
+     "is_test_data": 1},
+    {"contact_id": 3010, "first_name": "Shira", "last_name": "Katz",
+     "display_as": "Shira Katz", "email1": "shira@vega.co",
+     "phone1": "+972-53-1114444", "updated_timestamp": "2026-07-02T15:00:00",
+     "is_test_data": 1},
+]
+
+# ---------------------------------------------------------------------------
+# events  (event_view columns: event_id, name, organizers_profile_id, location_id)
+# start_datetime / end_datetime / location_type are the flat-contract fields the
+# tools read -- the real reader derives them from start_timestamp / end_timestamp
+# and the location_type model. Dates span "today" = 2026-07-06 and the
+# surrounding days, so "events today" and "this week" both have coverage.
+# ---------------------------------------------------------------------------
+CALENDAR_SEED_EVENTS = [
+    {"event_id": 9001, "name": "Coffee with Dana - partnership intro",
+     "organizers_profile_id": 1, "location_id": 4101,
+     "start_datetime": "2026-07-06T10:00:00", "end_datetime": "2026-07-06T10:45:00",
+     "location_type": "in_person", "is_test_data": 1},
+
+    {"event_id": 9002, "name": "Beta.io product sync",
+     "organizers_profile_id": 1, "location_id": 4102,
+     "start_datetime": "2026-07-06T14:00:00", "end_datetime": "2026-07-06T14:30:00",
+     "location_type": "remote", "is_test_data": 1},
+
+    {"event_id": 9003, "name": "Northwind onboarding call",
+     "organizers_profile_id": 1, "location_id": 4103,
+     "start_datetime": "2026-07-07T09:30:00", "end_datetime": "2026-07-07T10:15:00",
+     "location_type": "remote", "is_test_data": 1},
+
+    {"event_id": 9004, "name": "Lunch with Itai & Maya",
+     "organizers_profile_id": 1, "location_id": 4104,
+     "start_datetime": "2026-07-08T12:30:00", "end_datetime": "2026-07-08T13:30:00",
+     "location_type": "in_person", "is_test_data": 1},
+
+    {"event_id": 9005, "name": "AI Circles meetup - networking",
+     "organizers_profile_id": 1, "location_id": 4105,
+     "start_datetime": "2026-07-09T18:00:00", "end_datetime": "2026-07-09T21:00:00",
+     "location_type": "in_person", "is_test_data": 1},
+
+    {"event_id": 9006, "name": "Delta.io contract review",
+     "organizers_profile_id": 1, "location_id": 4106,
+     "start_datetime": "2026-07-06T16:30:00", "end_datetime": "2026-07-06T17:00:00",
+     "location_type": "remote", "is_test_data": 1},
+]
+
+# ---------------------------------------------------------------------------
+# PROPOSED link table: event_contact_table  (who attends which event)
+# role is calendar-standard attendance state (Google Calendar responseStatus /
+# iCalendar PARTSTAT, plus organizer/checked_in): one of
+#   {"organizer", "checked_in", "accepted", "tentative", "declined", "needs_action"}.
+# The real adapter derives the same values from the event_profile is_* flags.
+# ---------------------------------------------------------------------------
+CALENDAR_SEED_EVENT_CONTACTS = [
+    {"event_id": 9001, "contact_id": 3001, "role": "accepted"},
+    {"event_id": 9002, "contact_id": 3002, "role": "accepted"},
+    {"event_id": 9003, "contact_id": 3003, "role": "needs_action"},
+    {"event_id": 9004, "contact_id": 3005, "role": "accepted"},
+    {"event_id": 9004, "contact_id": 3006, "role": "tentative"},
+    {"event_id": 9005, "contact_id": 3004, "role": "organizer"},
+    {"event_id": 9005, "contact_id": 3007, "role": "checked_in"},
+    {"event_id": 9005, "contact_id": 3010, "role": "accepted"},
+    {"event_id": 9006, "contact_id": 3008, "role": "declined"},
+]
+
+# ---------------------------------------------------------------------------
+# PROPOSED link table: contact_group_membership
+# Groups are the challenge's target groups: 2Call1..3, 2Contact1..3
+# ---------------------------------------------------------------------------
+CALENDAR_SEED_GROUP_MEMBERSHIPS = [
+    {"contact_id": 3001, "group_name": "2Call1"},
+    {"contact_id": 3003, "group_name": "2Call1"},
+    {"contact_id": 3002, "group_name": "2Call2"},
+    {"contact_id": 3005, "group_name": "2Call3"},
+    {"contact_id": 3004, "group_name": "2Contact1"},
+    {"contact_id": 3006, "group_name": "2Contact1"},
+    {"contact_id": 3007, "group_name": "2Contact2"},
+    {"contact_id": 3009, "group_name": "2Contact3"},
+    {"contact_id": 3010, "group_name": "2Contact3"},
+]

compass_local-0.0.1/compass_local/src/calendaring/calendar_tools.py

@@ -0,0 +1,126 @@
+"""Deterministic Calendar tools.
+
+Thin, no-LLM functions over a CalendarDataSource. Each is pure and independently
+unit-testable: given the same data it returns the same result, with no network,
+no database, and no model calls. The agent layer (added later) decides which of
+these to call for a natural-language request; these tools just answer.
+
+Date handling uses the standard library only, so the tools are testable without
+the private circlez packages. Each event's start/end is taken from the PROPOSED
+start_datetime/end_datetime when present, else derived from the provided
+day/month/year columns -- so the tools work against the real event_table too.
+"""
+
+from datetime import date, datetime
+
+from calendaring.calendar_data_source import CalendarDataSource
+from calendaring.fixture_data_source import FixtureDataSource
+
+
+def _to_datetime(value) -> datetime:
+    """Accept a datetime or an ISO-8601 string and return a datetime."""
+    if isinstance(value, datetime):
+        return value
+    return datetime.fromisoformat(value)
+
+
+def _event_start(event: dict) -> datetime:
+    if event.get("start_datetime"):
+        return datetime.fromisoformat(event["start_datetime"])
+    return datetime(event["year"], event["month"], event["day"])
+
+
+def _event_end(event: dict) -> datetime:
+    if event.get("end_datetime"):
+        return datetime.fromisoformat(event["end_datetime"])
+    start = _event_start(event)
+    return start.replace(hour=23, minute=59, second=59)
+
+
+class CalendarTools:
+    """Calendar-domain tools bound to a single data source."""
+
+    def __init__(self, source: CalendarDataSource | None = None) -> None:
+        self._source = source if source is not None else FixtureDataSource()
+
+    def _contacts_by_id(self) -> dict:
+        return {c["contact_id"]: c for c in self._source.get_contacts()}
+
+    def get_events(self, range_start, range_end) -> list[dict]:
+        """Events whose time overlaps [range_start, range_end], sorted by start."""
+        start = _to_datetime(range_start)
+        end = _to_datetime(range_end)
+        events = [
+            event
+            for event in self._source.get_events()
+            if _event_start(event) <= end and _event_end(event) >= start
+        ]
+        return sorted(events, key=_event_start)
+
+    def get_events_today(self, today=None) -> list[dict]:
+        """Events on a given day (defaults to the real current date)."""
+        day = today if today is not None else date.today()
+        if isinstance(day, str):
+            day = date.fromisoformat(day)
+        start = datetime(day.year, day.month, day.day, 0, 0, 0)
+        end = datetime(day.year, day.month, day.day, 23, 59, 59)
+        return self.get_events(start, end)
+
+    def get_event_attendees(self, event_id) -> list[dict]:
+        """Contacts linked to an event, each annotated with its role."""
+        contacts_by_id = self._contacts_by_id()
+        attendees = []
+        for link in self._source.get_event_contacts():
+            if link["event_id"] == event_id:
+                contact = contacts_by_id.get(link["contact_id"])
+                if contact is not None:
+                    attendees.append({**contact, "role": link.get("role")})
+        return attendees
+
+    def get_people_i_will_meet(self, range_start, range_end) -> list[dict]:
+        """Distinct contacts attending any event in the range."""
+        event_ids = {event["event_id"] for event in self.get_events(range_start, range_end)}
+        contacts_by_id = self._contacts_by_id()
+        met: dict = {}
+        for link in self._source.get_event_contacts():
+            contact_id = link["contact_id"]
+            if link["event_id"] in event_ids and contact_id not in met:
+                contact = contacts_by_id.get(contact_id)
+                if contact is not None:
+                    met[contact_id] = contact
+        return list(met.values())
+
+    def get_face_to_face_events(self, range_start, range_end) -> list[dict]:
+        """In-person events in the range."""
+        return [
+            event
+            for event in self.get_events(range_start, range_end)
+            if event.get("location_type") == "in_person"
+        ]
+
+    def get_remote_events(self, range_start, range_end) -> list[dict]:
+        """Remote events in the range."""
+        return [
+            event
+            for event in self.get_events(range_start, range_end)
+            if event.get("location_type") == "remote"
+        ]
+
+    def get_contacts_in_group(self, group_name) -> list[dict]:
+        """Contacts belonging to a named group (e.g. 2Call1, 2Contact2)."""
+        contacts_by_id = self._contacts_by_id()
+        members = []
+        for membership in self._source.get_group_memberships():
+            if membership["group_name"] == group_name:
+                contact = contacts_by_id.get(membership["contact_id"])
+                if contact is not None:
+                    members.append(contact)
+        return members
+
+    def get_meeting_followups(self, event_id) -> list[dict]:
+        """People to follow up with after an event (its linked contacts + roles).
+
+        Same linkage as get_event_attendees, exposed under a follow-up name so
+        the agent can answer "who should I follow up with from meeting X".
+        """
+        return self.get_event_attendees(event_id)

compass_local-0.0.1/compass_local/src/calendaring/event_profile_data_source.py

@@ -0,0 +1,118 @@
+"""Database-backed Compass calendar data source (the real adapter).
+
+Turns the normalized circlez data model into the SAME flat rows the
+deterministic tools already consume, so the tools and their tests never change.
+
+All the join / flatten / role / datetime logic lives here as pure Python over the
+narrow ``CalendarReader`` port (calendar_reader.py), so it is fully unit-testable
+without a database. The concrete port that talks to the real circlez packages
+lives in generic_crud_calendar_reader.py and is import-isolated there, because
+those classes open a MySQL connection at construction time and are not importable
+in a DB-free test environment.
+
+The attendee chain (confirmed against the provided SQL views) is:
+    event_profile_table (event_id, to_registered_profile_id, is_* flags)
+      -> contact_profile_table (profile_id -> contact_id)
+        -> contact_table  [= the attendee]
+Groups: contact_group_table (contact_id, group_id) -> group name (title).
+"""
+
+from datetime import date, datetime
+
+from calendaring.calendar_data_source import CalendarDataSource
+from calendaring.calendar_reader import CalendarReader
+
+# event_profile is_* flags mapped to a calendar-standard role, in precedence
+# order; the first truthy flag wins. The vocabulary matches Google Calendar's
+# responseStatus / iCalendar PARTSTAT, extended with organizer and checked_in,
+# and is the same set the sample data uses. Roles describe attendance STATE --
+# the axis the real schema supports; there is no lecturer/exhibitor flag.
+_ROLE_BY_FLAG = (
+    ("is_admin", "organizer"),
+    ("is_checked_in", "checked_in"),
+    ("is_will_arrive", "accepted"),
+    ("is_tentative", "tentative"),
+    ("is_will_not_arrive", "declined"),
+    ("is_not_interested", "declined"),
+    ("is_invited", "needs_action"),
+)
+_DEFAULT_ROLE = "needs_action"
+
+
+def _role_from_event_profile(event_profile: dict) -> str:
+    """Derive a role string from the event_profile state flags."""
+    for flag, role in _ROLE_BY_FLAG:
+        if event_profile.get(flag):
+            return role
+    return _DEFAULT_ROLE
+
+
+def _as_iso(value):
+    """Render a datetime/date as an ISO-8601 string; pass other values through.
+
+    The tools read start/end via ``datetime.fromisoformat`` on a string, so DB
+    DATETIME values (returned as datetime objects) must be stringified here to
+    keep the tools unchanged."""
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    return value
+
+
+class EventProfileDataSource(CalendarDataSource):
+    """CalendarDataSource backed by the normalized circlez model, reached through
+    a CalendarReader. Emits the same flat rows as FixtureDataSource."""
+
+    def __init__(self, reader: CalendarReader) -> None:
+        self._reader = reader
+
+    def get_events(self) -> list[dict]:
+        events = []
+        for row in self._reader.fetch_events():
+            event = dict(row)
+            if "start_datetime" in event:
+                event["start_datetime"] = _as_iso(event["start_datetime"])
+            if "end_datetime" in event:
+                event["end_datetime"] = _as_iso(event["end_datetime"])
+            events.append(event)
+        return events
+
+    def get_contacts(self) -> list[dict]:
+        return [dict(row) for row in self._reader.fetch_contacts()]
+
+    def get_event_contacts(self) -> list[dict]:
+        # profile_id -> contact_id (first mapping wins if a profile maps to more
+        # than one contact; the calendar view treats a registered profile as one
+        # person).
+        contact_id_by_profile_id: dict = {}
+        for row in self._reader.fetch_contact_profiles():
+            profile_id = row.get("profile_id")
+            contact_id = row.get("contact_id")
+            if profile_id is not None and contact_id is not None:
+                contact_id_by_profile_id.setdefault(profile_id, contact_id)
+
+        links = []
+        seen = set()
+        for event_profile in self._reader.fetch_event_profiles():
+            event_id = event_profile.get("event_id")
+            profile_id = event_profile.get("to_registered_profile_id")
+            contact_id = contact_id_by_profile_id.get(profile_id)
+            if contact_id is None:
+                # Registered profile with no linked contact -> not an attendee we
+                # can name; skip it.
+                continue
+            key = (event_id, contact_id)
+            if key in seen:
+                continue
+            seen.add(key)
+            links.append({
+                "event_id": event_id,
+                "contact_id": contact_id,
+                "role": _role_from_event_profile(event_profile),
+            })
+        return links
+
+    def get_group_memberships(self) -> list[dict]:
+        return [
+            {"contact_id": row["contact_id"], "group_name": row["group_name"]}
+            for row in self._reader.fetch_contact_group_memberships()
+        ]