Skip to content

Commit 77d6e50

Browse files
faresrafat3faresrafat3
committed
Initial release: Epistemic Forge — ARSENAL L0–L6 research kit
Original multi-domain package mapping Prompt Report routing, APE/OPRO instructions, meta experts, ToT/LATS search, Self-Refine polish, Reflexion + Voyager memory, and staged artifact export. Includes CLI, tests, and demos.
0 parents  commit 77d6e50

32 files changed

Lines changed: 2019 additions & 0 deletions

‎.github/workflows/tests.yml‎

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

‎.gitignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
__pycache__/
2+
*.py[cod]
3+
*.egg-info/
4+
.eggs/
5+
dist/
6+
build/
7+
.pytest_cache/
8+
.mypy_cache/
9+
.ruff_cache/
10+
.venv/
11+
venv/
12+
.env
13+
runs/
14+
forge_output/
15+
.DS_Store
16+
*.ipynb_checkpoints/

‎CONTRIBUTING.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Contributing
2+
3+
1. Fork and branch from `main`.
4+
2. `pip install -e ".[dev]"`
5+
3. Add tests for new experts or pipeline layers.
6+
4. `pytest -q`
7+
5. Open a PR with a clear ARSENAL-layer note (L0–L6) if you change routing or memory.
8+
9+
## Design rule
10+
11+
Prefer **explicit claims + limits** over flashy ungrounded generation. This project is an epistemic scaffold.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Fares Rafat
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Epistemic Forge
2+
3+
**An ARSENAL-powered kit for turning messy questions into claim lattices, dialectic briefs, freelance scopes, and Kaggle notebook spines.**
4+
5+
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
6+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7+
[![Built with ARSENAL](https://img.shields.io/badge/built%20with-ARSENAL%20L0--L6-purple.svg)](https://github.com/faresrafat3/arsenal-unified-master-pipeline)
8+
9+
Epistemic Forge is a **local-first Python package** (no paid API required) that implements a faithful, practical slice of the [ARSENAL](https://github.com/faresrafat3/arsenal-unified-master-pipeline) unified agent pipeline:
10+
11+
| Layer | ARSENAL idea | In this repo |
12+
|---|---|---|
13+
| **L0** | Technique routing | Domain → families + layer flags |
14+
| **L1** | APE + OPRO | Seed instructions + score-history climb |
15+
| **L2** | Meta conductor | Claim / dialectic / writing / freelance / Kaggle experts |
16+
| **L3** | ToT (+ LATS cascade) | Beam search over framings; optional rollout polish |
17+
| **L4** | Self-Refine | Multi-aspect critique → revise loop |
18+
| **L5** | Reflexion + Voyager | Verbal trial memory + skill library |
19+
| **L6** | Stage shell | Artifacts, executive summary, peer-review rubric |
20+
21+
> Novel angle: a **claim lattice** as the shared intermediate representation across philosophy, research writing, freelancing, and Kaggle planning—so epistemic humility travels with the deliverable.
22+
23+
---
24+
25+
## Install
26+
27+
```bash
28+
git clone https://github.com/faresrafat3/epistemic-forge.git
29+
cd epistemic-forge
30+
pip install -e ".[dev]"
31+
```
32+
33+
## Quick start (CLI)
34+
35+
```bash
36+
epistemic-forge \
37+
--title "Predictive minds and blame" \
38+
--question "If the brain is a prediction machine, what happens to moral responsibility?" \
39+
--domain philosophy \
40+
--keywords "predictive processing,agency,responsibility" \
41+
--out runs/philosophy_demo
42+
```
43+
44+
```bash
45+
epistemic-forge \
46+
--title "Imbalanced tabular baseline" \
47+
--question "What is an honest baseline plan for a noisy imbalanced Kaggle table?" \
48+
--domain kaggle \
49+
--keywords "imbalance,cv,leakage,baseline" \
50+
--out runs/kaggle_demo
51+
```
52+
53+
```bash
54+
epistemic-forge \
55+
--title "Climate-tech research sprint" \
56+
--question "How do I scope a 2-week research sprint for a climate-tech founder?" \
57+
--domain freelance \
58+
--keywords "sprint,scope,founder" \
59+
--out runs/freelance_demo
60+
```
61+
62+
## Python API
63+
64+
```python
65+
from epistemic_forge import run_pipeline
66+
from epistemic_forge.io.export import export_result
67+
68+
result = run_pipeline(
69+
title="Epistemic freelancing",
70+
question="How can freelancers package uncertain research without overclaiming?",
71+
domain="hybrid",
72+
keywords=["freelance", "research", "claims"],
73+
)
74+
print(result.final_score, result.peer_review["verdict"])
75+
export_result(result, "runs/hybrid_demo")
76+
```
77+
78+
## What you get in `--out`
79+
80+
| File | Purpose |
81+
|---|---|
82+
| `executive_summary.md` | One-pager |
83+
| `research_memo.md` | Full lattice + framing + limits + actions |
84+
| `client_brief.json` | Freelance pack (when domain fits) |
85+
| `kaggle_spine.md` | Notebook spine (when domain fits) |
86+
| `result.json` | Full machine-readable trace (route, trials, search nodes) |
87+
| `MANIFEST.json` | Score, review, file list |
88+
89+
## Domains
90+
91+
`research` · `philosophy` · `writing` · `freelance` · `kaggle` · `hybrid`
92+
93+
## Why this is not “another prompt dump”
94+
95+
1. **Executable pipeline** with tests (`pytest`)
96+
2. **Shared IR** (claims) across domains
97+
3. **Explicit ARSENAL mapping** with a run log: [`docs/ARSENAL_RUN_LOG.md`](docs/ARSENAL_RUN_LOG.md)
98+
4. **Memory**: verbal lessons + reusable skills
99+
5. **Publishable packaging**: `pyproject.toml`, CLI entrypoint, MIT license
100+
101+
## Project layout
102+
103+
```text
104+
epistemic_forge/
105+
pipeline/ # L0–L6 orchestration
106+
experts/ # L2 specialist modules
107+
memory/ # Reflexion + skill library
108+
io/ # export
109+
data/samples/ # demo specs
110+
tests/
111+
docs/ARSENAL_RUN_LOG.md
112+
examples/
113+
```
114+
115+
## Tests
116+
117+
```bash
118+
pytest -q
119+
```
120+
121+
## Design principles (from ARSENAL)
122+
123+
1. Router first
124+
2. Optimize the instruction (APE / OPRO cascade)
125+
3. Conduct via experts
126+
4. Search framings deliberately (ToT; cascade when code-like)
127+
5. Refine with multi-aspect feedback
128+
6. Remember failures and skills
129+
7. Ship staged artifacts + review
130+
131+
## Related work
132+
133+
- ARSENAL master pipeline: https://github.com/faresrafat3/arsenal-unified-master-pipeline
134+
- Extractions archive: https://github.com/faresrafat3/llm-agent-research-extractions
135+
136+
## License
137+
138+
MIT — see [LICENSE](LICENSE).
139+
140+
## Disclaimer
141+
142+
Epistemic Forge **scaffolds thinking and packaging**. It does not replace domain expertise, human ethics review, or competition rules. Treat outputs as **provisional** claims with explicit limits.

‎docs/ARSENAL_RUN_LOG.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# ARSENAL Run Log — Building Epistemic Forge
2+
3+
This project was **designed by applying** the ARSENAL L0–L6 pipeline (not merely mentioned).
4+
5+
Source doctrine: https://github.com/faresrafat3/arsenal-unified-master-pipeline
6+
7+
---
8+
9+
## L0 — Technique Router (Prompt Report)
10+
11+
**Task:** Build an original, publishable GitHub project spanning research / philosophy / writing / Python / Kaggle / freelancing.
12+
13+
**Route chosen:**
14+
- Families: ICL, Thought Generation, Decomposition, Self-Criticism, Agents, Answer Engineering, Prompt Optimization
15+
- Activate: meta, refine, reflexion, stages, tot, optional lats/voyager/opro by domain
16+
- Rationale: hybrid epistemic tooling needs structure + critique + packaging + optional skills
17+
18+
---
19+
20+
## L1 — Instruction Optimizer (APE → OPRO cascade)
21+
22+
**APE-style seeds considered:**
23+
1. Pure philosophy dialectic CLI
24+
2. Kaggle-only notebook generator
25+
3. Freelance proposal generator
26+
4. **Hybrid claim-lattice forge with multi-domain experts** ← selected
27+
28+
**OPRO-style climb:** scored seeds by novelty × multi-domain fit × implementability without paid APIs × ARSENAL fidelity.
29+
**Winning instruction:**
30+
31+
> Build a local-first Python package that runs an ARSENAL-mapped pipeline to turn a question into a claim lattice, dialectic, client pack, and Kaggle spine—with verbal + skill memory across trials.
32+
33+
---
34+
35+
## L2 — Meta Conductor (experts)
36+
37+
Dispatched virtual experts:
38+
- Claim lattice designer
39+
- Dialectic / philosophy designer
40+
- Freelance packaging designer
41+
- Kaggle baseline designer
42+
- Software architecture (package/tests/CLI)
43+
44+
Integrated into modules under `epistemic_forge/experts/` and `pipeline/`.
45+
46+
---
47+
48+
## L3 — Search (ToT + cascade)
49+
50+
Explored framings:
51+
- Library of prompts only (rejected: weak product)
52+
- Full LLM-hosted agent (rejected: API cost / non-reproducible CI)
53+
- **Deterministic ARSENAL-faithful pipeline + exportable artifacts** (selected)
54+
55+
Best thought: *light epistemic scaffold that ships artifacts without false precision.*
56+
57+
---
58+
59+
## L4 — Refine (Self-Refine)
60+
61+
Multi-aspect passes on README, API surface, tests:
62+
- clarity, structure, humility, actionability, domain fit
63+
- Added run log, examples, peer-review style packaging
64+
65+
---
66+
67+
## L5 — Memory
68+
69+
- **Reflexion:** trial log + lessons when score low
70+
- **Voyager-style:** built-in skill library + success skill registration
71+
72+
---
73+
74+
## L6 — Stages / production
75+
76+
- Stage 1: core models + router + L1
77+
- Stage 2: experts + search + refine
78+
- Stage 3: CLI + export + tests
79+
- Stage 4: docs, examples, license, CI-friendly pytest
80+
- Peer review checklist in README
81+
82+
---
83+
84+
## Outcome
85+
86+
Public package: **Epistemic Forge** — reproducible, tested, multi-domain.

‎epistemic_forge/__init__.py‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
"""Epistemic Forge — ARSENAL-powered research & writing kit."""
2+
3+
from .pipeline.arsenal_run import ArsenalRun, run_pipeline
4+
from .models import Claim, ForgeResult, ProjectSpec
5+
6+
__version__ = "0.1.0"
7+
__all__ = [
8+
"ArsenalRun",
9+
"run_pipeline",
10+
"Claim",
11+
"ForgeResult",
12+
"ProjectSpec",
13+
"__version__",
14+
]

‎epistemic_forge/cli.py‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
"""CLI for Epistemic Forge."""
2+
3+
from __future__ import annotations
4+
5+
import argparse
6+
import json
7+
from pathlib import Path
8+
9+
from epistemic_forge.io.export import export_result
10+
from epistemic_forge.pipeline.arsenal_run import run_pipeline
11+
12+
13+
def build_parser() -> argparse.ArgumentParser:
14+
p = argparse.ArgumentParser(
15+
prog="epistemic-forge",
16+
description="ARSENAL-powered epistemic research & writing forge",
17+
)
18+
p.add_argument("--title", required=True, help="Project title")
19+
p.add_argument("--question", required=True, help="Core research/client question")
20+
p.add_argument(
21+
"--domain",
22+
default="hybrid",
23+
choices=["research", "philosophy", "writing", "freelance", "kaggle", "hybrid"],
24+
)
25+
p.add_argument("--audience", default="technical peer / client")
26+
p.add_argument("--keywords", default="", help="Comma-separated keywords")
27+
p.add_argument("--constraints", default="", help="Comma-separated constraints")
28+
p.add_argument("--trials", type=int, default=3)
29+
p.add_argument("--out", default="forge_output", help="Output directory")
30+
p.add_argument("--json-stdout", action="store_true", help="Print full JSON result")
31+
return p
32+
33+
34+
def main(argv=None) -> int:
35+
args = build_parser().parse_args(argv)
36+
keywords = [k.strip() for k in args.keywords.split(",") if k.strip()]
37+
constraints = [c.strip() for c in args.constraints.split(",") if c.strip()]
38+
result = run_pipeline(
39+
title=args.title,
40+
question=args.question,
41+
domain=args.domain,
42+
audience=args.audience,
43+
keywords=keywords,
44+
constraints=constraints,
45+
max_trials=args.trials,
46+
)
47+
out = export_result(result, args.out)
48+
print(f"Epistemic Forge complete → {out.resolve()}")
49+
print(f"Score={result.final_score:.3f} review={result.peer_review.get('verdict')}")
50+
print(f"Route L1={result.route.l1_mode} L3={result.route.l3_mode}")
51+
print(f"Families: {', '.join(result.route.families)}")
52+
if args.json_stdout:
53+
print(json.dumps(result.to_dict(), indent=2, ensure_ascii=False)[:5000])
54+
return 0
55+
56+
57+
if __name__ == "__main__":
58+
raise SystemExit(main())

0 commit comments

Comments
 (0)