hive-corp 0.1.0__tar.gz

hive_corp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra dashboard --extra matrix
+
+      - name: Ruff
+        run: uv run --extra dev --extra dashboard --extra matrix ruff check .
+
+      - name: Pyright
+        run: uv run --extra dev --extra dashboard --extra matrix pyright
+
+      - name: Pytest
+        run: uv run --extra dev --extra dashboard --extra matrix pytest
+
+      - name: Benchmark smoke
+        run: uv run --extra dev --extra dashboard --extra matrix hive benchmark --validate-suite all --json --artifact benchmarks/latest/validation-suite.json
+
+      - name: Upload benchmark artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-validation-suite
+          path: benchmarks/latest/validation-suite.json

hive_corp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hive_corp-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# Node
+node_modules/
+.next/
+out/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.local
+
+# SQLite
+*.db
+*.db-wal
+*.db-shm
+
+# Hive runtime
+.hive/
+worktrees/
+company.yaml

hive_corp-0.1.0/CLAUDE.md

@@ -0,0 +1,355 @@
+# Hive Corp — Project Instructions
+
+## What This Is
+
+Autonomous AI company platform. Users found a company through conversation,
+hire AI agents as employees, and the company runs on its own.
+The user is the CEO, not a developer using a tool.
+
+## Core Architecture Decisions
+
+1. **Agents are data, not processes.** Agent = config in DB (mem ~0).
+   Worker = execution slot (fixed-size pool). 100 agents share 3 workers.
+2. **Nothing is predefined.** No fixed departments, roles, or business models.
+   The company starts from a conversation and grows via Growth Engine triggers.
+3. **CLI-first.** Phase 1 is CLI-only. Matrix/Discord are Phase 3+.
+4. **Token efficiency is a core feature**, not an afterthought.
+   Proven techniques from Phase 1, experimental from Phase 4+.
+   All LLM calls logged to token_logs. No untracked LLM calls.
+
+## Key Documents
+
+- `docs/ARCHITECTURE.md` — full system design
+- `docs/ROADMAP.md` — phased development plan
+
+## Code Rules
+
+- Python 3.14+, strict pyright, ruff for lint/format
+- `@dataclass(slots=True)` for all data classes
+- `Protocol` for interfaces (not ABC)
+- `async/await` throughout (asyncio)
+- Type hints on all function signatures
+- `pathlib.Path` (not os.path)
+- `match/case` for 3+ branches
+- No `any` type, no `as` assertion, no `typing.Optional`
+
+## Common Mistakes — 반복하지 말 것
+
+실제 개발 중 ruff/pyright에 반복적으로 걸린 패턴들. 작성 시점에서 지킬 것.
+
+### 1. 함수 내 import 금지 (PLC0415)
+```python
+# ❌
+async def fire(self) -> bool:
+    from time import time  # PLC0415
+    ...
+
+# ✅ 파일 상단에서 import
+from time import time
+```
+순환 import가 아닌 이상 함수 내 import를 쓰지 않는다.
+
+### 2. 테스트에서 호출할 메서드는 public으로 (reportPrivateUsage)
+```python
+# ❌ 테스트에서 접근 불가
+def _classify(self, approval): ...
+
+# ✅ 테스트 가능성을 고려
+def classify(self, approval): ...
+```
+`_prefix`는 정말 외부에서 호출할 일이 없는 내부 구현에만 사용.
+
+### 3. `type: ignore` 복붙 금지 (reportUnnecessaryTypeIgnoreComment)
+```python
+# ❌ 이전 파일에서 복사한 불필요한 주석
+return float(row["total"])  # type: ignore[index]
+
+# ✅ 먼저 pyright를 돌려보고 필요할 때만
+return float(row["total"])
+```
+`type: ignore`는 pyright가 실제로 에러를 내는 경우에만 추가.
+
+### 4. async 함수에서 blocking I/O 금지 (ASYNC240)
+```python
+# ❌ async 함수에서 Path.exists() 직접 호출
+async def check() -> None:
+    if not Path(DB_PATH).exists(): ...
+
+# ✅ sync 헬퍼로 분리
+def _db_exists() -> bool:
+    return Path(DB_PATH).exists()
+```
+
+### 5. 테스트에서 하드코딩 시크릿 주의 (S105)
+```python
+# ❌
+assert token == "secret123"  # S105 경고
+
+# ✅ noqa 명시 또는 변수로 분리
+assert token == "secret123"  # noqa: S105
+```
+
+### 6. `datetime.UTC` alias 사용 (UP017)
+```python
+# ❌ Python 3.11 이전 스타일
+from datetime import timezone
+now = datetime.now(tz=timezone.utc)
+
+# ✅ Python 3.11+ alias
+from datetime import UTC
+now = datetime.now(tz=UTC)
+```
+`datetime.timezone.utc` 대신 `datetime.UTC`를 사용한다.
+
+### 7. FastAPI `Depends()` 기본값 (B008)
+```python
+# ❌ ruff B008 경고
+async def handler(db: Database = Depends(get_db)) -> None: ...
+
+# ✅ noqa 명시 (FastAPI 공식 패턴)
+async def handler(db: Database = Depends(get_db)) -> None:  # noqa: B008
+    ...
+```
+FastAPI의 `Depends()`는 함수 기본값에 쓰는 것이 공식 패턴이므로 `noqa: B008`로 허용.
+
+## Project Structure
+
+```
+src/hive/
+  cli/          — CEO CLI (click + rich)
+  core/         — Domain models (Company, Agent, Task, Project)
+  founding/     — Conversational founding engine
+  growth/       — Growth triggers
+  ceo/          — CEO Gateway (escalation logic)
+  memory/       — Company Memory (SQLite FTS5)
+  budget/       — Token budget controller + model router
+  runtime/      — Worker Pool + Agent Registry + Scheduler
+  office/       — Office Protocol (cli, matrix, discord)
+  storage/      — SQLite database + migrations
+  api/          — FastAPI dashboard API
+```
+
+## Build & Run
+
+```bash
+uv sync --extra dev      # Install deps (with dev tools)
+uv run hive found        # Found a company
+uv run hive status       # Company status
+uv run pytest            # Run tests
+uv run pytest --memray   # Run tests with memory profiling
+ruff check --fix && ruff format   # Lint
+pyright                  # Type check
+```
+
+## Pre-commit Hooks (lefthook)
+
+commit 시 자동 실행 (병렬, ~2초):
+- `ruff check` — lint
+- `ruff format --check` — format 검증
+- `pyright` — 타입 체크
+
+push 시 자동 실행:
+- `pytest` — 전체 테스트
+
+## Token Efficiency — Must Follow
+
+- Never call LLM for something code can do (standups, status, routing, git ops)
+- Agent-to-agent communication uses structured messages (token 0), not natural language
+- Only CEO-facing messages use natural language
+- Use `cache_control` on system prompts (Anthropic prompt caching)
+- Log every LLM call to `token_logs` with `optimization_flags`
+- Task-based model routing: Haiku for simple, Sonnet for code, Opus for architecture only
+
+## Memory Management — Must Follow
+
+메모리 누수는 장시간 실행되는 Agent Runtime에서 치명적이다.
+코드 작성 시 아래 규칙을 반드시 따른다.
+
+### 리소스 정리 원칙
+
+```python
+# ✅ async 리소스는 반드시 async with (DB, HTTP, file)
+async with aiosqlite.connect(path) as conn:
+    ...
+
+async with httpx.AsyncClient() as client:
+    response = await client.post(...)
+
+# ✅ subprocess는 finally에서 kill 보장
+try:
+    proc = await asyncio.create_subprocess_exec(...)
+    await proc.communicate()
+finally:
+    if proc.returncode is None:
+        proc.kill()
+        await proc.wait()
+
+# ✅ 캐시는 반드시 크기 제한
+from functools import lru_cache
+@lru_cache(maxsize=128)  # 무제한(maxsize=None) 금지
+
+# ✅ 객체 참조가 약해야 하면 WeakRef
+from weakref import WeakValueDictionary
+agent_cache: WeakValueDictionary[str, AgentConfig] = WeakValueDictionary()
+```
+
+### 금지 패턴
+
+```python
+# ❌ context manager 없이 리소스 열기
+conn = await aiosqlite.connect(path)  # close 누락 위험
+
+# ❌ 무한 증가 컬렉션
+results: list[Result] = []
+async for item in stream:
+    results.append(item)  # OOM 위험 → generator로 yield
+
+# ❌ 전역 변수에 큰 객체 캐싱
+_cache: dict[str, bytes] = {}  # GC 불가, 무한 증가
+
+# ❌ 이벤트 리스너 등록 후 미해제
+```
+
+### 모듈별 위험 지점
+
+| 모듈 | 위험 | 대응 |
+|------|------|------|
+| runtime/pool | Worker subprocess 좀비 | finally에서 kill + wait |
+| runtime/scheduler | Task queue 무한 증가 | 완료 태스크 주기적 정리 |
+| storage/database | Connection 미반환 | context manager 강제 |
+| memory/store | FTS 인덱스 무한 증가 | 오래된 memory 아카이브 정책 |
+| budget/controller | token_logs 무한 증가 | 월별 집계 후 상세 로그 정리 |
+| LLM 호출 | httpx client 미반환 | async with 강제 |
+
+### 메모리 프로파일링
+
+```bash
+# CI/테스트: pytest-memray로 메모리 회귀 탐지
+uv run pytest --memray
+
+# 특정 테스트에 메모리 한도 설정
+@pytest.mark.limit_memory("50 MB")
+async def test_worker_pool() -> None:
+    ...
+
+# 개발: memray로 상세 분석
+memray run -o output.bin python script.py
+memray flamegraph output.bin
+
+# 프로덕션: tracemalloc (낮은 오버헤드)
+# 3.14: python -m asyncio ps <PID> 로 async 태스크 실시간 조회
+# 3.14: python -m pdb -p <PID> 로 실행 중 프로세스 원격 디버깅
+```
+
+### 대량 데이터 처리
+
+```python
+# ✅ generator로 한 건씩 처리
+async def stream_logs(db: Database) -> AsyncGenerator[TokenLog]:
+    async for row in await db.execute("SELECT * FROM token_logs"):
+        yield TokenLog(**row)
+
+# ✅ 대량 INSERT는 executemany + 배치
+await db.executemany(
+    "INSERT INTO token_logs VALUES (?, ?, ?)",
+    batch,  # list[tuple], 1000건 단위
+)
+```
+
+## Testing — Must Follow
+
+코드를 작성하면 반드시 테스트도 함께 작성한다. PR 없는 코드는 있어도, 테스트 없는 코드는 없다.
+
+### 원칙
+
+- **새 모듈 = 새 테스트 파일.** `src/hive/foo/bar.py` → `tests/test_bar.py`
+- **모든 public 함수에 최소 1개 테스트.** happy path + edge case
+- **테스트 먼저 실행 가능한 상태 유지.** `uv run pytest` 가 항상 통과해야 함
+- **LLM 호출은 mock.** 단위 테스트에서 실제 API를 호출하지 않는다
+
+### 테스트 구조
+
+```
+tests/
+  test_models.py       ← core/models.py
+  test_database.py     ← storage/database.py
+  test_config.py       ← core/config.py
+  test_founding.py     ← founding/engine.py  (LLM mock)
+  test_gateway.py      ← ceo/gateway.py
+  test_memory.py       ← memory/store.py
+  test_budget.py       ← budget/controller.py
+  test_pool.py         ← runtime/pool.py
+  test_scheduler.py    ← runtime/scheduler.py
+  test_cli_office.py   ← office/cli.py
+  ...
+```
+
+### 패턴
+
+```python
+# 1. async 테스트는 그냥 async def로 작성 (asyncio_mode=auto)
+class TestSomething:
+    async def test_example(self) -> None:
+        ...
+
+# 2. DB fixture — in-memory SQLite (매 테스트 격리)
+@pytest.fixture
+async def db() -> AsyncGenerator[Database]:
+    database = Database(":memory:")
+    await database.connect()
+    yield database
+    await database.close()
+
+# 3. LLM mock — anthropic client를 mock
+@pytest.fixture
+def mock_llm() -> MockLLMClient:
+    return MockLLMClient(responses=[
+        {"content": "분석 결과입니다.", "input_tokens": 100, "output_tokens": 50},
+    ])
+
+# 4. Office mock — CLI 입력을 자동화
+@pytest.fixture
+def mock_office() -> MockOffice:
+    return MockOffice(ceo_responses=["yes", "TestCorp", "50"])
+
+# 5. integration 테스트는 마커로 분리
+@pytest.mark.integration
+async def test_real_llm_call() -> None:
+    """실제 LLM API 호출. CI에서는 스킵."""
+    ...
+```
+
+### 무엇을 테스트하는가
+
+| 모듈 | 테스트 대상 | mock 대상 |
+|------|-----------|----------|
+| models | 기본값, 유효성, ID 유니크 | 없음 |
+| database | CRUD, FTS, 집계 쿼리 | 없음 (in-memory DB) |
+| config | load/save, env var, 기본값 | 없음 |
+| founding | 대화 흐름, company.yaml 생성 | Office (CEO 입력), LLM |
+| gateway | escalation 판단, 승인/거절 | Office |
+| memory | CRUD, 검색, 중복 감지 | 없음 (in-memory DB) |
+| budget | 예산 추적, auto-downgrade, 알림 | Office (알림) |
+| pool | Worker 동시성 제한, semaphore | LLM |
+| scheduler | DAG 정렬, 병렬 실행, 큐 | Worker Pool |
+| office/cli | 메시지 표시, 승인 프롬프트 | stdin/stdout |
+
+### 테스트 실행
+
+```bash
+uv run pytest                    # 전체
+uv run pytest tests/test_foo.py  # 단일 파일
+uv run pytest -k "test_hire"     # 이름으로 필터
+uv run pytest -v                 # 상세 출력
+uv run pytest -m integration     # integration만
+uv run pytest -m "not integration"  # integration 제외
+```
+
+### 체크리스트 (새 기능 작성 시)
+
+- [ ] 새 모듈에 대응하는 test 파일 생성했는가?
+- [ ] happy path 테스트가 있는가?
+- [ ] edge case (빈 값, None, 잘못된 입력) 테스트가 있는가?
+- [ ] async 함수는 async 테스트로 작성했는가?
+- [ ] LLM 호출을 mock 했는가?
+- [ ] `uv run pytest` 가 전부 통과하는가?

hive_corp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Son Seongjun (SonAIengine)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.