cyborg-data

Organizational data access library with O(1) lookups for employee, team, organization, pillar, and team group queries.

Available in Go and Python with identical APIs.

Quick Start

Go

go get github.com/openshift-eng/cyborg-data/go

import orgdatacore "github.com/openshift-eng/cyborg-data/go"

service := orgdatacore.NewService()
// Load from GCS or custom data source
employee := service.GetEmployeeByUID("user123")

See go/README.md for full documentation.

Python

pip install -e .
# With GCS support:
pip install -e ".[gcs]"

from orgdatacore import Service

service = Service()
# Load from GCS or custom data source
employee = service.get_employee_by_uid("user123")

See python/README.md for full documentation.

Repository Structure

cyborg-data/
├── go/                     # Go implementation
│   ├── service.go          # Core service
│   ├── types.go            # Data structures
│   ├── example/            # Examples
│   └── README.md
│
├── python/                 # Python implementation
│   ├── orgdatacore/        # Package source
│   ├── tests/
│   └── README.md
│
├── testdata/               # Shared test fixtures
└── Makefile                # Build orchestration

Architecture

All organizational relationships are pre-computed during indexing. No tree traversals at query time.

Data Source (GCS) → LoadFromDataSource() → In-memory indexes → O(1) queries

Performance

Operation	Complexity
GetEmployeeByUID	O(1)
GetEmployeeBySlackID	O(1)
GetEmployeeByGitHubID	O(1)
GetTeamsForUID	O(1)
IsEmployeeInTeam	O(n) where n = user's teams
GetEmployeeByEmail	O(n) where n = employees

Build Commands

# Test both implementations
make test

# Lint both
make lint

# Build both
make build

Go

cd go
make test              # Run tests
make test-with-gcs     # With GCS support
make examples          # Build examples
make bench             # Benchmarks

Python

cd python
pytest                          # Run tests
pytest --cov=orgdatacore        # With coverage
ruff check .                    # Lint
ruff format .                   # Format

API

Both implementations provide identical interfaces:

Employee Queries

• GetEmployeeByUID(uid) / get_employee_by_uid(uid)
• GetEmployeeBySlackID(slackID) / get_employee_by_slack_id(slack_id)
• GetEmployeeByGitHubID(githubID) / get_employee_by_github_id(github_id)
• GetManagerForEmployee(uid) / get_manager_for_employee(uid)

Entity Queries

• GetTeamByName(name) / get_team_by_name(name)
• GetOrgByName(name) / get_org_by_name(name)
• GetPillarByName(name) / get_pillar_by_name(name)
• GetTeamGroupByName(name) / get_team_group_by_name(name)

Membership Queries

• GetTeamsForUID(uid) / get_teams_for_uid(uid)
• GetTeamMembers(teamName) / get_team_members(team_name)
• IsEmployeeInTeam(uid, teamName) / is_employee_in_team(uid, team_name)
• IsEmployeeInOrg(uid, orgName) / is_employee_in_org(uid, org_name)
• GetUserOrganizations(slackUserID) / get_user_organizations(slack_user_id)

Enumeration

• GetAllEmployeeUIDs() / get_all_employee_uids()
• GetAllTeamNames() / get_all_team_names()
• GetAllOrgNames() / get_all_org_names()
• GetAllPillarNames() / get_all_pillar_names()
• GetAllTeamGroupNames() / get_all_team_group_names()

Data Sources

GCS (Google Cloud Storage)

• Go: Build with -tags gcs
• Python: Install with pip install -e ".[gcs]"
• Supports hot-reload via Watch()

Custom Sources

Implement the DataSource interface for other backends (S3, Azure, HTTP, etc.).

Data Format

JSON format generated by Python orglib in the cyborg project:

{
  "metadata": { "generated_at": "...", "total_employees": 100 },
  "lookups": {
    "employees": { "uid": { ... } },
    "teams": { "team_name": { ... } },
    "orgs": { "org_name": { ... } },
    "pillars": { "pillar_name": { ... } },
    "team_groups": { "team_group_name": { ... } }
  },
  "indexes": {
    "membership": { ... },
    "slack_id_mappings": { ... },
    "github_id_mappings": { ... }
  }
}

Contributing

When adding features, update both Go and Python implementations to maintain API parity.

• Go documentation
• Python documentation
• CLAUDE.md - AI assistant guidance

License

Apache 2.0