Module 0 core

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format check
+        run: ruff format --check .
+      - name: Mypy
+        run: mypy agentargus
+      - name: Pytest
+        run: pytest --cov=agentargus --cov-report=xml --cov-report=term-missing
+
+  e2e:
+    # End-to-end demo runs separately and does not block the merge gate (spec §10).
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push'
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Run demo (placeholder until Module 10)
+        run: echo "e2e demo lands in Module 10"

.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Secrets & local config
+.env
+.env.*
+!.env.example
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Project artifacts
+*.sqlite
+*.sqlite3
+dead_letter*.jsonl
+
+# Internal planning / study docs (not for the public repo)
+IMPLEMENTAION.md
+module_notes/

.ruff.toml

@@ -0,0 +1,25 @@
+target-version = "py310"
+line-length = 100
+src = ["agentargus", "tests"]
+
+[lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "W",   # pycodestyle warnings
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # comprehensions
+    "SIM", # simplify
+    "T20", # flake8-print  -> bans print() in library code (§7)
+]
+
+[lint.per-file-ignores]
+# Examples and CLI are allowed to print; tests may too.
+"examples/**" = ["T20"]
+"tests/**" = ["T20"]
+"benchmarks/**" = ["T20"]
+
+[format]
+quote-style = "double"

DESIGN.md

@@ -0,0 +1,36 @@
+# AgentArgus — Design, Scope, Non-Goals
+
+> Owner-authored document. Claude Code seeds it from spec §1; the owner refines
+> and defends each point.
+
+## Problem
+Teams ship LLM agents to production with almost no operational rigour. There is
+no single place to answer: *Did the agent do the right thing? What did it cost?
+Why did it fail? Can it recover?* RAGAS covers RAG eval only; observability
+tools cover traces only; reliability is hand-rolled per project. AgentArgus is a
+framework-agnostic, single-package answer.
+
+## What AgentArgus is
+A production-grade Python library that wraps *any* agent and uniformly adds
+evaluation, observability, reliability, human-in-the-loop, and orchestration
+helpers, producing a rich `RunResult` that evaluation consumes.
+
+## The core design bet (checkpoint 1.1)
+**Framework-agnostic wrapping.** We wrap a callable / LangGraph graph / BaseAgent
+behind one `Agent` facade. The cost of that generality: we cannot piggyback any
+one framework's trace schema, so we define our own (`RunResult` + GenAI-convention
+spans), and we forgo framework-specific optimizations. The payoff: one API works
+everywhere and nothing is locked to a vendor.
+
+## Non-goals (defend these)
+- **Not a model-serving / inference engine** — that's vLLM/TGI's job.
+- **Not a vector DB or a RAG framework** — AgentArgus *evaluates* RAG; it does
+  not *do* retrieval for you.
+- **Not tied to any one agent framework** — LangGraph is *supported*, never
+  *required*.
+- **Not a hosted product in v0.1.0** — it is a library. A dashboard/app is a
+  *consumer* of it.
+
+## Key decisions log
+See [DESIGN_LOG.md](DESIGN_LOG.md) for the per-module decision record and
+[HARD_QUESTIONS.md](HARD_QUESTIONS.md) for the review questions.