Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
312 lines (239 loc) · 6.13 KB

CONTRIBUTING.md

File metadata and controls

312 lines (239 loc) · 6.13 KB
Raw

🚀 Development Guide

Developer Installation

# Clone the project
git clone <your-repo>
cd debat-ia-agents

# Install dependencies
npm install
npm run install:all

# Configure
cd backend
cp .env.example .env
# Add your API keys to .env

# Run in dev mode
cd ..
npm run dev

Code Architecture

Backend (TypeScript)

backend/src/
├── server.ts           # Express entry point
├── agents/            # Agent logic
│   ├── router.ts      # Request triage
│   ├── moderator.ts   # Debate preparation
│   ├── advocate.ts      # Argumentation
│   └── judge.ts        # Final synthesis
├── graph/             # LangGraph
│   ├── state.ts       # State types
│   └── workflow.ts    # Orchestration
├── tools/             # External tools
│   └── webSearch.ts   # Tavily API
└── config/            # Configuration
    └── prompts.ts     # System prompts

Frontend (React + TypeScript)

frontend/src/
├── App.tsx                    # Main component
├── components/
│   ├── DebateForm.tsx        # Form
│   └── DebateResult.tsx      # Display
└── types.ts                   # Shared types

Add a New Agent

  1. Create the file in backend/src/agents/
  2. Define the prompt in backend/src/config/prompts.ts
  3. Add the node in backend/src/graph/workflow.ts
  4. Update DebateState in backend/src/graph/state.ts

Example:

// backend/src/agents/new-agent.ts
import { ChatAnthropic } from "@langchain/anthropic";
import { DebateState } from "../graph/state.js";

const model = new ChatAnthropic({
  modelName: "claude-3-opus-20240229",
  temperature: 0.7,
});

export async function newAgentNode(
  state: DebateState
): Promise<Partial<DebateState>> {
  // Agent logic
  const response = await model.invoke([
    { role: "system", content: "Your system prompt" },
    { role: "user", content: state.userQuery },
  ]);

  return {
    // State update
    newField: response.content.toString(),
  };
}

Modify Prompts

Prompts are centralized in backend/src/config/prompts.ts.

export const PROMPTS = {
  router: {
    system: `Your new prompt...`,
  },
  // ...
};

Add a New Tool

  1. Create the file in backend/src/tools/
  2. Use the LangChain tool pattern:
import { tool } from "@langchain/core/tools";
import { z } from "zod";

export const myNewTool = tool(
  async ({ param }: { param: string }) => {
    // Tool logic
    return "result";
  },
  {
    name: "my_new_tool",
    description: "Description of the tool",
    schema: z.object({
      param: z.string().describe("Description of the parameter"),
    }),
  }
);
  1. Bind the tool to an agent:
const model = new ChatAnthropic({
  modelName: "claude-3-opus-20240229",
}).bindTools([myNewTool]);

Frontend Styles

The project uses TailwindCSS. Useful classes:

// Gradients
className="bg-gradient-to-br from-indigo-100 via-purple-50 to-pink-100"

// Cards
className="bg-white rounded-2xl shadow-xl p-8"

// Buttons
className="px-8 py-4 bg-indigo-600 text-white font-semibold rounded-xl hover:bg-indigo-700"

// Agent color codes
className="bg-blue-100 text-blue-800"      // Advocate A
className="bg-purple-100 text-purple-800"  // Advocate B
className="bg-amber-50 text-gray-900"      // Judge

Tests

Test the API

# Automatic test script
npm run test

# Or manually
curl -X POST http://localhost:3000/api/debate \
  -H "Content-Type: application/json" \
  -d '{"query": "React vs Vue.js"}'

Test an Isolated Agent

Create a test file:

// backend/src/tests/test-agent.ts
import { routerNode } from "../agents/router.js";

const testState = {
  userQuery: "What is React?",
  // ... other fields
};

const result = await routerNode(testState);
console.log(result);

Run with:

cd backend
npx tsx src/tests/test-agent.ts

Debugging

Backend

Enable debug mode in .env:

DEBUG_MODE=true

Logs will appear in the terminal:

🔀 Agent Router - Analyzing the request...
📋 Agent Moderator - Preparing the debate...
⚖️ Advocate A - Defending React...

Frontend

Use React DevTools:

  • Install the Chrome/Firefox extension
  • Inspect components
  • Observe state and props

Environment Variables

Backend

# APIs
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
TAVILY_API_KEY=tvly-...

# Server
PORT=3000
NODE_ENV=development

# Models (customizable)
ROUTER_MODEL=claude-3-haiku-20240307
MODERATOR_MODEL=claude-sonnet-4-20250514
ADVOCATE_MODEL=claude-3-opus-20240229
JUDGE_MODEL=gpt-4o

# System
MAX_ITERATIONS=10
DEBUG_MODE=true

Production Build

# Build backend
cd backend
npm run build

# Build frontend
cd ../frontend
npm run build

# Or both
npm run build

Production files will be in:

  • backend/dist/
  • frontend/dist/

Deployment

Backend (e.g., Render/Railway)

  1. Connect the GitHub repo
  2. Define environment variables
  3. Build command: cd backend && npm install && npm run build
  4. Start command: cd backend && npm start

Frontend (e.g., Vercel/Netlify)

  1. Connect the GitHub repo
  2. Build command: cd frontend && npm run build
  3. Output directory: frontend/dist
  4. Configure the backend URL in environment variables

Contributing

  1. Fork the project
  2. Create a branch: git checkout -b feature/my-feature
  3. Commit: git commit -m "feat: add my feature"
  4. Push: git push origin feature/my-feature
  5. Open a Pull Request

Commit Convention

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Formatting
  • refactor: Refactoring
  • test: Tests
  • chore: Maintenance

Resources

API Documentation

Tools

License

MIT