docs: Comprehensive documentation with Mermaid diagrams #8
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Create docs/ directory with 11 structured Markdown files - Add Mermaid diagrams for architecture, agent loop, context management - Document Chutes API integration (CHUTES_API_KEY, Kimi K2.5-TEE) - Include usage examples with python3 agent.py --instruction - Cover configuration, tools reference, best practices - Update README.md to reference new documentation structure
📝 WalkthroughWalkthroughThis PR reorganizes README.md and introduces comprehensive documentation covering BaseAgent's architecture, installation, quickstart, tools, configuration, context management, best practices, and Chutes AI integration. All changes are documentation-focused with no code modifications. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
5 tasks
Contributor
Author
|
Part of Umbrella PR: #6 (Epic: Complete Chutes API Integration) This PR is the second step in the stacked PR sequence:
Note: After #7 is merged, this PR should be rebased on main before merging. Please see #6 for the complete merge strategy. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Fix all issues with AI agents
In `@docs/chutes-integration.md`:
- Around line 131-136: The table's LLM_PROVIDER default conflicts with the
document narrative; update the LLM_PROVIDER row so its Default column reads
`chutes` (and keep or adjust the Description to "Set to `chutes`") to match the
"Chutes as default" messaging; ensure related variables CHUTES_API_TOKEN,
LLM_MODEL, and LLM_COST_LIMIT remain unchanged and that any earlier prose that
states the default also references `chutes` so the doc is consistent.
In `@docs/context-management.md`:
- Around line 355-363: The fenced code block containing the compaction log
should include a language specifier (e.g., "text") to satisfy rendering and
linting; update the triple-backtick fence that wraps the log lines starting with
"[14:30:16] [compaction] ..." so it becomes ```text (and close with ```),
leaving the log contents unchanged.
In `@docs/installation.md`:
- Around line 68-72: Several fenced code blocks in the installation docs use
plain triple backticks; update those blocks (the dependency list block
containing "litellm... pydantic..." and the directory tree block starting with
"baseagent/") to use language tag "text" (i.e., replace ``` with ```text at the
opening fence) so the blocks render properly and satisfy MD040; apply the same
change to the other similar block around the later directory listing as noted in
the comment.
- Around line 151-153: The documentation uses a development-only import path;
change the verification command to import run_agent_loop from the installed
package namespace by replacing "from src.core.loop import run_agent_loop" with
"from baseagent.core.loop import run_agent_loop" so the verification (printing
"BaseAgent: OK") works for users who installed the package.
In `@docs/README.md`:
- Line 5: Update the phrasing in the README sentence describing BaseAgent to
hyphenate "decision-making" for standard usage by changing the phrase
"LLM-driven decision making" to "LLM-driven decision-making" (reference: the
BaseAgent description line mentioning "LLM-driven decision making").
- Around line 100-119: Update the fenced code block that shows the project tree
(the block starting with "baseagent/") in README.md to include a language tag by
changing the opening backticks from ``` to ```text so markdownlint renders it
consistently; ensure the closing fence remains ``` and no other content is
modified.
In `@docs/tools.md`:
- Around line 94-100: Update the Markdown fenced code blocks in docs/tools.md to
include a language tag (use "text" for output/examples or a more specific
language where appropriate) so markdownlint MD040 is satisfied; specifically,
add "text" after the opening ``` for all the shown example blocks (directory
listings, docstring snippets, patch blocks, file lists and directory trees) and
the other similar blocks referenced in the review to ensure every
triple-backtick fence has a language identifier.
Comment on lines
+131
to
+136
| | Variable | Required | Default | Description | | ||
| |----------|----------|---------|-------------| | ||
| | `CHUTES_API_TOKEN` | Yes | - | API token from chutes.ai | | ||
| | `LLM_PROVIDER` | No | `openrouter` | Set to `chutes` | | ||
| | `LLM_MODEL` | No | `moonshotai/Kimi-K2.5-TEE` | Model identifier | | ||
| | `LLM_COST_LIMIT` | No | `10.0` | Max cost in USD | |
There was a problem hiding this comment.
Align the default LLM_PROVIDER with the “Chutes as default” narrative.
The table lists default openrouter, but earlier sections describe Chutes as the default. Please reconcile to avoid confusion.
Suggested fix (if Chutes is the default)
-| `LLM_PROVIDER` | No | `openrouter` | Set to `chutes` |
+| `LLM_PROVIDER` | No | `chutes` | Set to `chutes` |🤖 Prompt for AI Agents
In `@docs/chutes-integration.md` around lines 131 - 136, The table's LLM_PROVIDER
default conflicts with the document narrative; update the LLM_PROVIDER row so
its Default column reads `chutes` (and keep or adjust the Description to "Set to
`chutes`") to match the "Chutes as default" messaging; ensure related variables
CHUTES_API_TOKEN, LLM_MODEL, and LLM_COST_LIMIT remain unchanged and that any
earlier prose that states the default also references `chutes` so the doc is
consistent.
Comment on lines
+355
to
+363
| ``` | ||
| [14:30:16] [compaction] Context: 45000 tokens (26.8% of 168000) | ||
| [14:35:22] [compaction] Context: 125000 tokens (74.4% of 168000) | ||
| [14:38:45] [compaction] Context: 148000 tokens (88.1% of 168000) | ||
| [14:38:45] [compaction] Context overflow detected, managing... | ||
| [14:38:45] [compaction] Prune scan: 95000 total tokens, 55000 prunable | ||
| [14:38:45] [compaction] Pruning 12 tool outputs, recovering ~55000 tokens | ||
| [14:38:46] [compaction] Pruning sufficient: 148000 -> 93000 tokens | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to fenced code block.
The log output code block should specify a language for proper rendering and linting compliance.
📝 Proposed fix
-```
+```text
[14:30:16] [compaction] Context: 45000 tokens (26.8% of 168000)
[14:35:22] [compaction] Context: 125000 tokens (74.4% of 168000)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ``` | |
| [14:30:16] [compaction] Context: 45000 tokens (26.8% of 168000) | |
| [14:35:22] [compaction] Context: 125000 tokens (74.4% of 168000) | |
| [14:38:45] [compaction] Context: 148000 tokens (88.1% of 168000) | |
| [14:38:45] [compaction] Context overflow detected, managing... | |
| [14:38:45] [compaction] Prune scan: 95000 total tokens, 55000 prunable | |
| [14:38:45] [compaction] Pruning 12 tool outputs, recovering ~55000 tokens | |
| [14:38:46] [compaction] Pruning sufficient: 148000 -> 93000 tokens | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 355-355: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@docs/context-management.md` around lines 355 - 363, The fenced code block
containing the compaction log should include a language specifier (e.g., "text")
to satisfy rendering and linting; update the triple-backtick fence that wraps
the log lines starting with "[14:30:16] [compaction] ..." so it becomes ```text
(and close with ```), leaving the log contents unchanged.
Comment on lines
+68
to
+72
| ``` | ||
| litellm>=1.0.0 # LLM API abstraction | ||
| httpx>=0.24.0 # HTTP client | ||
| pydantic>=2.0.0 # Data validation | ||
| ``` |
There was a problem hiding this comment.
Add language tags to fenced code blocks.
Use ```text for dependency and directory listings to satisfy MD040 and improve formatting.
Suggested fix
-```
+```text
litellm>=1.0.0 # LLM API abstraction
httpx>=0.24.0 # HTTP client
pydantic>=2.0.0 # Data validation
-```
+```
-```
+```text
baseagent/
├── agent.py # ✓ Entry point
@@
└── astuces/ # Implementation techniques
-```
+```Also applies to: 167-188
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 68-68: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@docs/installation.md` around lines 68 - 72, Several fenced code blocks in the
installation docs use plain triple backticks; update those blocks (the
dependency list block containing "litellm... pydantic..." and the directory tree
block starting with "baseagent/") to use language tag "text" (i.e., replace ```
with ```text at the opening fence) so the blocks render properly and satisfy
MD040; apply the same change to the other similar block around the later
directory listing as noted in the comment.
Comment on lines
+151
to
+153
| ```bash | ||
| python3 -c "from src.core.loop import run_agent_loop; print('BaseAgent: OK')" | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check where run_agent_loop is defined and how packages are structured
rg -nP 'def\s+run_agent_loop\b' -S src/
rg -nP 'run_agent_loop' -S pyproject.toml setup.cfg setup.py src/Repository: PlatformNetwork/baseagent
Length of output: 425
🏁 Script executed:
#!/bin/bash
# Check pyproject.toml for package configuration
cat -n pyproject.toml | head -50
# Also check if there's a __init__.py in the repo root or how package is structured
ls -la | grep -E "^\-|^d" | head -20
fd -d 1 "__init__.py"
# Check package name and any entry points
rg -A 5 "^\[project\]|name\s*=" pyproject.toml | head -20Repository: PlatformNetwork/baseagent
Length of output: 3050
Update the verification import path to use the installed package name.
The code shows from src.core.loop import run_agent_loop, which only works in development. When users install the package, they must use from baseagent.core.loop import run_agent_loop instead. Update the installation guide to show the correct import path for installed packages.
🤖 Prompt for AI Agents
In `@docs/installation.md` around lines 151 - 153, The documentation uses a
development-only import path; change the verification command to import
run_agent_loop from the installed package namespace by replacing "from
src.core.loop import run_agent_loop" with "from baseagent.core.loop import
run_agent_loop" so the verification (printing "BaseAgent: OK") works for users
who installed the package.
|
|
||
| > **Professional documentation for the BaseAgent autonomous coding assistant** | ||
|
|
||
| BaseAgent is a high-performance autonomous agent designed for the [Term Challenge](https://term.challenge). It leverages LLM-driven decision making with advanced context management and cost optimization techniques. |
There was a problem hiding this comment.
Hyphenate “decision-making” for standard usage.
Small wording polish to match common technical style.
🧰 Tools
🪛 LanguageTool
[grammar] ~5-~5: Use a hyphen to join words.
Context: ...lenge). It leverages LLM-driven decision making with advanced context management ...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In `@docs/README.md` at line 5, Update the phrasing in the README sentence
describing BaseAgent to hyphenate "decision-making" for standard usage by
changing the phrase "LLM-driven decision making" to "LLM-driven decision-making"
(reference: the BaseAgent description line mentioning "LLM-driven decision
making").
Comment on lines
+100
to
+119
| ``` | ||
| baseagent/ | ||
| ├── agent.py # Entry point | ||
| ├── src/ | ||
| │ ├── core/ | ||
| │ │ ├── loop.py # Main agent loop | ||
| │ │ └── compaction.py # Context management | ||
| │ ├── llm/ | ||
| │ │ └── client.py # LLM client (litellm) | ||
| │ ├── config/ | ||
| │ │ └── defaults.py # Configuration | ||
| │ ├── tools/ # Tool implementations | ||
| │ ├── prompts/ | ||
| │ │ └── system.py # System prompt | ||
| │ └── output/ | ||
| │ └── jsonl.py # JSONL event emission | ||
| ├── rules/ # Development guidelines | ||
| ├── astuces/ # Implementation techniques | ||
| └── docs/ # This documentation | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the fenced code block.
Markdownlint flags the project structure block; using ```text improves rendering consistency.
Suggested fix
-```
+```text
baseagent/
├── agent.py # Entry point
@@
└── docs/ # This documentation
-```
+```🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 100-100: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@docs/README.md` around lines 100 - 119, Update the fenced code block that
shows the project tree (the block starting with "baseagent/") in README.md to
include a language tag by changing the opening backticks from ``` to ```text so
markdownlint renders it consistently; ensure the closing fence remains ``` and
no other content is modified.
Comment on lines
+94
to
+100
| ``` | ||
| total 40 | ||
| drwxr-xr-x 7 root root 4096 Feb 3 13:16 . | ||
| drwxr-xr-x 1 root root 4096 Feb 3 12:00 .. | ||
| -rw-r--r-- 1 root root 5432 Feb 3 13:16 agent.py | ||
| drwxr-xr-x 4 root root 4096 Feb 3 13:16 src | ||
| ``` |
There was a problem hiding this comment.
Add language tags to fenced blocks to satisfy markdownlint.
Use text (or a more specific language) for output examples to avoid MD040 warnings.
Suggested fix
-```
+```text
total 40
drwxr-xr-x 7 root root 4096 Feb 3 13:16 .
@@
drwxr-xr-x 4 root root 4096 Feb 3 13:16 src
-```
+```
-```
+```text
L1: """
L2: Main agent loop - the heart of the SuperAgent system.
@@
L6: import time
-```
+```
-```
+```text
*** Begin Patch
*** Add File: path/to/new/file.py
@@
*** End Patch
-```
+```
-```
+```text
src/llm/client.py
src/core/compaction.py
src/utils/truncate.py
-```
+```
-```
+```text
src/
core/
loop.py
@@
tools/
shell.py
read_file.py
-```
+```Also applies to: 131-138, 192-203, 263-267, 306-316
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 94-94: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@docs/tools.md` around lines 94 - 100, Update the Markdown fenced code blocks
in docs/tools.md to include a language tag (use "text" for output/examples or a
more specific language where appropriate) so markdownlint MD040 is satisfied;
specifically, add "text" after the opening ``` for all the shown example blocks
(directory listings, docstring snippets, patch blocks, file lists and directory
trees) and the other similar blocks referenced in the review to ensure every
triple-backtick fence has a language identifier.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds comprehensive documentation with Mermaid diagrams for the BaseAgent project.
Changes
docs/directory with 11 structured Markdown filespython3 agent.py --instructionDocumentation Structure
Related
Summary by CodeRabbit