refactor: restructure the agent package and add contributor docs #20

Merged

Jc-965 merged 20 commits from repo-restructure into main 2026-09-26 18:22:09 +00:00

Conversation 2 Commits 20 Files changed 53 +2990 -2328

Jc-965 commented 2026-09-18 21:55:25 +00:00

Member

Copy link

Summary

This pull request restructures the agent repository. The code moved from a flat agent/ directory into a src/cmugpt package, with large modules split by responsibility, configuration centralized, and tests moved to pytest. The production startup check, which had never been active, is now turned on. Comments, docstrings, and the README have been rewritten, and the repository now has a contributing guide and PR template. The service behaves the same as before. Closes #21.

Changes

Package layout

• The code is now a src/cmugpt package installed as cmugpt-agent, with the entry point defined in pyproject.toml.
• The 1,000-line memory module becomes a memory/ package with separate modules for the store, facts, the remember and forget tools, background extraction, and management routes.
• The map code becomes a maps/ package, and buildings.json moves inside it so the built wheel ships the catalog.
• The HTTP layer becomes an api/ package, with the app assembly in server.py, the shared bearer-token and body-size checks in deps.py, and one router per route group.
• Per-turn tool and memory selection is split out of graph.py into planning.py. A new llm.py builds the OpenRouter clients in one place and caches them per configuration.
• The package init is empty, so importing one module no longer loads the whole agent.

Configuration

• All environment variables are read through settings.py, which uses pydantic-settings and builds a fresh object per call so tests can override values per case.
• The prod secretspec profile now sets AGENT_ENV=production. The startup check for DATABASE_URL and a 32-character AGENT_SHARED_SECRET was already in the code but never ran.
• The default local port is 5055, which avoids the AirPlay conflict on macOS. Kennel injects its own port in production.
• A .env.example documents every variable with its default.

Tests

• The unit tests move from ci_test/ to tests/unit/ and run under pytest with asyncio in auto mode. CI runs them with a single uv run pytest.
• The live end-to-end checks move from tools/ to evals/ as pytest tests. They skip themselves when the API keys are absent and fail on a miss instead of printing a report.

Cleanup

• The Procfile is removed, since Kennel never read it, along with a duplicate output name in flake.nix and a dangling pre-commit symlink.
• The unused mcp, openai, and pre-commit dependencies are removed. Both libraries still arrive through the LangChain packages.
• Two uncalled functions, a duplicated constant, three one-line settings wrappers, and four unused package exports are removed.

Code quality

• Every function signature is annotated, and helpers used only inside their module are underscore-prefixed.
• ruff now runs the pep8-naming rules and the PEP 257 docstring form checks, and the code passes both. DailyTokenLimitExceeded is renamed to DailyTokenLimitError.
• Comments and docstrings across the package are rewritten to state contracts and reasons rather than narrate the code.

Documentation

• The README is rewritten to cover the structure of the codebase and development process.
• CONTRIBUTING.md covers the workflow, code style, commit conventions, and the pull request process.
• AI tool state directories are gitignored.

AI use

• None
• Minor: autocomplete or suggestions for a few lines
• Some: AI drafted parts of the change, the rest was written by hand
• Most: AI wrote the bulk of the change, edited by hand
• All: AI wrote the whole change, reviewed and tested by hand

Checklist

• DATABASE_URL="" uv run pytest passes
• uv run pytest evals run, if prompts or tool selection changed (prompts unchanged; the two smoke evals were run and pass)
• Hooks pass (ruff and ty directly; devenv unavailable locally)
• README updated if a variable, route, or command changed
• No secrets, keys, or .env values in the diff
• Commits follow Conventional Commits, one change each, rebased onto main
• Title written like a commit subject

## Summary This pull request restructures the agent repository. The code moved from a flat `agent/` directory into a `src/cmugpt` package, with large modules split by responsibility, configuration centralized, and tests moved to pytest. The production startup check, which had never been active, is now turned on. Comments, docstrings, and the README have been rewritten, and the repository now has a contributing guide and PR template. The service behaves the same as before. Closes #21. ## Changes Package layout - The code is now a `src/cmugpt` package installed as `cmugpt-agent`, with the entry point defined in `pyproject.toml`. - The 1,000-line memory module becomes a `memory/` package with separate modules for the store, facts, the remember and forget tools, background extraction, and management routes. - The map code becomes a `maps/` package, and `buildings.json` moves inside it so the built wheel ships the catalog. - The HTTP layer becomes an `api/` package, with the app assembly in `server.py`, the shared bearer-token and body-size checks in `deps.py`, and one router per route group. - Per-turn tool and memory selection is split out of `graph.py` into `planning.py`. A new `llm.py` builds the OpenRouter clients in one place and caches them per configuration. - The package init is empty, so importing one module no longer loads the whole agent. Configuration - All environment variables are read through `settings.py`, which uses pydantic-settings and builds a fresh object per call so tests can override values per case. - The `prod` secretspec profile now sets `AGENT_ENV=production`. The startup check for `DATABASE_URL` and a 32-character `AGENT_SHARED_SECRET` was already in the code but never ran. - The default local port is 5055, which avoids the AirPlay conflict on macOS. Kennel injects its own port in production. - A `.env.example` documents every variable with its default. Tests - The unit tests move from `ci_test/` to `tests/unit/` and run under pytest with asyncio in auto mode. CI runs them with a single `uv run pytest`. - The live end-to-end checks move from `tools/` to `evals/` as pytest tests. They skip themselves when the API keys are absent and fail on a miss instead of printing a report. Cleanup - The Procfile is removed, since Kennel never read it, along with a duplicate output name in `flake.nix` and a dangling pre-commit symlink. - The unused `mcp`, `openai`, and `pre-commit` dependencies are removed. Both libraries still arrive through the LangChain packages. - Two uncalled functions, a duplicated constant, three one-line settings wrappers, and four unused package exports are removed. Code quality - Every function signature is annotated, and helpers used only inside their module are underscore-prefixed. - ruff now runs the pep8-naming rules and the PEP 257 docstring form checks, and the code passes both. `DailyTokenLimitExceeded` is renamed to `DailyTokenLimitError`. - Comments and docstrings across the package are rewritten to state contracts and reasons rather than narrate the code. Documentation - The README is rewritten to cover the structure of the codebase and development process. - `CONTRIBUTING.md` covers the workflow, code style, commit conventions, and the pull request process. - AI tool state directories are gitignored. ## AI use - [ ] None - [ ] Minor: autocomplete or suggestions for a few lines - [ ] Some: AI drafted parts of the change, the rest was written by hand - [x] Most: AI wrote the bulk of the change, edited by hand - [ ] All: AI wrote the whole change, reviewed and tested by hand ## Checklist - [x] `DATABASE_URL="" uv run pytest` passes - [x] `uv run pytest evals` run, if prompts or tool selection changed (prompts unchanged; the two smoke evals were run and pass) - [x] Hooks pass (ruff and ty directly; devenv unavailable locally) - [x] README updated if a variable, route, or command changed - [x] No secrets, keys, or `.env` values in the diff - [x] Commits follow Conventional Commits, one change each, rebased onto `main` - [x] Title written like a commit subject

