|
|
|
|
@@ -0,0 +1,280 @@
|
|
|
|
|
# GENOME.md — timmy-config
|
|
|
|
|
|
|
|
|
|
Generated from target repo `Timmy_Foundation/timmy-config` at commit `04ecad3`.
|
|
|
|
|
This host-repo artifact lives in `timmy-home` so the meta backlog can track a repo-grounded genome without depending on the target repo checkout.
|
|
|
|
|
|
|
|
|
|
## Project Overview
|
|
|
|
|
|
|
|
|
|
`timmy-config` is Timmy's sovereign configuration sidecar. It is not the Hermes harness itself. It is the identity, doctrine, routing, deployment overlay, fleet glue, training recipes, and operational tooling that make the harness behave as Timmy.
|
|
|
|
|
|
|
|
|
|
Grounded facts from the analyzed checkout:
|
|
|
|
|
- target repo path analyzed: `/Users/apayne/code/timmy-config`
|
|
|
|
|
- target repo origin: `https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config.git`
|
|
|
|
|
- analyzed commit: `04ecad3`
|
|
|
|
|
- text files in the checkout: `607`
|
|
|
|
|
- Python LOC from a raw `find ... '*.py' | xargs wc -l`: `48,179`
|
|
|
|
|
- the target repo already ships its own `GENOME.md` on `main`
|
|
|
|
|
- the repo uses the sidecar pattern: `deploy.sh` overlays files into `~/.hermes/` and `~/.timmy/`
|
|
|
|
|
- the repo contains both older top-level sidecar surfaces and a newer `hermes-sovereign/` subtree
|
|
|
|
|
|
|
|
|
|
The repo is best understood as five overlapping layers:
|
|
|
|
|
1. identity and conscience (`SOUL.md`, `HEART.md`, memories, doctrine docs)
|
|
|
|
|
2. harness configuration (`config.yaml`, overlay files, skins, channels, fallback portfolios)
|
|
|
|
|
3. orchestration / fleet control (`orchestration.py`, `tasks.py`, `fleet/`, `scripts/`)
|
|
|
|
|
4. training / evaluation / adversary infrastructure (`training/`, `adversary/`, `evaluations/`, `pipelines/`)
|
|
|
|
|
5. emerging typed sidecar subsystems (`hermes-sovereign/`, especially `mempalace/` and `devkit/`)
|
|
|
|
|
|
|
|
|
|
This is not a tiny config repo anymore. It is a mixed control-plane repository containing shell deploy logic, Python automation, agent routing doctrine, adversary datasets, infrastructure playbooks, and embedded product evolution experiments.
|
|
|
|
|
|
|
|
|
|
## Architecture Diagram
|
|
|
|
|
|
|
|
|
|
```mermaid
|
|
|
|
|
graph TD
|
|
|
|
|
soul["Identity Layer\nSOUL.md\nHEART.md\nmemories/"]
|
|
|
|
|
overlay["Overlay Layer\ndeploy.sh\nconfig.yaml\nskins/\nplaybooks/\ncron/"]
|
|
|
|
|
orchestration["Control Plane\norchestration.py\ntasks.py\nfleet/\ngitea_client.py"]
|
|
|
|
|
scripts["Operational Scripts\nscripts/\nbin/"]
|
|
|
|
|
training["Training + Eval\ntraining/\nadversary/\nevaluations/\npipelines/"]
|
|
|
|
|
sidecar["Typed Sidecar Modules\nhermes-sovereign/\nmempalace/\ndevkit/"]
|
|
|
|
|
ansible["Infra Deployment\nansible/\ndeploy/\ninfra/"]
|
|
|
|
|
harness["Hermes Runtime\n~/.hermes/\n~/.timmy/"]
|
|
|
|
|
|
|
|
|
|
soul --> overlay
|
|
|
|
|
overlay --> harness
|
|
|
|
|
orchestration --> scripts
|
|
|
|
|
orchestration --> harness
|
|
|
|
|
scripts --> harness
|
|
|
|
|
training --> scripts
|
|
|
|
|
training --> orchestration
|
|
|
|
|
sidecar --> orchestration
|
|
|
|
|
sidecar --> overlay
|
|
|
|
|
ansible --> harness
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Entry Points and Data Flow
|
|
|
|
|
|
|
|
|
|
### Primary entry points
|
|
|
|
|
|
|
|
|
|
- `deploy.sh`
|
|
|
|
|
- canonical sidecar deployment path
|
|
|
|
|
- validates config, copies `SOUL.md` into `~/.timmy/`, and overlays config/playbooks/memories/skins/bin/cron into `~/.hermes/`
|
|
|
|
|
- `config.yaml`
|
|
|
|
|
- main Hermes runtime config consumed by the harness
|
|
|
|
|
- defines model/provider choices, auxiliary models, display, memory, approvals, security, and custom providers
|
|
|
|
|
- `orchestration.py`
|
|
|
|
|
- Huey + SQLite orchestration core
|
|
|
|
|
- defines scheduled pipeline tasks and token logging hooks
|
|
|
|
|
- `tasks.py`
|
|
|
|
|
- scheduled work surface using `huey.crontab`
|
|
|
|
|
- imports `GiteaClient`, metrics helpers, and Hermes local-run wrappers
|
|
|
|
|
- `gitea_client.py`
|
|
|
|
|
- typed zero-dependency Gitea API client used across automation flows
|
|
|
|
|
- `scripts/` and `bin/`
|
|
|
|
|
- operational entrypoints for validation, audits, fleet health, token tracking, PR triage, adversary harnesses, and generators
|
|
|
|
|
- `hermes-sovereign/`
|
|
|
|
|
- newer typed subsystem area, especially devkit, wizard bootstrap, and MemPalace integration
|
|
|
|
|
|
|
|
|
|
### Data flow
|
|
|
|
|
|
|
|
|
|
1. The operator edits `timmy-config` as source of truth.
|
|
|
|
|
2. `deploy.sh` validates and overlays config into `~/.hermes/` / `~/.timmy/`.
|
|
|
|
|
3. Hermes runtime loads `config.yaml`, skin, playbooks, memories, and sidecar scripts.
|
|
|
|
|
4. Scheduled control-plane work runs through `orchestration.py` and `tasks.py`.
|
|
|
|
|
5. Task code uses helpers like `gitea_client.py`, `metrics_helpers.py`, and `scripts/*` modules to inspect or mutate repo/fleet state.
|
|
|
|
|
6. Training and adversary surfaces in `training/`, `adversary/`, and `evaluations/` generate or validate datasets and evaluation outputs.
|
|
|
|
|
7. Ansible / deploy / infra surfaces bridge the config repo into VPS and fleet deployment workflows.
|
|
|
|
|
|
|
|
|
|
### Repo boundary data flow
|
|
|
|
|
|
|
|
|
|
The README encodes an important boundary:
|
|
|
|
|
- `timmy-config` owns identity, configuration, routing doctrine, playbooks, and harness-side glue
|
|
|
|
|
- `timmy-home` owns lived work, notes, gameplay, research, trajectories, metrics, and produced artifacts
|
|
|
|
|
|
|
|
|
|
That boundary is central to the repo's architecture. Many files only make sense when read as “how Timmy is hosted,” not “what Timmy did.”
|
|
|
|
|
|
|
|
|
|
## Key Abstractions
|
|
|
|
|
|
|
|
|
|
### Sidecar pattern
|
|
|
|
|
|
|
|
|
|
The dominant abstraction is the sidecar. `timmy-config` does not fork `hermes-agent`; it overlays the harness. `deploy.sh` is the concrete mechanism. The repo's purpose is to customize runtime behavior without carrying the main harness source as its own project.
|
|
|
|
|
|
|
|
|
|
### Typed Gitea client
|
|
|
|
|
|
|
|
|
|
`gitea_client.py` replaces ad-hoc curl usage with typed dataclasses:
|
|
|
|
|
- `User`
|
|
|
|
|
- `Label`
|
|
|
|
|
- `Issue`
|
|
|
|
|
- `Comment`
|
|
|
|
|
- `PullRequest`
|
|
|
|
|
- `PRFile`
|
|
|
|
|
- `GiteaClient`
|
|
|
|
|
|
|
|
|
|
This is one of the repo's cleanest abstractions: a sovereign stdlib-only API client that the automation layer can import anywhere.
|
|
|
|
|
|
|
|
|
|
### Huey orchestration core
|
|
|
|
|
|
|
|
|
|
`orchestration.py` defines a `SqliteHuey` queue living in `~/.hermes/orchestration.db`, plus token logging and task wrappers like:
|
|
|
|
|
- `playground_factory_task`
|
|
|
|
|
- `training_factory_task`
|
|
|
|
|
- `knowledge_mine_task`
|
|
|
|
|
- `adversary_task`
|
|
|
|
|
- `codebase_genome_task`
|
|
|
|
|
|
|
|
|
|
`tasks.py` is the scheduled-work counterpart. Together they form the repo's actual control plane.
|
|
|
|
|
|
|
|
|
|
### Config overlay / validation
|
|
|
|
|
|
|
|
|
|
`config_overlay.py` and the validator scripts (`scripts/config_validator.py`, `bin/validate_config.py`, related tests) express another strong abstraction: config as layered overlays with validation-before-deploy.
|
|
|
|
|
|
|
|
|
|
### Sovereign memory bridge
|
|
|
|
|
|
|
|
|
|
The `hermes-sovereign/mempalace/` subtree is a real subsystem, not a stray experiment. It includes:
|
|
|
|
|
- `mempalace.py`
|
|
|
|
|
- `retrieval_enforcer.py`
|
|
|
|
|
- `scratchpad.py`
|
|
|
|
|
- `wakeup.py`
|
|
|
|
|
- `sovereign_store.py`
|
|
|
|
|
- a dedicated tests subtree
|
|
|
|
|
|
|
|
|
|
This is the repo's strongest sign that `timmy-config` evolved from “just config” into a sidecar product with typed internal modules.
|
|
|
|
|
|
|
|
|
|
### Training / adversary substrate
|
|
|
|
|
|
|
|
|
|
The training surface is split across:
|
|
|
|
|
- `training/`
|
|
|
|
|
- `adversary/`
|
|
|
|
|
- `evaluations/`
|
|
|
|
|
- `pipelines/`
|
|
|
|
|
- many generator/validator scripts in `scripts/`
|
|
|
|
|
|
|
|
|
|
This area is not one polished abstraction; it is a substrate of evolving dataset, evaluation, and safety-guard tooling.
|
|
|
|
|
|
|
|
|
|
## API Surface
|
|
|
|
|
|
|
|
|
|
### Shell / CLI surfaces
|
|
|
|
|
|
|
|
|
|
- `./deploy.sh`
|
|
|
|
|
- `python3 gitea_client.py` patterns through importing `GiteaClient`
|
|
|
|
|
- `python3 orchestration.py` / `python3 tasks.py` style orchestration entry
|
|
|
|
|
- `python3 scripts/...`
|
|
|
|
|
- `python3 bin/...`
|
|
|
|
|
- `python3 pipelines/...`
|
|
|
|
|
- Ansible entrypoints under `ansible/`
|
|
|
|
|
|
|
|
|
|
### Important import surfaces
|
|
|
|
|
|
|
|
|
|
- `gitea_client.GiteaClient`
|
|
|
|
|
- `orchestration.huey`
|
|
|
|
|
- `tasks.*` scheduled jobs
|
|
|
|
|
- `config_overlay.load_config(...)`
|
|
|
|
|
- `metrics_helpers.build_local_metric_record(...)`
|
|
|
|
|
- `hermes-sovereign.mempalace.*`
|
|
|
|
|
|
|
|
|
|
### Consumed configuration surfaces
|
|
|
|
|
|
|
|
|
|
- `config.yaml`
|
|
|
|
|
- `config.dev.yaml`
|
|
|
|
|
- `fallback-portfolios.yaml`
|
|
|
|
|
- `channel_directory.json`
|
|
|
|
|
- YAML under `playbooks/`
|
|
|
|
|
- cron definitions under `cron/`
|
|
|
|
|
|
|
|
|
|
### Infrastructure surfaces
|
|
|
|
|
|
|
|
|
|
- `ansible/`
|
|
|
|
|
- `deploy/`
|
|
|
|
|
- `infra/`
|
|
|
|
|
- `fleet/`
|
|
|
|
|
|
|
|
|
|
## Test Coverage Gaps
|
|
|
|
|
|
|
|
|
|
### Observed current test health
|
|
|
|
|
|
|
|
|
|
On analyzed commit `04ecad3`, running `python3 -m pytest -q` in the target repo did not collect cleanly. I filed:
|
|
|
|
|
- `timmy-config#823` — `[tests] Restore pytest collection on main — 7 collection errors`
|
|
|
|
|
|
|
|
|
|
Reproduced collection failures:
|
|
|
|
|
- `scripts/adversary_schema.py` — unterminated string literal
|
|
|
|
|
- `scripts/config_validate.py` — unmatched `)`
|
|
|
|
|
- `bin/glitch_patterns.py` — missing `THREEJS_CATEGORIES` export expected by tests
|
|
|
|
|
- `adversary/harm_facilitation_adversary.py` — unterminated f-string
|
|
|
|
|
- `scripts/pr_triage.py` — unterminated f-string
|
|
|
|
|
- `validate_scene_data` import path mismatch for `tests/test_validate_scene_data.py`
|
|
|
|
|
- `training/training_pair_provenance.py` missing the `ProvenanceTracker` symbol expected by `training/test_training_pair_provenance.py`
|
|
|
|
|
|
|
|
|
|
### Coverage strengths
|
|
|
|
|
|
|
|
|
|
Despite the collection breakage, the repo clearly has a broad intended test surface:
|
|
|
|
|
- top-level `tests/` is substantial
|
|
|
|
|
- `training/tests/` exists
|
|
|
|
|
- `pipelines/tests/` exists
|
|
|
|
|
- `hermes-sovereign/mempalace/tests/` exists
|
|
|
|
|
- many major subsystems have named tests (`gitea_client`, config drift, orchestration, token tracking, adversary harnesses, etc.)
|
|
|
|
|
|
|
|
|
|
### High-value gaps / weak seams
|
|
|
|
|
|
|
|
|
|
- collection is broken on `main`, so true effective coverage is lower than the test tree suggests
|
|
|
|
|
- shell deploy behavior in `deploy.sh` is still an operationally critical seam with relatively weak contract coverage compared to Python subsystems
|
|
|
|
|
- the training / adversary script layer appears especially fragile because several current collection failures live there
|
|
|
|
|
- repo drift between older top-level scripts and newer `hermes-sovereign/` equivalents suggests duplicated or partially superseded logic risk
|
|
|
|
|
|
|
|
|
|
## Security Considerations
|
|
|
|
|
|
|
|
|
|
### Sidecar trust boundary
|
|
|
|
|
|
|
|
|
|
`deploy.sh` writes directly into `~/.hermes/` and `~/.timmy/`. That is the core trust boundary. If the overlay is wrong, Timmy's live runtime is wrong.
|
|
|
|
|
|
|
|
|
|
### Conscience / identity integrity
|
|
|
|
|
|
|
|
|
|
`SOUL.md` and `HEART.md` are not ordinary docs. They are the repo's identity anchor. Any tampering here changes the hosted agent's conscience and persona.
|
|
|
|
|
|
|
|
|
|
### Provider / endpoint drift
|
|
|
|
|
|
|
|
|
|
Current `config.yaml` still contains:
|
|
|
|
|
- `model.default: claude-opus-4-6`
|
|
|
|
|
- `provider: anthropic`
|
|
|
|
|
- many `http://localhost:11434/v1` auxiliary endpoints
|
|
|
|
|
|
|
|
|
|
This is not a secret leak, but it is operationally sensitive. It exposes routing assumptions, provider drift, and localhost-specific deployment expectations.
|
|
|
|
|
|
|
|
|
|
### Hardcoded infrastructure defaults
|
|
|
|
|
|
|
|
|
|
`gitea_client.py` defaults to `http://143.198.27.163:3000` if `GITEA_URL` is unset. That is an especially clear example of stale operational state embedded in code.
|
|
|
|
|
|
|
|
|
|
### Training / adversary content
|
|
|
|
|
|
|
|
|
|
The repo contains adversary and crisis-eval data generation code. This is valuable safety infrastructure, but it is also a high-risk mutation surface because subtle formatting or syntax corruption can silently poison evaluation pipelines.
|
|
|
|
|
|
|
|
|
|
### Ansible / infrastructure exposure
|
|
|
|
|
|
|
|
|
|
`ansible/`, `deploy/`, and `infra/` encode host, topology, or service assumptions. Even when they contain no raw credentials, they are still sensitive operational maps.
|
|
|
|
|
|
|
|
|
|
## Performance Characteristics
|
|
|
|
|
|
|
|
|
|
### Scale signals
|
|
|
|
|
|
|
|
|
|
- roughly `48k` Python LOC in the analyzed checkout
|
|
|
|
|
- many one-off scripts plus several large coordinator modules
|
|
|
|
|
- mixed repository roles increase cognitive load and maintenance cost
|
|
|
|
|
|
|
|
|
|
### Likely hotspots
|
|
|
|
|
|
|
|
|
|
- `tasks.py` is large and central to runtime scheduling
|
|
|
|
|
- `orchestration.py` is central to pipeline dispatch and token logging
|
|
|
|
|
- `gitea_client.py` is foundational and widely reused
|
|
|
|
|
- `scripts/` contains a long tail of single-purpose tools that are individually small but collectively expensive to reason about
|
|
|
|
|
- `hermes-sovereign/` introduces a second architectural center that is cleaner than the legacy script sprawl, but coexistence increases duplication pressure
|
|
|
|
|
|
|
|
|
|
### Human performance bottleneck
|
|
|
|
|
|
|
|
|
|
The main performance problem is architectural sprawl, not CPU. The repo contains identity docs, shell overlay logic, Python automation, training tools, evaluation corpora, infra playbooks, and typed sidecar modules in one place. That makes repo-wide truth expensive to maintain.
|
|
|
|
|
|
|
|
|
|
## Key Findings to Preserve
|
|
|
|
|
|
|
|
|
|
- `timmy-config` already ships its own `GENOME.md` on target `main`
|
|
|
|
|
- the repo is a sidecar overlay, not a fork of Hermes
|
|
|
|
|
- `deploy.sh`, `config.yaml`, `gitea_client.py`, `orchestration.py`, and `tasks.py` are the clearest canonical control-plane surfaces
|
|
|
|
|
- the README's boundary between `timmy-config` and `timmy-home` is architecturally important and should remain explicit
|
|
|
|
|
- `python3 -m pytest -q` on analyzed `main` currently stops at 7 collection errors; filed `timmy-config#823`
|
|
|
|
|
- `config.yaml` still encodes provider / localhost drift that deserves human review
|
|
|
|
|
- `gitea_client.py` still defaults to a stale raw-IP base URL
|
