# fishmingyu/orcaloca architecture

> Architecture diagram of the GitHub repository fishmingyu/orcaloca, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fishmingyu/orcaloca
- Repository: https://github.com/fishmingyu/orcaloca
- Video tour (about a minute): https://gitdiagram.com/fishmingyu/orcaloca/video

## Overview

OrcaLoca localizes software issues in benchmark repositories through trace analysis followed by LLM-guided search. Its search layer builds and queries a repository symbol graph and inverted index, while the agent manages prioritized actions, decomposition, relevance scoring, and context pruning before producing bug locations. The README also documents top-K retrieval and external SearchAgent-backend support. Sampled source confirms parts of search, graph construction, parsing, and CLI trace execution; wiring for the full trace/search orchestration is therefore shown only where documented, and finer internal trace details are omitted.

Main entry points: [`Orcar/search_agent.py`](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/search_agent.py) (Search agent), [`evaluation/run.py`](https://github.com/fishmingyu/orcaloca/blob/main/evaluation/run.py) (Evaluation runner), [`Orcar/trace_analysis_agent.py`](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/trace_analysis_agent.py) (Trace analysis agent), [`cli.py`](https://github.com/fishmingyu/orcaloca/blob/main/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_runner["Evaluation runner<br/>[run.py]"]
  node_cli["CLI<br/>[cli.py]"]
  node_dataset["Benchmark dataset"]
  node_environment["Benchmark environment"]
end

subgraph group_analysis["Trace analysis"]
  node_trace["Trace analysis agent"]
  node_tracer["Execution tracer<br/>[tracer.py]"]
  node_trace_types["Trace result types<br/>[types.py]"]
end

subgraph group_search["Search and retrieval"]
  node_agent["Orca agent<br/>[agent.py]"]
  node_search_agent["Search agent<br/>[search_agent.py]"]
  node_search_manager["Search manager<br/>[search_tool.py]"]
  node_parser["Output parser<br/>[output_parser.py]"]
  node_result["Bug locations<br/>[types.py]"]
end

subgraph group_repository["Repository model"]
  node_graph[("Symbol graph<br/>[build_graph.py]")]
  node_index[("Inverted index<br/>[inverted_index.py]")]
  node_scorer["Code relevance scorer<br/>[code_scorer.py]"]
end

node_user(("Benchmark user"))
node_repo["Issue repository"]
node_llm(("LLM service"))

node_user -->|"starts run"| node_runner
node_runner -->|"loads instances"| node_dataset
node_runner -->|"dispatches stages"| node_cli
node_cli -->|"sets up environment"| node_environment
node_cli -->|"runs analysis"| node_trace
node_environment -->|"prepares repository"| node_repo
node_trace -->|"requests analysis"| node_llm
node_trace -->|"uses tracing"| node_tracer
node_trace -->|"produces trace output"| node_trace_types
node_runner -->|"runs search stage"| node_search_agent
node_search_agent -->|"requests actions"| node_llm
node_search_agent -->|"invokes search tools"| node_search_manager
node_search_agent -->|"parses responses"| node_parser
node_search_agent -->|"scores candidates"| node_scorer
node_search_agent -->|"emits locations"| node_result
node_search_manager -->|"queries graph"| node_graph
node_search_manager -->|"queries index"| node_index
node_repo -->|"indexed as symbols"| node_graph
node_repo -->|"indexed for lookup"| node_index
node_agent -->|"provides agent framework"| node_search_agent

click node_runner "https://github.com/fishmingyu/orcaloca/blob/main/evaluation/run.py"
click node_cli "https://github.com/fishmingyu/orcaloca/blob/main/cli.py"
click node_dataset "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/load_cache_dataset.py"
click node_environment "https://github.com/fishmingyu/orcaloca/tree/main/Orcar/environment"
click node_trace "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/trace_analysis_agent.py"
click node_tracer "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/tracer.py"
click node_trace_types "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/types.py"
click node_agent "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/agent.py"
click node_search_agent "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/search_agent.py"
click node_search_manager "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/search/search_tool.py"
click node_parser "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/output_parser.py"
click node_result "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/types.py"
click node_graph "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/search/build_graph.py"
click node_index "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/search/inverted_index.py"
click node_scorer "https://github.com/fishmingyu/orcaloca/blob/main/Orcar/code_scorer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_cli,node_dataset,node_environment,node_user toneBlue
class node_trace,node_tracer,node_trace_types toneAmber
class node_agent,node_search_agent,node_search_manager,node_parser,node_result toneMint
class node_graph,node_index,node_scorer toneRose
class node_repo,node_llm toneIndigo
```

## Components

### Entry and orchestration

- [Evaluation runner](https://github.com/fishmingyu/orcaloca/blob/main/evaluation/run.py): `evaluation/run.py`
- [CLI](https://github.com/fishmingyu/orcaloca/blob/main/cli.py): `cli.py`
- [Benchmark dataset](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/load_cache_dataset.py): `Orcar/load_cache_dataset.py`
- [Benchmark environment](https://github.com/fishmingyu/orcaloca/tree/main/Orcar/environment): `Orcar/environment`

### Trace analysis

- [Trace analysis agent](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/trace_analysis_agent.py): `Orcar/trace_analysis_agent.py`
- [Execution tracer](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/tracer.py): `Orcar/tracer.py`
- [Trace result types](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/types.py): `Orcar/types.py`

### Search and retrieval

- [Orca agent](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/agent.py): `Orcar/agent.py`
- [Search agent](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/search_agent.py): `Orcar/search_agent.py`
- [Search manager](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/search/search_tool.py): `Orcar/search/search_tool.py`
- [Output parser](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/output_parser.py): `Orcar/output_parser.py`
- [Bug locations](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/types.py): `Orcar/types.py`

### Repository model

- [Symbol graph](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/search/build_graph.py): `Orcar/search/build_graph.py`
- [Inverted index](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/search/inverted_index.py): `Orcar/search/inverted_index.py`
- [Code relevance scorer](https://github.com/fishmingyu/orcaloca/blob/main/Orcar/code_scorer.py): `Orcar/code_scorer.py`

### Other components

- **Benchmark user**
- **Issue repository**
- **LLM service**

## Connections

- Benchmark user → Evaluation runner: starts run
- Evaluation runner → Benchmark dataset: loads instances
- Evaluation runner → CLI: dispatches stages
- CLI → Benchmark environment: sets up environment
- CLI → Trace analysis agent: runs analysis
- Benchmark environment → Issue repository: prepares repository
- Trace analysis agent → LLM service: requests analysis
- Trace analysis agent → Execution tracer: uses tracing
- Trace analysis agent → Trace result types: produces trace output
- Evaluation runner → Search agent: runs search stage
- Search agent → LLM service: requests actions
- Search agent → Search manager: invokes search tools
- Search agent → Output parser: parses responses
- Search agent → Code relevance scorer: scores candidates
- Search agent → Bug locations: emits locations
- Search manager → Symbol graph: queries graph
- Search manager → Inverted index: queries index
- Issue repository → Symbol graph: indexed as symbols
- Issue repository → Inverted index: indexed for lookup
- Orca agent → Search agent: provides agent framework