openrabbit/docs/api-reference.md

API Reference

Gitea Client

clients/gitea_client.py

Initialization

from clients import GiteaClient

client = GiteaClient(
    api_url="https://gitea.example.com/api/v1",
    token="your_token",
    timeout=30,
)

Issue Methods

# List issues
issues = client.list_issues(
    owner="user",
    repo="repo",
    state="open",      # open, closed, all
    labels=["bug"],
    page=1,
    limit=30,
)

# Get single issue
issue = client.get_issue(owner, repo, index=123)

# Create comment
comment = client.create_issue_comment(owner, repo, index=123, body="Comment text")

# Update comment
client.update_issue_comment(owner, repo, comment_id=456, body="Updated text")

# List comments
comments = client.list_issue_comments(owner, repo, index=123)

# Add labels
client.add_issue_labels(owner, repo, index=123, labels=[1, 2, 3])

# Get repo labels
labels = client.get_repo_labels(owner, repo)

Pull Request Methods

# Get PR
pr = client.get_pull_request(owner, repo, index=123)

# Get diff
diff = client.get_pull_request_diff(owner, repo, index=123)

# List changed files
files = client.list_pull_request_files(owner, repo, index=123)

# Create review with inline comments
client.create_pull_request_review(
    owner, repo, index=123,
    body="Review summary",
    event="COMMENT",  # APPROVE, REQUEST_CHANGES, COMMENT
    comments=[
        {"path": "file.py", "line": 10, "body": "Issue here"},
    ],
)

Repository Methods

# Get repository info
repo = client.get_repository(owner, repo)

# Get file contents (base64 encoded)
content = client.get_file_contents(owner, repo, "path/to/file.py", ref="main")

# Get branch
branch = client.get_branch(owner, repo, "main")

---

LLM Client

clients/llm_client.py

Initialization

from clients import LLMClient

# Direct initialization
client = LLMClient(
    provider="openai",  # openai, openrouter, ollama
    config={"model": "gpt-4", "temperature": 0},
)

# From config file
client = LLMClient.from_config(config_dict)

Methods

# Basic call
response = client.call("Explain this code")
print(response.content)
print(response.tokens_used)

# JSON response
result = client.call_json("Return JSON: {\"key\": \"value\"}")
print(result["key"])

Response Object

@dataclass
class LLMResponse:
    content: str           # Generated text
    model: str             # Model used
    provider: str          # Provider name
    tokens_used: int       # Token count
    finish_reason: str     # stop, length, etc.

---

Base Agent

agents/base_agent.py

Creating Custom Agent

from agents import BaseAgent, AgentContext, AgentResult

class MyAgent(BaseAgent):
    def can_handle(self, event_type: str, event_data: dict) -> bool:
        return event_type == "my_event"

    def execute(self, context: AgentContext) -> AgentResult:
        # Use built-in methods
        prompt = self.load_prompt("my_prompt")
        response = self.call_llm(prompt)

        self.upsert_comment(
            context.owner,
            context.repo,
            issue_index=123,
            body=response.content,
        )

        return AgentResult(
            success=True,
            message="Done",
            actions_taken=["posted comment"],
        )

Built-in Methods

# Load prompt template
prompt = self.load_prompt("prompt_name")  # From prompts/prompt_name.md

# LLM calls (with rate limiting)
response = self.call_llm(prompt)
json_result = self.call_llm_json(prompt)

# Comment management
comment_id = self.find_ai_comment(owner, repo, issue_index)
self.upsert_comment(owner, repo, issue_index, body)

# Format with disclaimer
formatted = self.format_with_disclaimer(content)

Context Object

@dataclass
class AgentContext:
    owner: str           # Repository owner
    repo: str            # Repository name
    event_type: str      # Event type
    event_data: dict     # Event payload
    config: dict         # Configuration

Result Object

@dataclass
class AgentResult:
    success: bool
    message: str
    data: dict = {}
    actions_taken: list[str] = []
    error: str | None = None

---

Dispatcher

dispatcher.py

Usage

from dispatcher import Dispatcher, get_dispatcher

# Get global dispatcher
dispatcher = get_dispatcher()

# Register agents
dispatcher.register_agent(MyAgent())

# Dispatch event
result = dispatcher.dispatch(
    event_type="pull_request",
    event_data={"action": "opened", ...},
    owner="user",
    repo="repo",
)

# Async dispatch
future = dispatcher.dispatch_async(event_type, event_data, owner, repo)
result = future.result()

---

Security Scanner

security/security_scanner.py

Usage

from security import SecurityScanner

scanner = SecurityScanner()

# Scan content
for finding in scanner.scan_content(code, "file.py"):
    print(finding.rule_id, finding.severity, finding.line)

# Scan diff (only added lines)
for finding in scanner.scan_diff(diff):
    print(finding.file, finding.line, finding.code_snippet)

# Summary
findings = list(scanner.scan_diff(diff))
summary = scanner.get_summary(findings)

Finding Object

@dataclass
class SecurityFinding:
    rule_id: str         # SEC001, SEC002, etc.
    rule_name: str       # Human-readable name
    severity: str        # HIGH, MEDIUM, LOW
    category: str        # OWASP category
    file: str            # File path
    line: int            # Line number
    code_snippet: str    # Matched code
    description: str     # Issue description
    recommendation: str  # How to fix
    cwe: str | None      # CWE reference