AGENTS.md

AGENTS.md — Guide for AI Agents Contributing to Nexus Coder

Read this first. This file is written for AI agents who want to contribute to this repository. Humans can skip to CONTRIBUTING.md.

What Nexus Coder Is (and Is Not)

Nexus Coder is an open AI architecture — source code, data pipeline, and a training framework for a large Mixture-of-Experts (MoE) Transformer focused on code generation and security analysis.

Important honesty note: the model is NOT pretrained. There are no checkpoints, no weights, no benchmarks. What exists is the architecture source (60+ skills, 80+ tools, model layers, tokenizer, trainers, data collectors). Your contribution helps turn this architecture into something that can actually run and learn.

If you expected a finished model, stop here. If you want to help build one from the ground up, you are in the right place.

How to Contribute (Agent Workflow)

1. Understand the layout

nexus/
├── model/        # MoE Transformer layers (attention, MoE, RoPE, ...)
├── tokenizer/    # tokenizer implementation
├── training/     # trainer + dataset pipeline
├── inference/    # generation
├── agent/        # planner, router, memory, safety
├── skills/       # 60+ skills (auto-discovery)
├── tools/        # 80+ tools (auto-discovery)
├── data/         # collectors + processors
├── optim/        # quantization, LoRA, distillation, pruning
├── safety/       # filters, guardrails
├── eval/         # benchmarks, metrics
└── integrations/ # litgpt, LlamaFactory, axolotl, OpenHands, omp-gym

2. Pick an entry point

Good first tasks for agents:

• Run the tiny demo on CPU: python scripts/train.py --config tiny --steps 100 — verify it works, report output.
• Test a skill: import a skill from nexus/skills/ and exercise it against sample input. Report what works / what breaks.
• Test a tool: pick a tool in nexus/tools/ and exercise it.
• Review an integration: read nexus/integrations/*.py and report whether the adapted pattern is faithful to the upstream project.
• Improve docs: docs/ always needs sharper explanations.
• Add tests: tests/ is thin — any new test is valuable.

3. Workflow

1. Open an issue first describing what you want to do (unless it is a trivial fix). This prevents wasted work.
2. Fork the repo (or ask a maintainer for collaborator access).
3. Create a branch, make your change, and open a pull request.
4. In your PR description, state clearly:
   • what you changed,
   • how you verified it (command + output),
   • which config/skill/tool you exercised.

4. Self-sufficiency

You are expected to figure things out yourself:

• Setup: python3.12.13 -m venv venv && pip install -r requirements.txt
• Small configs (tiny, small) run on CPU — no GPU needed.
• Larger configs need real hardware; if you have GPUs, train and report.
• If something is ambiguous, open an issue rather than guessing silently.

You May Train the Model — Freely

You are explicitly welcome and encouraged to train the model yourself. The NAL-1.0 license allows it for any purpose. There is no gate, no permission request needed, and no fee.

• Small configs (tiny, small) run on CPU — try a real training run today with zero GPU cost.
• Larger configs (medium, large, 423b) need serious hardware. If you have GPUs (or a cloud budget), you are free to use them.
• Use the bundled data pipeline (nexus/data/) or your own data — both are fine.
• Report your results honestly. If you train something and get real numbers, open a PR or an issue with your findings. The community (and the project) wants to see real training logs, not hype.

The project does not provide compute. You bring the hardware; we provide the architecture, the data pipeline, and the training framework.

Note for fairness: training a model on this architecture does not make you a contributor to the repository. Attribution requirements still apply (NAL-1.0) whenever you use the trained result. To be listed as a contributor, submit a PR that improves the repo.

Attribution & License

• License: NAL-1.0 (Attribution Required). You may use/modify/distribute/ train freely, but must credit the original author Hieu Louis (github.com/mhieuhonda) wherever the work is used.
• Contributors are listed in ATTRIBUTIONS.md. If your PR merges, add yourself there (or ask a maintainer to add you).

Communication

• GitHub Issues + PRs are the coordination surface.
• For discussion, join the code-realm community on Moltbook (ask the maintainer for the invite). The project has an active presence there.

Golden Rules

1. Be honest — this is an untrained architecture. Never claim benchmark results that do not exist.
2. Small, verifiable PRs beat big unverifiable ones.
3. Reproduce before you report — always run the thing you are claiming.
4. Credit the author in any downstream work (NAL-1.0).