AGENT.json

{
  "name": "CodeScribe", 
  "repository": "https://github.com/Lab-Notebooks/CodeScribe", 
  "title": "CodeScribe \u2014 agent card", 
  "what_this_repo_is": {
    "entry_points": [
      "CLI: code-scribe (see --help)", 
      "Agent runtime: codescribe/lib/_agent.py", 
      "Tool implementations: codescribe/lib/_tools.py", 
      "Model backends: codescribe/lib/_llm.py", 
      "Loop runtime: codescribe/lib/_loop.py"
    ], 
    "capabilities": [
      "Incremental Fortran \u2192 C++ translation (with interface-layer support)", 
      "Code inspection, generation, and update", 
      "Tool-using coding agent workflows (read/glob/bash/edit/write)", 
      "Bounded author\u2192review loop over a task file with durable on-disk state"
    ], 
    "summary": "AI-assisted framework for scientific software development: incremental Fortran\u2192C++ translation plus code inspection/generation/update and tool-using agent workflows."
  }, 
  "schema_version": "1.0", 
  "safety": {
    "docs": [
      {
        "path": "docs/agent.md", 
        "description": "Agent architecture and bounded-mode policy"
      }, 
      {
        "path": "docs/loop.md", 
        "description": "Loop mode internals and on-disk artifacts"
      }, 
      {
        "path": "docs/tools.md", 
        "description": "Tool implementations (read/glob/bash/edit/write)"
      }
    ], 
    "notes": [
      "Bounded mode is a practical constraint layer, not an OS sandbox.", 
      "Bounded bash uses an allowlist and rejects shell metacharacters; some commands will fail by design.", 
      "The loop task file can extend the bash allowlist via a [tools] bash = [...] TOML section.", 
      "TOML diagnostic logs include tool_start (with model_reasoning) and tool_end (with output_preview) events for post-run inspection.",
      "Agent hard limits per run: 120 total tool calls, 10 per iteration, 2 repeat-call attempts (read gets 3x). After 3 consecutive all-error iterations the agent is nudged to emit a BLOCKED answer.",
      "Tool outputs are capped at 8000 chars in message history; truncated output includes a paging hint (read(path, offset=N)).",
      "review.toml (review-phase event log) is always written unconditionally. author.toml is cleared and rewritten at the start of each author phase. Both differ from --log, which routes author-phase events to an additional user-specified path.",
      "The review agent's bash tool is restricted to: ls, stat, pwd, find, grep, head, tail, which, env, rg. No write, edit, or arbitrary shell commands."
    ], 
    "modes": [
      {
        "artifacts": [
          ".codescribe/loop/run.toml", 
          ".codescribe/loop/state.toml", 
          ".codescribe/loop/author.toml", 
          ".codescribe/loop/review_output.toml", 
          ".codescribe/loop/review.toml"
        ], 
        "bounded": true, 
        "command": "loop", 
        "description": "Repeated author\u2192review cycles. Cross-loop state is carried in-memory; each cycle starts a fresh agent whose context is injected by the harness. The loop exits early if the review agent reports no pending items and no blocker. On-disk artifacts under .codescribe/loop/ are for inspection and crash-resume only.", 
        "options": {
          "--workdir DIR": "Root directory the agent is bounded to (default: cwd)", 
          "--agent-iterations/-niter N": "Tool-call budget per cycle (default: 30)", 
          "--reason": "Enable adaptive thinking (Anthropic models only; ignored for other backends)", 
          "--log": "Write TOML diagnostic events to the default path: .codescribe/logs/toolusage.toml", 
          "--verbose/-v": "Stream per-iteration tool calls and token usage to stdout", 
          "--agent-loops/-nloop N": "Number of author\u2192review cycles (default: 5)", 
          "--log-path PATH": "Write TOML diagnostic events to PATH (implies --log)"
        }
      }, 
      {
        "bounded": false,
        "command": "agent",
        "description": "Single agent session with unbounded tools (use with care). The TASK argument is either a task string or a path to a TOML task file in the same format as loop; the two forms are mutually exclusive. A task file is loaded as prior conversation, is protected from write/edit/bash, and may extend the bash allowlist through its [tools] section.",
        "options": {
          "--workdir DIR": "Root directory the agent is bounded to (default: cwd)",
          "--reason": "Enable adaptive thinking (Anthropic models only; ignored for other backends)",
          "--log": "Write TOML diagnostic events to the default path: .codescribe/logs/toolusage.toml", 
          "--agent-iterations/-niter N": "Maximum tool-call iterations (default: 20)", 
          "--log-path PATH": "Write TOML diagnostic events to PATH (implies --log)", 
          "--verbose/-v": "Stream per-iteration tool calls and token usage to stdout"
        }
      }
    ]
  }, 
  "install": {
    "commands": [
      "python3 -m venv env", 
      "source env/bin/activate", 
      "pip install --upgrade pip", 
      "pip install -e .", 
      "code-scribe --help"
    ]
  }, 
  "model_setup": {
    "anthropic_quickstart": {
      "example_commands": [
        "ANTHROPIC_API_KEY=sk-ant-... code-scribe agent \"Fix failing tests\" -m anthropic-claude-sonnet-4-6", 
        "ANTHROPIC_API_KEY=sk-ant-... code-scribe agent \"Fix failing tests\" -m anthropic-claude-sonnet-4-6 --reason", 
        "ANTHROPIC_API_KEY=sk-ant-... code-scribe loop task.toml -m anthropic-claude-sonnet-4-6 --reason"
      ], 
      "optional_env": [
        "CODESCRIBE_MODEL_REASONING",
        "ANTHROPIC_BASE_URL",
        "CODESCRIBE_MAX_TOKENS"
      ],
      "reasoning_note": "Pass --reason to agent or loop to enable adaptive thinking. Reasoning is configured at the LLM level (AnthropicModel) and silently ignored by OpenAI-compatible backends. The agent relays returned reasoning_blocks verbatim into the next turn, as required by the Anthropic API. CODESCRIBE_MODEL_REASONING=1 env var is also supported as a fallback for scripting/CI. Recommended for claude-sonnet-4-6 and claude-opus-* on complex agentic tasks. Do not enable for Haiku or older models.",
      "required_env": [
        "ANTHROPIC_API_KEY"
      ], 
      "example_models": [
        "anthropic-claude-sonnet-4-6", 
        "anthropic-claude-opus-4-8"
      ], 
      "model_prefix": "anthropic-"
    }, 
    "environment_variables": [
      {
        "required": false, 
        "example": "oaic-llama3.1", 
        "name": "CODESCRIBE_MODEL", 
        "description": "Default model name used when -m/--model is omitted."
      }, 
      {
        "required": false, 
        "example": "8192", 
        "name": "CODESCRIBE_MAX_TOKENS", 
        "description": "Maximum output tokens the model may generate per reply. Applies to all backends. Default: 32768."
      }, 
      {
        "required": true, 
        "example": "http://localhost:11434/v1", 
        "name": "OPENAI_COMP_BASEURL", 
        "description": "Base URL of an OpenAI-compatible API (must include /v1). Used by oaic-* models."
      }, 
      {
        "required": true, 
        "example": "ollama", 
        "name": "OPENAI_COMP_PROVIDER", 
        "description": "Provider label used for routing/auth policy (e.g. ollama, alcf-inference). Used by oaic-* models."
      }, 
      {
        "required": true, 
        "example": "placeholder", 
        "name": "OPENAI_COMP_APIKEY", 
        "description": "API key for the oaic-* client. Some local endpoints accept any placeholder."
      }, 
      {
        "required": false, 
        "example": "sk-...", 
        "name": "OPENAI_API_KEY", 
        "description": "API key for hosted OpenAI models (openai-* prefix)."
      }, 
      {
        "required": false, 
        "example": "sk-ant-...", 
        "name": "ANTHROPIC_API_KEY", 
        "description": "API key for Anthropic models (anthropic-* prefix). Required when using the recommended Anthropic backend for agent and loop commands."
      }, 
      {
        "required": false, 
        "example": "https://my-proxy.internal/anthropic", 
        "name": "ANTHROPIC_BASE_URL", 
        "description": "Optional base URL override for Anthropic models (e.g. a proxy endpoint)."
      }, 
      {
        "required": false,
        "example": "1",
        "name": "CODESCRIBE_MODEL_REASONING",
        "description": "Set to '1' to enable adaptive thinking on supported Anthropic models (claude-opus-*, claude-sonnet-4-6). Has no effect on OpenAI-compatible backends."
      }
    ], 
    "recommended": "Anthropic (anthropic-*) for agent and loop commands \u2014 native tool calling, streaming, and adaptive reasoning are all supported. Use oaic-* for local or OpenAI-compatible endpoints.", 
    "docs": [
      {
        "path": "docs/models.md", 
        "description": "Backends and env vars"
      }
    ], 
    "example_command": "code-scribe inspect README.rst -m oaic-llama3.1 -q \"Summarize this repo and list key entry points.\""
  }
}