CODEFORGE Docs

Quick Start

1. 1
   Clone and install

   Python 3.10+ required.

   git clone https://github.com/vignesh2027/CODEFORGE.git
   cd CODEFORGE
   pip install -r requirements.txt

2. 2
   Configure keys

   Copy the example and fill in Groq + Tavily keys.

   cp .env.example .env
   # edit .env and set:
   GROQ_API_KEY=gsk_...
   TAVILY_API_KEY=tvly-...

3. 3
   Run

   python3 main.py

4. 4
   Verify with tests

   python3 tests/test_suite.py
   # Expected: 20/20 passing · 100%

Configuration

All configuration is via a .env file in the project root. Copy .env.example to get started. The file is gitignored and never committed.

All Environment Variables

Agents

Six agents run in sequence. Each reads the full AgentState and writes only the fields it owns. Feedback loops are handled by LangGraph conditional edges.

1. Orchestrator

// JSON response from Groq
{
  "task_summary": "Implement a BST with insert, search, delete",
  "language": "python"
}

2. Planner

3. Coder

4. Reviewer

{
  "approved": true,
  "score": 9,
  "issues": [],
  "summary": "Clean BST implementation, all edge cases handled"
}

5. Executor

6. Debugger

DIAGNOSIS: IndentationError on line 14 — mixed tabs and spaces

```python
# complete fixed code here
```

Shared State

All agents communicate through a single AgentState TypedDict defined in state/schema.py. LangGraph passes this state through the graph — each agent receives the full object and returns only the fields it modifies.

class AgentState(TypedDict):
    task: str                    # raw task → summarized by Orchestrator
    plan: str                    # implementation plan from Planner
    language: str                # detected language (e.g. "python")
    code: str                    # current code from Coder/Debugger
    code_iteration: int          # how many times Coder has run
    review_feedback: str         # Reviewer's rejection reason
    review_approved: bool        # True = proceed to Executor
    execution_output: str        # stdout/stderr from subprocess
    execution_success: bool      # True = code ran without error
    debug_attempts: int          # how many Debugger cycles ran
    debug_notes: str             # Debugger's diagnosis
    current_agent: str           # name of the currently active agent
    agent_log: List[str]         # chronological activity log
    final_code: str              # confirmed working code (set by Executor)
    final_explanation: str       # human-readable explanation
    messages: Annotated[List, add_messages]  # LangChain message history

Routing Logic

Two conditional edges drive the feedback loops in graph/workflow.py:

After Reviewer

def _route_after_review(state: AgentState) -> str:
    if state["review_approved"] or state["code_iteration"] >= MAX_CODE_ITERATIONS:
        return "executor"    # approved, or max loops hit
    return "coder"            # send back for rework

After Executor

def _route_after_execution(state: AgentState) -> str:
    if state["execution_success"] or state["debug_attempts"] >= MAX_DEBUG_ATTEMPTS:
        return END             # success, or max debug attempts
    return "debugger"         # execution failed — debug it

Tools

TavilySearch — tools/search.py

from langchain_tavily import TavilySearch

def get_search_tool():
    return TavilySearch(max_results=3)

The Coder agent binds this tool with llm.bind_tools([search_tool]). The LLM decides autonomously whether to call it.

execute_python_code — tools/repl.py

def execute_python_code(code: str, timeout: int = 30) -> tuple[bool, str]:
    # writes to tempfile, runs subprocess, returns (success, output)

Returns (True, stdout) on success, (False, error_message) on failure or timeout. The temp file is always cleaned up.

LangSmith Integration

LangSmith traces every LLM call in the pipeline automatically when enabled. No code changes required — tracing is controlled entirely by environment variables.

Enable tracing

# In .env
LANGSMITH_API_KEY=lsv2_pt_...    # personal token, not service key
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=CODEFORGE

What gets traced

• Every agent's LLM call (prompt + response)
• Token counts (input / output / total)
• Latency per call
• Tool calls (Tavily search queries + results)
• Run metadata (agent name, iteration count)

Flowise Integration

CODEFORGE ships with a script that automatically creates and deploys a visual agent canvas in Flowise Cloud.

Deploy

# Set FLOWISE_API_KEY in .env, then:
python3 flowise/create_flow.py

The script creates a CHATFLOW with three nodes — ChatGroq → BufferMemory → CODEFORGE Agent — with real edge connections and the Groq API key pre-embedded. It prints the canvas URL when done.

Canvas structure

Test Suite

python3 tests/test_suite.py

Adding tests

def test_my_feature():
    result = my_function()
    assert result == expected, f"Got {result}"
    return "Descriptive success message"

# Register in main():
suite.run("Category", "My feature", test_my_feature)

File Structure

CODEFORGE/
├── main.py                 ← entry point, run this
├── requirements.txt        ← pip dependencies
├── .env.example            ← copy to .env, fill in keys
├── LICENSE                 ← MIT
├── CONTRIBUTING.md
│
├── state/
│   └── schema.py           ← AgentState TypedDict
│
├── config/
│   ├── settings.py         ← env loader, LangSmith setup
│   └── llm.py              ← ChatGroq(model, max_retries=3)
│
├── agents/
│   ├── orchestrator.py     ← Agent 1: language detection
│   ├── planner.py          ← Agent 2: implementation plan
│   ├── coder.py            ← Agent 3: code generation + Tavily
│   ├── reviewer.py         ← Agent 4: quality scoring
│   ├── executor.py         ← Agent 5: subprocess runner
│   └── debugger.py         ← Agent 6: error diagnosis
│
├── tools/
│   ├── search.py           ← TavilySearch wrapper
│   └── repl.py             ← execute_python_code()
│
├── graph/
│   └── workflow.py         ← StateGraph, routing functions
│
├── flowise/
│   └── create_flow.py      ← Flowise CHATFLOW builder
│
├── tests/
│   └── test_suite.py       ← 20 tests, Rich report
│
└── docs/                   ← GitHub Pages (auto-deploys)
    ├── index.html          ← landing page
    └── docs.html           ← this file

FAQ

Which Groq models can I use?

Any model supported by Groq and accessible via langchain-groq. The default is llama-3.3-70b-versatile. Change it with MODEL_NAME in .env. Other tested options: llama3-8b-8192 (faster, lower quality), mixtral-8x7b-32768.

Why subprocess for code execution instead of exec() or PythonREPL?

Subprocess runs in a completely separate Python process, so a crash, infinite loop, or malicious code cannot affect the main CODEFORGE process. exec() shares the same process memory and namespace. PythonREPLTool from LangChain is a thin wrapper around exec().

Does it work with non-Python languages?

Yes — Orchestrator detects the language and Coder writes idiomatic code for it. Execution is Python-only (subprocess). JavaScript, TypeScript, Go, Rust, Java, C++, and others get full generation + review, then execution_success is set to True with a note that execution was skipped.

What happens if Groq rate-limits me?

The ChatGroq instance is configured with max_retries=3 and automatic exponential backoff. Heavy consecutive pipeline runs (5+ in a row) can exhaust the free 12,000 TPM limit. Wait 60 seconds and retry.

Can I use a different LLM provider?

Yes. Change config/llm.py to return any BaseChatModel-compatible object (ChatOpenAI, ChatAnthropic, ChatGoogleGenerativeAI, etc.). All agents use the model via the same interface.