<div align="center">
🪙 SOLVENT
자체 비용 대비 각 작업을 견적화하고, Stripe를 통해 대금을 받고, 지출 정책 내에서 자체 공급업체 청구서를 결제하며, 손해를 볼 작업은 거절하는 작은 연구 사업을 운영하는 Python 에이전트입니다.
CI
PyPI
Hugging Face Space
Python 3.10+
Zero dependencies
License: MIT
Hackathon
Stars
빠른 시작 (Quick Start) · 작동 방식 (How It Works) · 실시간 데모 (Live Demo) · 실제 구현하기 (Make It Real)
SOLVENT in a terminal: the margin gate declines an $8 job with a counter-offer, then the offline demo runs five jobs end to end
<sub>API 키나 네트워크 접속 없이 실제 CLI에서 녹화된 내용입니다. Stripe 결제 링크와 Nemotron 출력은 내장된 오프라인 스텁(stub)이며, 달러 금액은 시뮬레이션된 것입니다.</sub>
▶ 브라우저에서 사용해 보기: 설치나 키 설정 없이 Pyodide에서 실행되는 실제 패키지입니다.
The SOLVENT Hugging Face Space: five jobs run, J3 declined with a $15 counter-offer, and a simulated P&L snapshot
<sub>최종 현금 잔고를 포함하여 모든 달러 금액은 시뮬레이션된 것입니다.</sub>
</div
기본적으로 데모가 실행됩니다. 키가 설정되지 않은 경우, solvent는 전체 루프의 오프라인, 제로-키(zero-key) 시뮬레이션을 실행합니다. 데모에 표시된 달러 금액은 실제 수익이 아닌 예시적인 수치입니다. Stripe 테스트 모드 결제 링크와 실시간 NVIDIA Nemotron은 선택 사항입니다. 실제 구현하기를 참조하세요.
🚀 빠른 시작 (Quick Start)
30초 만에. API 키 불필요. Python 3.10 이상만 필요합니다.
pipx install solvent-agent # 또는: pip install solvent-agent
solvent --no-onboard # 오프라인 데모 배치를 실행합니다 (첫 실행 마법사 건너뛰기)
solvent finance # 손익계산서, 단위 경제학(unit economics), 운영 자금(runway)
그리고 데모가 출력하는 대시보드 경로(pip/pipx 설치의 경우 ~/.solvent/treasury_dashboard.html, 또는 환경 변수 $SOLVENT_HOME을 설정한 경우 그 아래)를 엽니다.
마진 게이트(margin gate)만 단독으로 사용해 보세요. 이 건식 실행(dry run)은 $8 규모의 주문을 거절하고, 마진 하한선(margin floor)을 충족하는 반대 제안을 반환합니다:
solvent quote "Edge-AI in industrial robotics" --budget 8
| 명령어 | 기능 |
|---|
solvent | 배치 데모 (첫 실행 시 온보딩 마법사 작동; --no-onboard로 건너뛰기) |
| ... | |
또는 소스 코드 체크아웃에서 실행합니다:
git clone https://github.com/ianalloway/solvent-agent.git
cd solvent-agent
python3 run_demo.py
...
이 데모는 마진 게이팅, 시뮬레이션된 Stripe 결제, Nemotron 이행(오프라인 스텁), 가드레일 심사, 실시간 손익계산서(P&L)를 거치는 5개의 샘플 분석가 작업 배치(4개 수락, 1개 마진 게이트에 의해 거절)를 약 30초 만에 실행합니다.
타사 기능은 **선택적 추가 기능(opt-in extras)**이므로, 필요한 것만 설치하세요:
pip install "solvent-agent[stripe]"
pip install "solvent-agent[serve]"
pip install "solvent-agent[telegram]"
...
소스 코드 체크아웃에서 실행할 경우, 런타임 데이터는 <repo>/data 아래에 유지됩니다. 다른 곳에 설치하는 경우, SOLVENT는 site-packages 내부가 아닌 ~/.solvent에 작성합니다. 이 둘 중 하나는 SOLVENT_HOME=/path/to/dir로 재정의할 수 있습니다.
첫 실행: 짧은 온보딩 마법사(onboarding wizard)가 모델, 상호작용 모드, Stripe 테스트 모드 활성화 여부를 선택하도록 요청합니다. 환경 설정은 .solvent/config.json에 저장되며 커밋되지 않습니다.
핵심 아이디어 (The Big Idea)
대부분의 에이전트는 돈을 쓸 수 있습니다. 하지만 거의 아무것도 비즈니스로 운영될 수는 없습니다.
SOLVENT는 전체 루프를 완성합니다:
고객이 Stripe에 지불 → 에이전트가 수익을 얻음 → 에이전트가 작업을 이행함 → 에이전트가 자체 공급업체 청구서를 지불함 → 손익계산서(P&L) 기록 → 대차대조표(balance sheet) 증가
모든 작업은 시작하기 전에 **수익성 게이트(profit-gated)**를 거칩니다. 수익성이 낮은 작업은 Stripe에 영향을 주지 않고 거절됩니다. 공급업체 결제는 NemoClaw 스타일의 정책 샌드박스(policy sandbox)로 검열되므로, 에이전트는 이미 수집한 수익 범위 내에서만 비용을 지출합니다.
📊 데모 (The Demo)
실행 후, CLI가 대시보드 경로를 출력합니다. 브라우저에서 열어보세요:
open treasury_dashboard.html
xdg-open treasury_dashboard.html
SOLVENT Treasury Dashboard — live P&L, job cards, resource allocation, transaction log
일반적인 오프라인 데모 배치 (시뮬레이션된 실행에서 가져온 예시 숫자 — 실제 수익 아님):
| 지표 (Metric) | 데모 값 (Demo value) |
|---|
| 수익 (Revenue) | $348.00 |
| ... | |
<sub style="font-size: 0.9em;">solvent --no-onboard를 사용하여 API 키가 없는 새로운 SOLVENT_HOME 환경에서 실행한 경우입니다. 99.4% 마진은 게이트의 87–92% 예측치보다 높은데, 이는 오프라인 이행(offline fulfilment)이 시장 데이터나 웹 검색 호출을 하지 않기 때문입니다 (참고 #79).</sub> | |
⚙️ 작동 방식 (How It Works)
inbound job
│
▼
...```
작업 파이프라인은 이행 전에 결제를 확인하고, 공급업체 지출을 구성된 지출 정책(spend policy)과 비교 검열합니다. 견적에는 예상 비용이 사용되므로, 승인된 견적은 실현된 수익의 보장이 아니라 예측된 마진입니다. 원장(ledger) 및 비용 조정 보고서(cost-calibration reports)는 실제 지출이 해당 예상치와 어떻게 비교되는지 보여줍니다.
---
## 🏗️ 아키텍처 (Architecture)
| 계층 (Layer) | 기술 (Technology) | 파일 (File) |
|---|---|---|
| **분석가 / 추론 (Analyst / reasoning)** | NVIDIA Nemotron (Llama-3.1-Nemotron-Ultra) | `solvent/nemotron.py` |
| ... |
**핵심 설계 선택 사항:**
- **구조적 수익성(Structural profitability)** — `pricing.py`에서 견적을 내기 전에 단위 비용을 계산합니다. 마진이 하한선(floor)보다 낮으면 해당 작업은 Stripe에 도달하지 않습니다.
- **지출 정책(Spend policy)** — `guardrails.py`가 공급업체 허용 목록(vendor allowlist), 거래별 한도(per-transaction cap), 누적 24시간 예산(rolling 24h budget), 최소 현금 보유액(minimum cash reserve), 그리고 음의 ROI 금지 규칙(no-negative-ROI rule)을 강제합니다.
- **오프라인 우선(Offline-first)** — API 키가 없으면 데모는 결정론적 스텁(deterministic stubs)으로 실행됩니다. 라이브 추론 및 실제 결제 링크를 사용하려면 `NVIDIA_API_KEY`와 `STRIPE_API_KEY=sk_test_...`를 추가하세요.
- **감사 추적(Audit trail)** — 모든 `cs_...` 체크아웃 세션 ID와 `pi_...` PaymentIntent ID는 이행이 시작되기 전에 원장(ledger)에 기록됩니다.
리소스 가격은 `.solvent/pricing_overrides.json`에서 재정의할 수 있습니다. 값은 센트 단위의 비용이어야 하며 유한하고 음수가 아닌 숫자여야 합니다. `0`은 무료 리소스에 대해 유효합니다. (음수 값, 부울, `NaN`, 무한대를 포함하여) 유효하지 않은 항목은 기본 설정된 가격을 유지합니다. 동일 파일 내의 유효한 항목은 여전히 적용됩니다.
---
## 🎮 실행 모드(Running Modes)
### 배치 데모(Batch demo) (기본값 — 심사위원에게 가장 적합)
```bash
python3 run_demo.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
5개의 사전 로드된 작업이 있습니다(4개 승인, 1개 거절). 약 30초 소요. 마진 게이팅, Stripe 수익/지출, Nemotron 이행 및 가드레일 작동을 보여줍니다.
대화형(Interactive) — 사용자의 자체 작업
python3 run_demo.py --interactive
프롬프트에서 연구 주제와 클라이언트 예산을 입력하세요. 에이전트는 실시간으로 견적을 내고, 비용을 지불하며, 이행하고, 손익계산서(P&L)를 기록합니다. 종료할 때까지 계속 진행하세요.
세션 중간에 자금 추가하기
python3 run_demo.py --seed 500
python3 run_demo.py --keep-balance
대화형 모드에서, /fund 200을 프롬프트에 입력하여 라이브 재무 보유액에 $200를 입금할 수 있습니다.
프로그래밍 방식(Programmatic)
from solvent.agent import Solvent
from solvent.jobs import SAMPLE_JOBS
...
운영 모드(Production mode) (웹훅 + 비동기 워커)
pip install "solvent-agent[serve]"
export SOLVENT_DASHBOARD_TOKEN=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')
...
슬래시(/)에 호스팅된 대시보드에는 채팅 패널(직접 입력하거나 Web Speech API를 사용하여 마이크 사용)과 Server-Sent Events( /api/events)를 통한 실시간 금고 업데이트가 포함되어 있습니다. 대시보드/제어 경로는 상태 데이터를 노출하거나 채팅을 Nemotron 에이전트 루프를 통해 라우팅하기 전에 ?token=... 또는 X-Solvent-Dashboard-Token 헤더를 통해 SOLVENT_DASHBOARD_TOKEN을 요구합니다.
Stripe 웹훅 설정, SMTP 전송 및 조정(reconciliation)에 대해서는 docs/PRODUCTION.md를 참조하십시오.
운영 (Operations)
python3 -m solvent quote "AI inference chips, 2026" --budget 49
python3 -m solvent backlog
python3 -m solvent guardrails
...
finance (별칭: report)는 금고 원장(treasury ledger)을 비즈니스가 관리하는 수치로 변환합니다. 이 수치에는 수익/비용/순이익(revenue/cost/net-margin), 작업당 평균 이익, 현금 런웨이(runway) — 남은 소진 일수(days of burn remaining), 또는 에이전트가 자체 자금을 확보하면 현금 흐름 양(+) 상태, 일/주/월별로 분류된 순 손익 추세(net-P&L trend), 그리고 잔액 예측(balance forecast) (일일 변동성(daily volatility)에 따라 폭이 커지는 최적/최악 범위가 포함된 중앙 투영치)가 포함됩니다. 손익계산서(income statement), 런웨이, 추세, 예측은 또한 HTML 대시보드의 재무제표(Financial Statement) 패널로 표시됩니다.
🧭 상업적 판단 (Commercial Judgement)
돈의 순환 고리를 스크립트처럼 작동하는 것이 아니라 가게처럼 행동하도록 만드는 세 가지 요소가 있습니다.
역제안(Counter-offers) — 거절은 협상 포지션이다
마진 게이트는 여전히 수익성이 없는 작업은 거부하지만, 더 이상 단순히 '아니오'라고만 말하지 않습니다. 모든 거절에는 에이전트가 수락할 수 있는 거래가 담겨 있습니다:
python3 -m solvent quote "Edge-AI in industrial robotics" --budget 8 --tokens 30000
Projected margin $-4.33 (-54.1%) floor 35.0%
Verdict DECLINE — order $8 below minimum order size $15
...
선호 순서에 따라 두 가지 형태가 있습니다: 고객의 기존 예산으로 구매할 수 있는 더 좁은 범위(시장 데이터 풀을 적게 요청하는 것부터 — 이것이 가장 비싼 자원입니다) 또는, 판매 가능한 범위가 없을 경우 마진 하한선을 넘기는 최저 가격. 제안은 거절 옆에 counter_offer 이벤트로 방출되며, 따라서 터미널, Telegram, job API 등 모든 채널에서 이를 인용할 수 있습니다.
solvent quote는 전체 게이트를 드라이 런(dry run)으로 실행합니다: 금고에 아무것도 쓰지 않으며, Stripe 호출도 이루어지지 않고, 스크립트가 판결에 따라 제어할 수 있도록 거절 시 종료 코드는 1입니다.
지출 정책 (Spend policy) — 단순히 금액이 아니라 돈이 움직이는 방식을 제한합니다
가드레일(guardrails)은 지출 분포를 형성하는 두 가지 규칙을 추가했습니다:
| 규칙 | 방지하는 것 |
|---|
| 벤더별 24시간 한도 (Per-vendor 24h cap) | 하나의 벤더가 손상되거나, 가격 책정이 잘못되었거나, 단순히 버그가 있어 하루 전체 예산을 흡수하는 것을 방지합니다. |
| 지출 속도 (Spend velocity) | 금고를 고갈시키기 훨씬 전에 짧은 주기로 지불을 시작하는 이행 루프(fulfilment loop)를 방지합니다. |
제한 사항은 코드를 건드리지 않고도 운영자가 .solvent/spend_policy.json을 통해 조정할 수 있습니다 (잘못된 파일은 정책을 확대하는 대신 무시됩니다):
{
"daily_budget_cents": 50000,
"per_vendor_daily_cents": 8000,
...
}
.solvent 설정 디렉토리는 해결된 런타임 홈 내부에 있습니다: 기본적으로 소스 체크아웃이거나, $SOLVENT_HOME으로 설정된 경우입니다. 활성 지출 정책 경로를 보려면 solvent guardrails 또는 solvent doctor를 실행하십시오. 만약 이전 설치본이 .solvent 파일을 다른 시작 디렉토리에 유지했다면, 업그레이드하기 전에 이 해결된 디렉토리로 이동시키십시오.
python3 -m solvent guardrails는 현재 적용 중인 정책, 각 롤링 윈도우에서 사용된 금액, 한도 대비 벤더별 노출 정도, 그리고 정책이 차단한 모든 지출을 출력합니다.
지출 통제 (Spending controls) — 작업별 예산 및 인간 승인
추가로 두 가지 규칙이 일일/벤더별 및 속도 제한 위에 놓여 있습니다. 이 두 규칙 모두 Stripe 호출이 이루어지기 전에 동일한 결정론적 가드레일 검사 내에서 실행되며, 둘 다 폐쇄적으로 실패(fail closed)합니다.
