jac-coder 0.1.0__tar.gz

jac_coder-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: jac-coder
+Version: 0.1.0
+Summary: AI coding agent backend for Jac, powered by jac-byllm
+Requires-Python: >=3.11
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: jaclang
+Requires-Dist: byllm
+Requires-Dist: mcp>=1.0.0

jac_coder-0.1.0/README.md

@@ -0,0 +1,141 @@
+# JacCoder
+
+![JacCoder CLI](assets/cli.png)
+
+AI coding agent for the Jaseci stack, built entirely in [Jac](https://github.com/jaseci-labs/jaseci) using Object-Spatial Programming. Features an orchestrator-worker architecture with compiler-level Jac Intelligence, self-correcting code writes, and in-process SubAgent delegation.
+
+## Architecture
+
+![JacCoder Graph Architecture](assets/graph.png)
+
+## Features
+
+- **Orchestrator-Worker Architecture** - MainAgent handles tasks directly or delegates to focused SubAgents (WorkerRunner / ExplorerRunner)
+- **Jac Intelligence** - compiler-level AST analysis via jaclang (`analyze_project`, `find_symbol`)
+- **22 Built-in Tools** - filesystem, search, git, shell, web, Jac compiler, scaffolding, delegation
+- **Self-Correcting Writes** - automatic `jac check` on `.jac` file writes with error feedback
+- **In-Process SubAgents** - no subprocess overhead, shared event system, capability-scoped tools
+- **Multi-Provider LLM** - 100+ models via [byllm](https://github.com/jaseci-labs/byllm)
+- **Public API** - clean interface for external apps (JacBuilder, IDE extensions)
+- **Context Management** - smart compaction keeps conversations under token budget
+
+## Prerequisites
+
+- Python 3.12+
+- jaclang, byllm, jac-super
+
+```bash
+pip install jaclang byllm jac-super python-dotenv
+```
+
+## Quick Start
+
+```bash
+# Set API key
+export OPENAI_API_KEY="sk-..."
+
+# Interactive REPL
+jac cli.jac
+
+# Single prompt (non-interactive)
+jac cli.jac run "build a hello world jac app at /tmp/myapp"
+
+# Resume a session
+jac cli.jac session <id-prefix>
+```
+
+## Architecture
+
+```
+Root → Session → MainAgent
+                    ├── handles simple tasks directly (read, search, edit, git)
+                    └── spawn_agent() → WorkerRunner (read+write) or ExplorerRunner (read-only)
+                                         └── runs in-process, returns result to MainAgent
+```
+
+- **MainAgent (node)** - orchestrator with 25 tools. Handles simple tasks directly, delegates complex work.
+- **WorkerRunner (obj)** - in-process SubAgent with 18 tools (can write/edit/run). Full Jac syntax rules.
+- **ExplorerRunner (obj)** - in-process SubAgent with 10 tools (read-only). For investigation tasks.
+- **Session (node)** - persistent chat state, history, active files, errors.
+- **ProjectMemory (node)** - AST-derived codebase knowledge (nodes, walkers, edges, imports).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read files with line numbers and pagination |
+| `write_code` | Write file with auto `jac_check` validation |
+| `edit_code` | Find-and-replace with auto `jac_check` validation |
+| `find_files` | Find files by glob pattern |
+| `grep_search` | Regex search across files |
+| `list_files` | List directory contents |
+| `run_command` | Execute shell commands (permission-guarded) |
+| `jac_check` | Type-check `.jac` files |
+| `jac_run` | Run `.jac` files |
+| `jac_docs` | Search Jac language reference and examples |
+| `analyze_project` | Full AST analysis of a Jac project |
+| `find_symbol` | Find symbol definitions, usages, and imports |
+| `git_status` | Show working tree status |
+| `git_diff` | Show uncommitted changes |
+| `git_log` | Show recent commit history |
+| `git_commit` | Stage and commit changes |
+| `think` | Explicit reasoning step before acting |
+| `spawn_agent` | Delegate task to a SubAgent (worker/explorer) |
+| `web_fetch` | Fetch URL content |
+| `web_search` | Web search via DuckDuckGo |
+| `scaffold_project` | Generate project templates |
+| `ask_question` | Prompt user for input |
+| `update_todos` | Track multi-step task progress |
+
+## Public API
+
+External apps import only from `jac_coder.api`:
+
+```python
+from jac_coder.api import initialize, create_session, chat, close_session
+
+initialize("web")
+session = create_session("/path/to/project", title="My App")
+result = chat(session["session_id"], "build a calculator")
+print(result["response"])
+```
+
+## Configuration
+
+Config sources (highest priority first):
+
+1. Environment: `MODEL`, `TEMPERATURE`, `MAX_TOKENS`, `MAX_REACT_ITERATIONS`
+2. Project: `./jaccoder.json`
+3. Global: `~/.jaccoder/config.json`
+
+## Testing
+
+```bash
+python -m pytest tests/ -v    # 58 tests
+```
+
+## Project Structure
+
+```
+jac-code/
+├── cli.jac                   # CLI entry point (REPL + subcommands)
+├── jac_coder/                # Core package
+│   ├── api.jac               # Public API (the only module external apps import)
+│   ├── nodes.jac             # MainAgent, WorkerRunner, ExplorerRunner, Session, ProjectMemory
+│   ├── walkers.jac           # Walker definitions (interact, new_session, etc.)
+│   ├── config.jac            # Multi-source config + LLM init
+│   ├── context.jac           # Smart context compaction
+│   ├── events.jac            # Tool event system + turn summaries
+│   ├── memory.jac            # AST-based project memory
+│   ├── permission.jac        # Permission rule engine
+│   ├── tool/                 # 22 tools organized by domain
+│   │   ├── delegation.jac    # spawn_agent (in-process SubAgent execution)
+│   │   ├── think.jac         # Chain-of-thought reasoning
+│   │   ├── git.jac           # Git operations
+│   │   ├── jac_analyzer.jac  # AST-based Jac Intelligence
+│   │   └── ...
+│   ├── data/                 # Jac syntax rules (build_rules, client_rules, server_rules)
+│   └── impl/                 # Implementation files
+├── tests/                    # 58 tests (pytest + jac)
+└── docs/                     # Architecture, roadmap, progress
+```

jac_coder-0.1.0/jac_coder/api.jac

@@ -0,0 +1,82 @@
+"""JacCoder public API."""
+
+import os;
+import sys;
+
+import from datetime { datetime }
+import from jac_coder.config {
+    get_config,
+    set_model as _set_model,
+    get_model as _get_model
+}
+import from jac_coder.util.tool_output { tool_end }
+import from jac_coder.permission { permission_engine }
+import from jac_coder.util.sandbox { set_sandbox_root }
+import from jac_coder.context { build_context, ContextConfig }
+import from jac_coder.walkers { new_session, ensure_main_agent, _consume_llm_stream }
+import from jac_coder.mcp_manager {
+    mcp_add_server,
+    mcp_remove_server,
+    mcp_list_servers,
+    mcp_get_tools,
+    mcp_register_builtin
+}
+import from jac_coder.memory {
+    find_or_create_memory,
+    _init_memory,
+    update_memory_from_session
+}
+import from jac_coder.nodes { Session, MainAgent }
+import from jac_coder.events {
+    register_event_callback,
+    clear_event_callbacks,
+    reset_steps,
+    start_turn,
+    emit_turn_summary,
+    emit_event
+}
+
+
+# Thread-safe session registry — graph root() is per-request in jac-cloud,
+# so background threads can't find sessions via [root()-->]. This dict
+# is module-level and accessible from any thread.
+glob _session_registry: dict = {};
+
+"""Initialize jac-coder."""
+def initialize(mode: str = "web") -> None;
+
+"""Create a new session."""
+def create_session(directory: str, title: str = "", agent: str = "main") -> dict;
+
+"""Send a message and get a response."""
+def chat(
+    session_id: str,
+    message: str,
+    directory: str = "",
+    on_event: Any = None,
+    mode: str = "full",
+    agent_context: str = ""
+) -> dict;
+
+def list_sessions() -> list;
+
+def get_session(session_id: str) -> dict;
+
+def close_session(session_id: str) -> dict;
+
+# --- Model management API ---
+"""Switch the active LLM model."""
+def api_set_model(model: str) -> dict;
+
+"""Get current model info."""
+def api_get_model() -> dict;
+
+# --- MCP management API ---
+"""Add or update an MCP server."""
+def api_mcp_add(name: str, config: dict) -> dict;
+
+"""Remove an MCP server."""
+def api_mcp_remove(name: str) -> dict;
+
+"""List all configured MCP servers."""
+def api_mcp_list() -> list;

jac_coder-0.1.0/jac_coder/cli_entry.py

@@ -0,0 +1,25 @@
+"""CLI entry point for `jac-coder` command."""
+
+import subprocess
+import sys
+import os
+
+
+def main():
+    # Find the project root (where cli.jac lives)
+    pkg_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(pkg_dir)
+    cli_jac = os.path.join(project_root, "cli.jac")
+
+    if not os.path.exists(cli_jac):
+        print("Error: cli.jac not found. Run from the jac-coder project directory.")
+        sys.exit(1)
+
+    # Set JACCODER_ROOT so tools can find data/ directory regardless of CWD
+    os.environ["JACCODER_ROOT"] = project_root
+
+    sys.exit(subprocess.call(["jac", cli_jac] + sys.argv[1:]))
+
+
+if __name__ == "__main__":
+    main()

jac_coder-0.1.0/jac_coder/config.jac

@@ -0,0 +1,36 @@
+import os;
+import json;
+
+import from pathlib { Path }
+import from dotenv { load_dotenv }
+import from byllm.lib { Model }
+
+
+obj JacCoderConfig {
+    has default_model: str = "gpt-5.2-2025-12-11",
+        temperature: float = 0.2,
+        max_tokens: int = 8192,
+        max_react_iterations: int = 30,
+        project_dir: str = "";
+}
+
+glob _config: JacCoderConfig = JacCoderConfig();
+
+# --- Config ---
+def get_home_dir() -> str;
+def _merge_from_file(config: JacCoderConfig, path: str) -> None;
+def load_config(project_dir: str = "") -> JacCoderConfig;
+def get_config() -> JacCoderConfig;
+def get_data_dir() -> str;
+
+# --- Model management ---
+def set_model(model: str) -> dict;
+def get_model() -> dict;
+
+with entry {
+    load_dotenv(override=True);
+    load_config();
+}
+
+glob model_name: str = _config.default_model;
+glob llm = Model(model_name=model_name);

jac_coder-0.1.0/jac_coder/context.jac

@@ -0,0 +1,17 @@
+obj ContextConfig {
+    has token_budget: int = 20000;
+    has recent_window: int = 8;
+}
+
+
+def estimate_tokens(messages: list[dict]) -> int;
+
+def needs_compaction(messages: list[dict], budget: int = 20000) -> bool;
+
+def build_context(
+    chat_history: list[dict],
+    active_files: list[str] = [],
+    pending_errors: list[str] = [],
+    config: ContextConfig | None = None,
+    project_summary: str = ""
+) -> list[dict];

jac_coder-0.1.0/jac_coder/data/examples/ai_agent.md

@@ -0,0 +1,90 @@
+# Example: AI Agent with LLM Routing
+
+Uses `by llm()` for intelligent routing, `sem` annotations for prompts, walker graph traversal.
+
+## Backend: agent.jac — Declarations
+
+```jac
+"""AI agent with LLM-driven routing between handler nodes."""
+
+import from byllm.lib { Model }
+
+glob llm: Model = Model(model_name="gpt-4.1-mini");
+
+node Router {}
+
+node QAHandler {
+    def respond(message: str, context: list[dict]) -> str by llm(
+        method="Reason",
+        messages=context,
+        temperature=0.3
+    );
+    can handle with process_request entry;
+}
+
+node CodeHandler {
+    def respond(message: str, context: list[dict]) -> str by llm(
+        messages=context,
+        tools=[search_docs]
+    );
+    can handle with process_request entry;
+}
+
+walker :pub process_request {
+    has message: str = "";
+    has context: list[dict] = [];
+
+    can route with Router entry {
+        visit [-->] by llm(
+            incl_info={"message": self.message, "context": self.context[-5:]}
+        );
+    }
+
+    can init_graph with Root entry {
+        visit [-->][?:Router] else {
+            router = (here ++> Router())[0];
+            router ++> QAHandler();
+            router ++> CodeHandler();
+            visit router;
+        };
+    }
+}
+```
+
+## Implementation: impl/agent.impl.jac
+
+```jac
+sem Router.classify = """Return exactly one label: QA, CODE, or DONE.
+QA = general questions, CODE = programming tasks, DONE = task complete.""";
+
+sem QAHandler.respond = """You are a helpful assistant. Answer clearly and concisely.""";
+
+sem CodeHandler.respond = """You are an expert programmer.
+Use search_docs to find documentation before answering.""";
+
+impl QAHandler.handle with process_request entry {
+    response = here.respond(message=self.message, context=self.context);
+    report {"response": response, "handler": "qa"};
+    visit [<--][?:Router];
+}
+
+impl CodeHandler.handle with process_request entry {
+    response = here.respond(message=self.message, context=self.context);
+    report {"response": response, "handler": "code"};
+    visit [<--][?:Router];
+}
+
+impl process_request.route with Router entry {
+    label = here.classify(message=self.message, context=self.context);
+    if "DONE" in label { disengage; }
+}
+```
+
+## Key Patterns Demonstrated
+
+- **Lazy graph creation**: `visit [-->][?:Router] else { ... }` creates graph on first use
+- **LLM-driven routing**: `visit [-->] by llm(...)` lets LLM choose which handler
+- **Interface/impl split**: Declarations in `.jac`, semantics + logic in `.impl.jac`
+- **Multi-node traversal**: Walker visits Router → Handler → back to Router
+- **`sem` annotations**: System prompts for each LLM-powered method
+- **`disengage`**: Stops walker when task is complete