Certifiedunder the Multi-Agent System module in the Mastering AI Agents program.
Program: Mastering AI Agents Certification — Multi-Agent System Capstone
Category: Technical Assets → Tool/App/Software
Author: Joram Kirubi
Code: https://github.com/joramkirubi/Publication-assistant
This project is a four-agent, LangGraph-orchestrated system that takes a GitHub repository URL and returns a concrete, actionable report: a better title and summary, relevant publication tags, and exactly which standard documentation sections are missing — checked against objective, rule-based criteria rather than a single LLM's opinion. It satisfies the Mastering AI Agents capstone requirements (minimum 3 agents, minimum 3 tools, orchestration framework) with margin: 4 agents, 4 tools, LangGraph.
This project builds a multi-agent system, Publication Assistant, that helps AI/ML practitioners prepare a GitHub repository for public sharing by automatically reviewing it against Ready Tensor's own documentation standards. Give it a repo URL; it returns a suggested title and summary, suggested publication tags, a checklist of missing documentation sections, and an overall recommendation — all synthesized into one markdown report.
The system uses 4 agents (Repo Analyzer, Metadata Recommender, Content Improver, Reviewer/Critic) coordinated by LangGraph, and integrates 4 tools (a GitHub API reader, a rule-based README structure checker, a keyword extractor, and a web search tool), exceeding the capstone's minimum requirements of 3 agents and 3 tools.
Most shared AI/ML repositories fall short of the documentation standards that would make them genuinely useful to others — missing installation steps, no license, titles that don't explain what the project actually does. Ready Tensor's own Open Source Repository Guide and Technical Evaluation Rubric lay out clear, objective criteria for what "good" looks like, but manually checking a repository against that checklist is tedious and easy to skip under deadline pressure.
This system automates that first pass. It applies the same Essential/Professional documentation criteria programmatically, so an author gets a concrete, prioritized list of what to fix in seconds — before investing time polishing the wrong thing, or nothing at all.
Four agents collaborate through a single shared state object, coordinated by a LangGraph graph with a deliberate fan-out/fan-in shape:
.svg?versionId=tIdzYON0tnpnrCQdpYfvdykJQxlxcIsc&Expires=1788094656&Key-Pair-Id=K3EVG0QTJR4SK0&Signature=RAtOwatEMRnEj5sabf3tKox7rNOPcAMEmyQZ9yjPUgwaJzSoubaCRgumpK1n9iYEWmqdVWABSPIUL3AiX5NZmdbjGfNEAtroLm6aCNbRxjcHVxIpuwA~8yY-AVu5SX-RyTHWOVy41SKGD17lvWecFHTCD~HG0rWXxhd9be-Vej2BJn1bMqphCW8ChtK1vdJCQf7jOhbNqmANu1i3m52AU7P1zrrNG~blSTs2uH-kM9CVjxBubxZ0l1--sUbRIa-nqPR3-ibjBZsn8S4dtG5kf0tEJzMvasYxtSygXHa1OlbJ6mDzOZexouEA-gNE6agEST8hNwRhDNRGIun1SWTNCg__)
| # | Agent | Role | Tool(s) used |
|---|---|---|---|
| 1 | Repo Analyzer | Fetches README text, file structure, and repo metadata (stars, license, language) | github_repo_reader |
| 2 | Metadata Recommender | Extracts candidate keywords, then uses an LLM to refine them into publication-quality tags | keyword_extractor |
| 3 | Content Improver | Searches the web for how similar projects are positioned, then drafts a grounded title/summary | web_search |
| 4 | Reviewer / Critic | Checks the README against Ready Tensor's Essential/Professional documentation tiers, synthesizes everything into one final report | readme_structure_checker |
Design decision — why parallel branches? Metadata Recommender and Content Improver don't depend on each other's output, so they run concurrently rather than in a strict chain, cutting end-to-end latency since both branches' LLM calls happen at the same time instead of sequentially.
Design decision — why a rule-based tool alongside LLM agents? The readme_structure_checker tool is deliberately deterministic (regex/heading matching against Ready Tensor's own documented Essential-tier criteria), not another LLM call. This gives the Reviewer agent an objective, reproducible signal to reason over, rather than compounding LLM opinion on LLM opinion.
The graph genuinely pauses before the Reviewer/Critic agent runs — using LangGraph's interrupt_before mechanism backed by a checkpointer — so a person can inspect the suggested title, summary, and tags, edit any of them, and leave free-text feedback before the final report is generated. This isn't a cosmetic log message: the edited values and feedback are injected back into the shared state via update_state() and are what the Reviewer/Critic agent actually reads when it resumes, which we verify with a dedicated test that inspects the exact text sent to the LLM after an edit.
Two issues surfaced only through real, interactive execution — not the mocked test suite alone:
update_state() raised InvalidUpdateError: Ambiguous update, specify as_node — LangGraph couldn't infer which of the two simultaneous writers the edit belonged to. Fixed by explicitly passing as_node="content_improver".n or e — as silent approval. Fixed by validating input and re-prompting until a real Y/n/e answer is given, backed by a dedicated regression test.Both issues trace back to the same architectural choice: Metadata Recommender and Content Improver running in parallel for latency. That's a deliberate tradeoff, and these two bugs are a concrete part of its cost — evidence of a real design decision with real, findable edges, not a frictionless demo.
Proof the human's input genuinely reaches the model, not just gets stored. Approving as-is with no edits in a real run against medical-rag-assistant produced this actual excerpt from the final report:
"Given the human reviewer's approval and the absence of specific feedback, it is recommended to proceed with the suggested title, summary, and tags..."
The model is explicitly reasoning about the human's approval status inside its own recommendation — a genuine conditional response to what happened at the checkpoint, not a static template.
Running with --auto-approve skips the interactive prompt for scripted or non-interactive use; the checkpoint is on by default otherwise.
Automated tests. The tool logic and agent orchestration are covered by 21 automated tests, including agent-level tests that mock the GitHub API and LLM calls so they run deterministically without needing live credentials, a regression test for a real concurrency bug caught during development (details below), dedicated tests proving the human-in-the-loop checkpoint genuinely pauses execution and that edits made during the pause reach the LLM call, and regression tests for the CLI input-validation fix described above.
Grounded generation. The Content Improver agent's system prompt explicitly instructs the LLM to draft claims only from the provided README text, not to invent features or metrics — reducing hallucinated claims in the suggested title/summary.
Graceful degradation. Every agent has explicit error handling. If the GitHub API fails, the web search API key is missing, or an LLM call errors, the pipeline continues and surfaces the issue in the final report rather than crashing.
A real run, not a mocked example. The following is unedited output from running the system against a real, independent repository (medical-rag-assistant):
$ python main.py --repo https://github.com/joramkirubi/medical-rag-assistant
The provided README for MedAssist, a medical AI assistant, covers essential
sections such as project title, installation, and license. However, it
lacks critical sections like overview/description, usage, configuration,
testing, and contributing.
MedAssist — Medical AI Assistant: uses Retrieval-Augmented Generation (RAG)
and ReAct reasoning strategy for medical question answering.
Retrieval-Augmented-Generation, RAG, LangChain, HuggingFace, Groq,
ChromaDB, ReAct, MedicalQuestionAnswering, Streamlit
Add the missing essential and professional sections to improve usability,
maintainability, and community engagement.
✅ Report saved to reports/joramkirubi_medical-rag-assistant_20260702-143012.md
This demonstrates all four agents completing successfully against a repo the system had never seen, with tags and structural gaps that are independently verifiable by checking the target repository directly.
Prerequisites: Python 3.10+, a free Groq API key (required), optionally a Tavily API key (enables web search positioning context) and a GitHub token (raises API rate limits).
Installation:
git clone https://github.com/joramkirubi/Publication-assistant.git
cd publication-assistant
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python main.py --repo https://github.com/owner/repo
Every run auto-saves a timestamped markdown report under reports/, in addition to printing it to the console.
Testing:
pytest tests/ -v
Code: https://github.com/joramkirubi/Publication-assistant
License: MIT
Contact: open an issue on the repository for questions or bug reports.
Publication Assistant demonstrates a multi-agent system where the agent/tool split reflects genuinely different sub-problems — deterministic structural analysis, LLM-refined metadata extraction, web-grounded content drafting, and final synthesis — coordinated through LangGraph's graph model rather than a single linear chain. It's a small system by design: four agents with clear, separable responsibilities, each independently testable, run successfully against a real, independent repository, with an honest account of where it can still fail.