Jc-965 added 18 commits 2026-09-18 21:55:25 +00:00

chore: move the agent into a src/cmugpt package c3048d17dc

chore: ignore pytest cache and untrack devenv pre-commit link bc70d9d620

docs: rewrite code comments 1fb08914fa

refactor: read all configuration through settings.py 56b3562262

refactor: split api into routers and shared deps fd69464fbb

test: add live evals folder 983322b5ae

docs: rewrite readme and comments/docstrings 89eacdd800

docs: add local setup process info, link mcp-server, redraw overview 76dbe58732

fix: turn on the production startup check b47e8575ff

chore: use port 5055 for local runs 3804753b38

chore: remove the Procfile and duplicate flake output 63e8be1ebf

build: remove unused dependencies 7cc4cb3034

refactor: keep the package init empty e4fee5c559

refactor: remove dead code and duplicate helpers 45614694b7

test: rename the maps test file d8c4d4b490

refactor: annotate graph nodes and hide module-private helpers 2feec5e425

style: follow PEP 257 docstrings and PEP 8 naming e728113a5d

docs: add contributing guide and rewrite readme a0d21edd81

Jc-965 added 1 commit 2026-09-18 22:10:00 +00:00

build: upgrade anyio to 4.14.2 for security advisories f0d87dbd94

krishsax commented 2026-09-19 18:34:01 +00:00

Member

Copy link

@thesuperRL Why is this issue happening? Is it because @Jc-965 doesn't have the right permissions? Grafana isn't very informative, would like to know what the cause is.

CC: @jiyas

@thesuperRL Why is this issue happening? Is it because @Jc-965 doesn't have the right permissions? Grafana isn't very informative, would like to know what the cause is. CC: @jiyas

thesuperRL commented 2026-09-19 18:38:56 +00:00

Owner

Copy link

@krishsax wrote in #20 (comment):

@thesuperRL Why is this issue happening? Is it because @Jc-965 doesn't have the right permissions? Grafana isn't very informative, would like to know what the cause is.

CC: @jiyas

It's a postgres issue I've seen a couple of times, just that you don't have correct perms on the relevant kennel job for some reason. I'll take a look during work session.

lowk thought i resolved it but i guess not

@krishsax wrote in https://git.cmu.dev/ScottyLabs/cmugpt-agent/pulls/20#issuecomment-11342: > @thesuperRL Why is this issue happening? Is it because @Jc-965 doesn't have the right permissions? Grafana isn't very informative, would like to know what the cause is. > > CC: @jiyas It's a postgres issue I've seen a couple of times, just that you don't have correct perms on the relevant kennel job for some reason. I'll take a look during work session. lowk thought i resolved it but i guess not

krishsax added a new dependency 2026-09-19 18:42:31 +00:00

#21 Refactoring Agent

krishsax removed a dependency 2026-09-19 18:44:20 +00:00

#21 Refactoring Agent

krishsax referenced this pull request 2026-09-19 19:01:37 +00:00

Refactoring Agent #21

krishsax added 1 commit 2026-09-26 17:44:44 +00:00

docs: setting up devenv 0db8cb3380

Jc-965 merged commit eb77a23158 into main 2026-09-26 18:22:09 +00:00

Jc-965 referenced this pull request from a commit 2026-09-26 18:22:10 +00:00

Merge pull request 'refactor: restructure the agent package and add contributor docs' (#20) from repo-restructure into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

  

needs/docs

Must have documentation written

  

needs/research

Discuss the ideal implementation with the tech lead

  

needs/upstream

Needs a contribution to an upstream project

  

type/bug

Something not working as intended

  

type/external

Lives outside of code

  

type/feature

New functionality

  

type/refactor

Improving existing code

  

urgency

high

This is currently causing issues

  

urgency

immediate

This is making a project or feature unusable

  

urgency

low

This can happen whenever

  

urgency

medium

This is expected to cause issues soon

No labels

needs/docs

needs/research

needs/upstream

type/bug

type/external

type/feature

type/refactor

urgency

high

urgency

immediate

urgency

low

urgency

medium

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

3 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

ScottyLabs/cmugpt-agent!20

No description provided.