Agent Service - Code Analysis AI Service

English | 中文

---

English

Overview

A FastAPI-based intelligent code analysis service that uses AI agents to automatically analyze code repositories and generate structured reports mapping feature requirements to their implementation locations.

Features

• 🤖 AI-Powered Analysis: Automatically identifies implementation locations for feature requirements
• 📊 Structured Reports: Returns JSON reports with file paths, function names, and line numbers
• 🔄 Streaming Support: Real-time streaming of analysis results
• 🔒 Secure File Handling: Safe ZIP extraction with path traversal protection
• 🌐 RESTful API: Easy integration with any client application
• 🐳 Docker Ready: Containerized deployment support

Architecture

agent_service/
├── app.py                      # FastAPI application entry point
├── main.py                     # Uvicorn startup script
├── agent_core/                 # Core analysis logic
│   ├── code_Analyze_agent.py  # AI agent definition
│   ├── code_analysis_tools.py # Analysis tool collection
│   └── utils/                  # Utility functions
│       ├── io.py              # File I/O operations
│       └── text.py            # Text processing utilities
└── tests/                      # Test scripts
    └── run_test_stream.py

API Endpoints

POST /analyze

Analyze code repository against requirements (synchronous)

Request:

• problem_description (form-data): Feature requirements description
• code_zip (file): ZIP archive of code repository

Response:

{
  "feature_analysis": [
    {
      "feature_description": "Create a channel",
      "implementation_location": [
        {
          "file": "src/channels/channels.service.ts",
          "function": "create",
          "lines": "23-35"
        }
      ]
    }
  ]
}

POST /analyze/stream

Analyze code repository with real-time streaming output

Request: Same as /analyze

Response: Server-Sent Events (SSE) stream with incremental results

GET /healthz

Health check endpoint

Response:

{
  "status": "ok"
}

Installation

Prerequisites

• Python 3.9+
• pip

Local Setup

1. Clone the repository:

git clone <repository-url>
cd agent_service

2. Install dependencies:

pip install -r requirements.txt

3. Set environment variables (optional):

export OPENAI_API_KEY="your-api-key-here"

4. Run the service:

python main.py

The service will be available at http://localhost:8000

Docker Deployment

1. Build the Docker image:

docker build -t agent-service:latest .

2. Run the container:

docker run -d \
  -p 8000:8000 \
  -e OPENAI_API_KEY="your-api-key" \
  --name agent-service \
  agent-service:latest

3. Check service status:

curl http://localhost:8000/healthz

Usage Example

Using cURL:

curl -X POST http://localhost:8000/analyze \
  -F "problem_description=Create a user authentication system" \
  -F "code_zip=@./my-project.zip"

Using Python:

import requests

url = "http://localhost:8000/analyze"
files = {
    "code_zip": open("project.zip", "rb")
}
data = {
    "problem_description": "Implement user login and registration"
}

response = requests.post(url, files=files, data=data)
print(response.json())

Analysis Tools

The service provides three core analysis tools:

1. read_lines_with_numbers: Reads file content with line numbers
2. build_tree: Generates directory tree structure
3. grepper_search: Regex-based code search

Configuration

Key configuration options can be set via environment variables:

• OPENAI_API_KEY: OpenAI API key for AI agent
• HOST: Service host (default: 0.0.0.0)
• PORT: Service port (default: 8000)

Testing

Run the streaming test:

python tests/run_test_stream.py

Tech Stack

• Web Framework: FastAPI
• AI Framework: OpenAI Agents
• Data Validation: Pydantic
• Server: Uvicorn
• Tree Visualization: treelib
• Async HTTP: aiohttp

Development

For development with auto-reload:

uvicorn app:app --reload --host 0.0.0.0 --port 8000

License

[Your License Here]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

中文

概述

基于 FastAPI 的智能代码分析服务，使用 AI 代理自动分析代码仓库，生成结构化报告，将功能需求映射到具体实现位置。

功能特性

• 🤖 AI 驱动分析：自动识别功能需求的实现位置
• 📊 结构化报告：返回包含文件路径、函数名和行号的 JSON 报告
• 🔄 流式支持：实时流式返回分析结果
• 🔒 安全文件处理：安全的 ZIP 解压，防止路径遍历攻击
• 🌐 RESTful API：易于与任何客户端应用集成
• 🐳 Docker 就绪：支持容器化部署

API 端点

POST /analyze

同步分析代码仓库

请求参数:

• problem_description (表单): 功能需求描述
• code_zip (文件): 代码仓库的 ZIP 压缩包

POST /analyze/stream

流式实时分析

GET /healthz

健康检查

安装部署

本地安装

1. 克隆仓库

git clone <repository-url>
cd agent_service

2. 安装依赖

pip install -r requirements.txt

3. 运行服务

python main.py

服务将在 http://localhost:8000 启动

Docker 部署

1. 构建镜像：

docker build -t agent-service:latest .

2. 运行容器：

docker run -d \
  -p 8000:8000 \
  -e OPENAI_API_KEY="your-api-key" \
  --name agent-service \
  agent-service:latest

使用示例

使用 cURL:

curl -X POST http://localhost:8000/analyze \
  -F "problem_description=创建用户认证系统" \
  -F "code_zip=@./my-project.zip"

使用 Python:

import requests

url = "http://localhost:8000/analyze"
files = {"code_zip": open("project.zip", "rb")}
data = {"problem_description": "实现用户登录和注册功能"}

response = requests.post(url, files=files, data=data)
print(response.json())

技术栈

• Web 框架: FastAPI
• AI 框架: OpenAI Agents
• 数据验证: Pydantic
• 服务器: Uvicorn
• 树形可视化: treelib

开发模式

开发模式启动（支持热重载）：

uvicorn app:app --reload --host 0.0.0.0 --port 8000

贡献

欢迎贡献代码！请随时提交 Pull Request。