Skip to content

Commit 9f578f0

Browse files
lyzx2001lyzx2001
committed
Migrate ARK to kaust-ark and update links
0 parents  commit 9f578f0

File tree

121 files changed

+27404
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

121 files changed

+27404
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Bug Report
2+
description: Report a bug or unexpected behavior
3+
labels: ["bug"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for reporting a bug! Please fill out the sections below.
9+
10+
- type: textarea
11+
id: description
12+
attributes:
13+
label: Description
14+
description: A clear description of the bug.
15+
placeholder: What happened? What did you expect?
16+
validations:
17+
required: true
18+
19+
- type: textarea
20+
id: reproduce
21+
attributes:
22+
label: Steps to Reproduce
23+
description: Minimal steps to reproduce the behavior.
24+
placeholder: |
25+
1. ark new my-project
26+
2. ark run my-project
27+
3. ...
28+
validations:
29+
required: true
30+
31+
- type: textarea
32+
id: logs
33+
attributes:
34+
label: Logs / Error Output
35+
description: Paste relevant logs or error messages.
36+
render: shell
37+
38+
- type: dropdown
39+
id: model
40+
attributes:
41+
label: LLM Backend
42+
options:
43+
- Claude
44+
- Gemini
45+
- Codex
46+
47+
- type: input
48+
id: python-version
49+
attributes:
50+
label: Python Version
51+
placeholder: "3.10"
52+
53+
- type: input
54+
id: os
55+
attributes:
56+
label: Operating System
57+
placeholder: "Ubuntu 22.04"

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Feature Request
2+
description: Suggest a new feature or improvement
3+
labels: ["enhancement"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Have an idea to make ARK better? We'd love to hear it!
9+
10+
- type: textarea
11+
id: problem
12+
attributes:
13+
label: Problem
14+
description: What problem does this feature solve?
15+
placeholder: I'm always frustrated when...
16+
validations:
17+
required: true
18+
19+
- type: textarea
20+
id: solution
21+
attributes:
22+
label: Proposed Solution
23+
description: How should this work?
24+
validations:
25+
required: true
26+
27+
- type: textarea
28+
id: alternatives
29+
attributes:
30+
label: Alternatives Considered
31+
description: Any other approaches you've considered?
32+
33+
- type: dropdown
34+
id: area
35+
attributes:
36+
label: Area
37+
options:
38+
- Pipeline (paper/research loop)
39+
- CLI
40+
- Agents
41+
- Telegram
42+
- Compute backends
43+
- Figure generation
44+
- Other

‎.github/pull_request_template.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
## Summary
2+
3+
<!-- Brief description of what this PR does -->
4+
5+
## Changes
6+
7+
-
8+
9+
## Testing
10+
11+
- [ ] `python -m pytest tests/ -x -q` passes
12+
- [ ] Tested manually with a project (if applicable)
13+
14+
## Notes
15+
16+
<!-- Anything reviewers should know? -->

‎.github/workflows/ci.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.9", "3.10", "3.11", "3.12"]
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python ${{ matrix.python-version }}
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: ${{ matrix.python-version }}
23+
24+
- name: Install dependencies
25+
run: |
26+
python -m pip install --upgrade pip
27+
pip install -e ".[paper]"
28+
pip install pytest
29+
30+
- name: Run tests
31+
run: python -m pytest tests/ -x -q

‎.gitignore‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# State files (project-specific, generated at runtime)
2+
state/*.yaml
3+
state/*.md
4+
state/*.json
5+
6+
# Logs
7+
logs/
8+
9+
# Python
10+
__pycache__/
11+
*.pyc
12+
*.pyo
13+
*.egg-info/
14+
dist/
15+
build/
16+
.venv/
17+
venv/
18+
env/
19+
.pytest_cache/
20+
.coverage
21+
htmlcov/
22+
.mypy_cache/
23+
.ruff_cache/
24+
25+
# PID files
26+
projects/*/.pid
27+
28+
# Project configs contain secrets (telegram tokens, paths)
29+
projects/*/config.yaml
30+
31+
# Local environment / database
32+
.env
33+
.env.*
34+
*.db
35+
*.sqlite
36+
*.sqlite3
37+
38+
# OS
39+
.DS_Store
40+
.nfs*
41+
42+
# Temp
43+
*.tmp
44+
*.pptx

‎.gitmodules‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule "materials/references/openclaw"]
2+
path = materials/references/openclaw
3+
url = https://github.com/openclaw/openclaw.git

‎ARCHITECTURE.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# ARK Architecture
2+
3+
## Design Principles
4+
5+
**Core idea**: Trust the AI's judgment; code handles execution and guardrails only.
6+
7+
## Pipeline Overview
8+
9+
```
10+
┌─────────────────────────────────────────────────────────────┐
11+
│ Simplified Pipeline │
12+
├─────────────────────────────────────────────────────────────┤
13+
│ │
14+
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
15+
│ │ Reviewer │───▶│ Planner │───▶│ Execute │ │
16+
│ │ Review │ │ Decide │ │ Run │ │
17+
│ └──────────┘ └────┬─────┘ └──────────┘ │
18+
│ │ │
19+
│ ▼ │
20+
│ Planner outputs YAML: │
21+
│ actions: │
22+
│ - agent: experimenter │
23+
│ task: "..." │
24+
│ - agent: writer │
25+
│ task: "..." │
26+
│ │
27+
│ ┌──────────────────────────────────────────┐ │
28+
│ │ Memory (minimal) │ │
29+
│ │ - scores: [7.0, 7.2, 7.5, ...] │ │
30+
│ │ - is_stagnating() → bool │ │
31+
│ │ - GOAL_ANCHOR (constant) │ │
32+
│ └──────────────────────────────────────────┘ │
33+
│ │
34+
└─────────────────────────────────────────────────────────────┘
35+
```
36+
37+
## Core Components
38+
39+
### 1. Memory System (`memory.py`)
40+
41+
Tracks scores, detects stagnation, and prevents repetitive failures:
42+
43+
```python
44+
class SimpleMemory:
45+
scores: List[float] # Score history (last 20)
46+
best_score: float # Historical best
47+
stagnation_count: int # Consecutive stagnation count
48+
49+
def record_score(score) # Record a score
50+
def is_stagnating() # Stagnation detection
51+
def get_context() # Get context (Goal Anchor + score trends)
52+
```
53+
54+
Additional features:
55+
- **Issue tracking**: Counts how many times each issue reappears across iterations
56+
- **Repair validation**: Verifies that attempted fixes actually resolved the issue
57+
- **Strategy escalation**: Automatically bans ineffective methods and suggests alternatives
58+
- **Meta-debugging**: Triggers diagnostic when the system is stuck
59+
60+
### 2. Goal Anchor
61+
62+
Every agent invocation includes a constant "Goal Anchor" that describes the project's core objectives. This prevents agents from drifting off-topic over many iterations.
63+
64+
The Goal Anchor is project-specific and should be configured per project.
65+
66+
### 3. Planner Agent
67+
68+
The **core decision-maker**. Outputs a structured action plan:
69+
70+
```yaml
71+
actions:
72+
- agent: experimenter
73+
task: "Run perplexity validation experiment"
74+
priority: 1
75+
- agent: writer
76+
task: "Update Section 4.2"
77+
priority: 2
78+
```
79+
80+
### 4. Orchestrator (`orchestrator.py`)
81+
82+
Minimal control flow:
83+
84+
```python
85+
def run_paper_iteration():
86+
# 1. Review
87+
review = run_agent("reviewer")
88+
score = parse_score(review)
89+
memory.record_score(score)
90+
91+
# 2. Stagnation detection
92+
if memory.is_stagnating():
93+
send_notification("Human intervention needed")
94+
95+
# 3. Planner decides + execute
96+
run_planner_cycle(review)
97+
98+
# 4. Visualize + commit
99+
run_figure_phase()
100+
compile_latex()
101+
git_commit()
102+
```
103+
104+
## Agent List (8 agents)
105+
106+
| Agent | Role |
107+
|-------|------|
108+
| reviewer | Reviews and scores the paper |
109+
| planner | Analyzes issues, generates action plan (paper & dev modes) |
110+
| experimenter | Designs, runs, and analyzes experiments |
111+
| researcher | Literature search and experimental result analysis |
112+
| writer | Writes/revises paper sections |
113+
| visualizer | Checks and fixes figure/table quality |
114+
| meta_debugger | System-level diagnosis |
115+
| coder | Implements code changes (dev mode) |
116+
117+
## Deprecated
118+
119+
- `events.py` — Event-driven system (replaced by Planner-based decisions)
120+
- Complex Memory tracking (issues, effective_actions, failed_attempts) — simplified
121+
122+
## File Structure
123+
124+
```
125+
ARK/
126+
├── orchestrator.py # Main loop
127+
├── memory.py # Memory system
128+
├── agents/ # Agent prompt templates
129+
│ ├── reviewer.prompt
130+
│ ├── planner.prompt
131+
│ ├── experimenter.prompt
132+
│ ├── researcher.prompt
133+
│ ├── writer.prompt
134+
│ ├── visualizer.prompt
135+
│ ├── meta_debugger.prompt
136+
│ └── coder.prompt
137+
├── state/ # Runtime state (gitignored)
138+
│ ├── action_plan.yaml
139+
│ ├── latest_review.md
140+
│ ├── findings.yaml
141+
│ └── memory.yaml
142+
└── logs/ # Execution logs (gitignored)
143+
```

0 commit comments

Comments
 (0)
⚡