a3s-code 0.6.0__tar.gz → 0.9.1__tar.gz

a3s_code-0.9.1/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: a3s-code
+Version: 0.9.1
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Summary: A3S Code - Native Python bindings for the AI coding agent
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# A3S Code - Native Python Bindings
+
+Native Python module for the A3S Code AI coding agent, built with PyO3.
+
+```python
+from a3s_code import Agent
+
+agent = Agent(model="claude-sonnet-4-20250514", api_key="sk-ant-...", workspace="/project")
+result = agent.send("What files handle auth?")
+print(result.text)
+```
+
+## Installation
+
+```bash
+pip install a3s-code
+```
+
+## License
+
+MIT
+

a3s_code-0.9.1/README.md

@@ -0,0 +1,21 @@
+# A3S Code - Native Python Bindings
+
+Native Python module for the A3S Code AI coding agent, built with PyO3.
+
+```python
+from a3s_code import Agent
+
+agent = Agent(model="claude-sonnet-4-20250514", api_key="sk-ant-...", workspace="/project")
+result = agent.send("What files handle auth?")
+print(result.text)
+```
+
+## Installation
+
+```bash
+pip install a3s-code
+```
+
+## License
+
+MIT

a3s_code-0.9.1/code/Cargo.toml

@@ -0,0 +1,19 @@
+[workspace]
+resolver = "2"
+members = [
+    "core",
+    "cli",
+]
+# Native SDK crates require special toolchains (Python/Node.js)
+# Build them individually: cargo build -p a3s-code-node / a3s-code-py
+exclude = [
+    "sdk/node",
+    "sdk/python",
+]
+
+[profile.release]
+opt-level = "z"
+lto = "fat"
+codegen-units = 1
+strip = true
+panic = "abort"

a3s_code-0.9.1/code/core/.gitignore

@@ -0,0 +1,5 @@
+/target
+Cargo.lock
+.a3s/
+.cargo/
+.claude/

a3s_code-0.9.1/code/core/Cargo.toml

@@ -0,0 +1,115 @@
+[package]
+name = "a3s-code-core"
+version = "0.9.1"
+edition = "2021"
+authors = ["A3S Lab Team"]
+license = "MIT"
+repository = "https://github.com/A3S-Lab/Code"
+description = "A3S Code Core - Embeddable AI agent library with tool execution"
+
+[lib]
+name = "a3s_code_core"
+path = "src/lib.rs"
+
+[dependencies]
+# Internal crates
+a3s-common = { version = "0.1", path = "../../common" }
+a3s-memory = { version = "0.1", path = "../../memory" }
+a3s-lane = { version = "0.4", path = "../../lane" }
+a3s-search = { version = "0.8", path = "../../search", default-features = false }
+# Sandbox integration (optional — requires `sandbox` feature)
+a3s-box-sdk = { version = "0.6", path = "../../box/src/sdk", optional = true }
+
+# Async runtime
+tokio = { version = "1.35", features = [
+    "rt-multi-thread", "sync", "time", "io-util",
+    "process", "fs", "macros"
+] }
+tokio-stream = { version = "0.1", features = ["net"] }
+tokio-util = { version = "0.7", features = ["codec"] }
+
+# Serialization
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+serde_yaml = "0.9"
+
+# HCL config parsing
+hcl-rs = "0.18"
+
+# Error handling
+anyhow = "1.0"
+thiserror = "1.0"
+
+# Logging (tracing only — no OTel)
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
+
+# OpenTelemetry (optional — requires `telemetry` feature)
+opentelemetry = { version = "0.27", optional = true }
+opentelemetry_sdk = { version = "0.27", features = ["rt-tokio"], optional = true }
+opentelemetry-otlp = { version = "0.27", features = ["tonic"], optional = true }
+tracing-opentelemetry = { version = "0.28", optional = true }
+
+# Async utilities
+futures = "0.3"
+async-trait = "0.1"
+async-stream = "0.3"
+
+# HTTP client for LLM APIs
+reqwest = { version = "0.11", default-features = false, features = ["json", "stream", "rustls-tls"] }
+
+# File operations
+glob = "0.3"
+ignore = "0.4"
+
+# Diff for edit tool
+similar = "2.4"
+
+# Home directory for project memory
+dirs = "5.0"
+
+# Regex for template substitution
+regex = "1.10"
+
+# SHA256 for security provider
+sha256 = "1.5"
+
+# Shell argument parsing
+shell-words = "1.1"
+
+# HTML to text/markdown conversion
+html2text = "0.16"
+htmd = "0.5"
+
+# Base64 for image encoding
+base64 = "0.21"
+
+# Bytes for streaming
+bytes = "1.5"
+
+# Pin for futures
+pin-project-lite = "0.2"
+
+# UUID
+uuid = { version = "1.6", features = ["v4", "serde"] }
+
+# Time handling
+chrono = { version = "0.4", features = ["serde"] }
+
+[features]
+default = []
+# Enable A3S Box sandbox integration for the `bash` tool.
+# When active, `SessionOptions::with_sandbox()` routes bash commands through
+# a MicroVM sandbox instead of `std::process::Command`.
+sandbox = ["dep:a3s-box-sdk"]
+# Enable OpenTelemetry OTLP export for traces and metrics.
+# When active, `TelemetryConfig::init()` sets up OTLP exporter + tracing subscriber.
+telemetry = [
+    "dep:opentelemetry",
+    "dep:opentelemetry_sdk",
+    "dep:opentelemetry-otlp",
+    "dep:tracing-opentelemetry",
+]
+
+[dev-dependencies]
+tempfile = "3.10"

a3s_code-0.9.1/code/core/examples/01_basic_send.rs

@@ -0,0 +1,83 @@
+//! # Basic Send — Non-Streaming Agent Execution
+//!
+//! The simplest possible A3S Code example: create an agent from config,
+//! bind to a workspace, send a prompt, and print the result.
+//!
+//! ```bash
+//! cd crates/code
+//! cargo run --example 01_basic_send
+//! ```
+
+use a3s_code_core::Agent;
+use std::path::PathBuf;
+use tempfile::TempDir;
+
+fn find_config() -> PathBuf {
+    if let Ok(p) = std::env::var("A3S_CONFIG") {
+        return PathBuf::from(p);
+    }
+    let home = dirs::home_dir().expect("no home dir");
+    let home_cfg = home.join(".a3s/config.hcl");
+    if home_cfg.exists() {
+        return home_cfg;
+    }
+    // Project root
+    let project_cfg = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../.a3s/config.hcl");
+    if project_cfg.exists() {
+        return project_cfg;
+    }
+    panic!("Config not found. Create ~/.a3s/config.hcl or set A3S_CONFIG");
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    tracing_subscriber::fmt()
+        .with_env_filter("a3s_code_core=info")
+        .init();
+
+    let config = find_config();
+    println!("Config: {}", config.display());
+
+    // 1. Create agent from config
+    let agent = Agent::new(config.to_str().unwrap()).await?;
+    println!("Agent created ✓");
+
+    // 2. Create a temp workspace
+    let workspace = TempDir::new()?;
+    let session = agent.session(workspace.path().to_str().unwrap(), None)?;
+    println!("Session bound to: {}\n", workspace.path().display());
+
+    // 3. Send a prompt (non-streaming)
+    let result = session
+        .send(
+            "Create a file called hello.rs with a main function that prints 'Hello, A3S!'.\n\
+             Then read the file back and confirm it looks correct.",
+            None,
+        )
+        .await?;
+
+    println!("─── Result ───");
+    println!("Text:       {}", truncate(&result.text, 200));
+    println!("Tool calls: {}", result.tool_calls_count);
+    println!("Tokens:     {} total", result.usage.total_tokens);
+
+    // 4. Verify the file
+    let hello = workspace.path().join("hello.rs");
+    if hello.exists() {
+        println!(
+            "\n✓ hello.rs created ({} bytes)",
+            std::fs::metadata(&hello)?.len()
+        );
+    }
+
+    Ok(())
+}
+
+fn truncate(s: &str, max: usize) -> String {
+    let s = s.trim();
+    if s.len() <= max {
+        s.to_string()
+    } else {
+        format!("{}…", &s[..max])
+    }
+}

a3s_code-0.9.1/code/core/examples/02_streaming.rs

@@ -0,0 +1,108 @@
+//! # Streaming Events — Real-Time Agent Visibility
+//!
+//! Subscribe to the agent's event stream to watch it think and act in real time.
+//! Demonstrates all event types: TextDelta, ToolStart, ToolEnd, TurnStart, etc.
+//!
+//! ```bash
+//! cargo run --example 02_streaming
+//! ```
+
+use a3s_code_core::{Agent, AgentEvent};
+use std::path::PathBuf;
+use tempfile::TempDir;
+
+fn find_config() -> PathBuf {
+    if let Ok(p) = std::env::var("A3S_CONFIG") {
+        return PathBuf::from(p);
+    }
+    let home = dirs::home_dir().expect("no home dir");
+    let candidates = [
+        home.join(".a3s/config.hcl"),
+        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../.a3s/config.hcl"),
+    ];
+    candidates
+        .into_iter()
+        .find(|p| p.exists())
+        .expect("Config not found. Set A3S_CONFIG or create ~/.a3s/config.hcl")
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let agent = Agent::new(find_config().to_str().unwrap()).await?;
+    let workspace = TempDir::new()?;
+
+    // Pre-create a file for the agent to work with
+    std::fs::write(
+        workspace.path().join("users.json"),
+        r#"[{"name":"Alice","role":"admin"},{"name":"Bob","role":"viewer"},{"name":"Carol","role":"editor"}]"#,
+    )?;
+
+    let session = agent.session(workspace.path().to_str().unwrap(), None)?;
+    println!(
+        "Streaming example — workspace: {}\n",
+        workspace.path().display()
+    );
+
+    // Stream returns (receiver, join_handle)
+    let (mut rx, _handle) = session
+        .stream(
+            "Read users.json, then create a Markdown table in users.md listing each user's name and role.",
+            None,
+        )
+        .await?;
+
+    let mut tool_count = 0usize;
+    let mut text_chars = 0usize;
+
+    while let Some(event) = rx.recv().await {
+        match event {
+            AgentEvent::Start { .. } => {
+                println!("▶ Agent started");
+            }
+            AgentEvent::TurnStart { turn } => {
+                println!("┌─ Turn {turn}");
+            }
+            AgentEvent::ToolStart { name, .. } => {
+                tool_count += 1;
+                print!("│  🔧 {name}...");
+            }
+            AgentEvent::ToolEnd { exit_code, .. } => {
+                let icon = if exit_code == 0 { "✓" } else { "✗" };
+                println!(" {icon}");
+            }
+            AgentEvent::ToolInputDelta { .. } => {
+                // Tool argument streaming — could show partial JSON here
+            }
+            AgentEvent::TextDelta { text } => {
+                text_chars += text.len();
+            }
+            AgentEvent::TurnEnd { turn, usage } => {
+                println!("└─ Turn {turn} done ({} tokens)", usage.total_tokens);
+            }
+            AgentEvent::End { usage, .. } => {
+                println!("\n■ Agent finished");
+                println!(
+                    "  Tools: {tool_count}, Text: {text_chars} chars, Tokens: {}",
+                    usage.total_tokens
+                );
+                break;
+            }
+            AgentEvent::Error { message } => {
+                eprintln!("✗ Error: {message}");
+                break;
+            }
+            _ => {} // #[non_exhaustive] — always include wildcard
+        }
+    }
+
+    // Verify output
+    let md = workspace.path().join("users.md");
+    if md.exists() {
+        println!(
+            "\n✓ users.md created ({} bytes)",
+            std::fs::metadata(&md)?.len()
+        );
+    }
+
+    Ok(())
+}

a3s_code-0.9.1/code/core/examples/03_multi_turn.rs

@@ -0,0 +1,106 @@
+//! # Multi-Turn Conversation — Context Preservation
+//!
+//! Demonstrates that the session preserves conversation history across
+//! multiple send() calls, so the LLM remembers what happened earlier.
+//!
+//! ```bash
+//! cargo run --example 03_multi_turn
+//! ```
+
+use a3s_code_core::Agent;
+use std::path::PathBuf;
+use tempfile::TempDir;
+
+fn find_config() -> PathBuf {
+    if let Ok(p) = std::env::var("A3S_CONFIG") {
+        return PathBuf::from(p);
+    }
+    let home = dirs::home_dir().expect("no home dir");
+    let candidates = [
+        home.join(".a3s/config.hcl"),
+        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../.a3s/config.hcl"),
+    ];
+    candidates
+        .into_iter()
+        .find(|p| p.exists())
+        .expect("Config not found. Set A3S_CONFIG or create ~/.a3s/config.hcl")
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let agent = Agent::new(find_config().to_str().unwrap()).await?;
+    let workspace = TempDir::new()?;
+    let session = agent.session(workspace.path().to_str().unwrap(), None)?;
+
+    println!(
+        "Multi-turn example — workspace: {}\n",
+        workspace.path().display()
+    );
+
+    // ── Turn 1: Create a config file ──
+    println!("[Turn 1] Create a config file");
+    let r1 = session
+        .send(
+            "Create a file called `config.toml` with:\n\
+             [server]\nhost = \"0.0.0.0\"\nport = 8080\n\n\
+             [database]\nurl = \"postgres://localhost/mydb\"\npool_size = 5",
+            None,
+        )
+        .await?;
+    println!(
+        "  Tools: {}, Tokens: {}",
+        r1.tool_calls_count, r1.usage.total_tokens
+    );
+
+    // ── Turn 2: Ask about the file (tests context memory) ──
+    println!("\n[Turn 2] Ask about the file");
+    let r2 = session
+        .send(
+            "What port is the server configured to use? Read the config file to confirm.",
+            None,
+        )
+        .await?;
+    println!(
+        "  Tools: {}, Tokens: {}",
+        r2.tool_calls_count, r2.usage.total_tokens
+    );
+    println!("  Answer: {}", truncate(&r2.text, 120));
+
+    // ── Turn 3: Modify based on context ──
+    println!("\n[Turn 3] Modify based on previous context");
+    let r3 = session
+        .send(
+            "Change the server port to 3000 and increase pool_size to 10.",
+            None,
+        )
+        .await?;
+    println!(
+        "  Tools: {}, Tokens: {}",
+        r3.tool_calls_count, r3.usage.total_tokens
+    );
+
+    // ── Verify ──
+    let history = session.history();
+    println!("\nHistory: {} messages across 3 turns", history.len());
+
+    let config_path = workspace.path().join("config.toml");
+    if config_path.exists() {
+        let content = std::fs::read_to_string(&config_path)?;
+        println!(
+            "✓ config.toml: port=3000? {} pool=10? {}",
+            content.contains("3000"),
+            content.contains("10")
+        );
+    }
+
+    Ok(())
+}
+
+fn truncate(s: &str, max: usize) -> String {
+    let s = s.trim();
+    if s.len() <= max {
+        s.to_string()
+    } else {
+        format!("{}…", &s[..max])
+    }
+}

a3s_code-0.9.1/code/core/examples/04_model_switching.rs

@@ -0,0 +1,87 @@
+//! # Model Switching — Use Different Providers Per Session
+//!
+//! Shows how to override the default model on a per-session basis.
+//! Each session can target a different provider/model from the config.
+//!
+//! ```bash
+//! cargo run --example 04_model_switching
+//! ```
+
+use a3s_code_core::{Agent, SessionOptions};
+use std::path::PathBuf;
+use tempfile::TempDir;
+
+fn find_config() -> PathBuf {
+    if let Ok(p) = std::env::var("A3S_CONFIG") {
+        return PathBuf::from(p);
+    }
+    let home = dirs::home_dir().expect("no home dir");
+    let candidates = [
+        home.join(".a3s/config.hcl"),
+        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../.a3s/config.hcl"),
+    ];
+    candidates
+        .into_iter()
+        .find(|p| p.exists())
+        .expect("Config not found. Set A3S_CONFIG or create ~/.a3s/config.hcl")
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let agent = Agent::new(find_config().to_str().unwrap()).await?;
+
+    let prompt = "What model are you? Reply in one short sentence.";
+
+    // ── Session 1: Default model (from config's default_model) ──
+    println!("─── Session 1: Default model ───");
+    let ws1 = TempDir::new()?;
+    let s1 = agent.session(ws1.path().to_str().unwrap(), None)?;
+    let r1 = s1.send(prompt, None).await?;
+    println!("  Response: {}", r1.text.trim());
+    println!("  Tokens:   {}\n", r1.usage.total_tokens);
+
+    // ── Session 2: Override to a specific model ──
+    // Use the model specified by A3S_ALT_MODEL env var, or try "anthropic/claude-sonnet-4-20250514"
+    let alt_model = std::env::var("A3S_ALT_MODEL")
+        .unwrap_or_else(|_| "anthropic/claude-sonnet-4-20250514".to_string());
+
+    println!("─── Session 2: Override to {alt_model} ───");
+    let ws2 = TempDir::new()?;
+    let opts = SessionOptions::new().with_model(&alt_model);
+    match agent.session(ws2.path().to_str().unwrap(), Some(opts)) {
+        Ok(s2) => {
+            let r2 = s2.send(prompt, None).await?;
+            println!("  Response: {}", r2.text.trim());
+            println!("  Tokens:   {}\n", r2.usage.total_tokens);
+        }
+        Err(e) => {
+            println!("  Skipped (model not in config): {e}\n");
+        }
+    }
+
+    // ── Session 3: Override with temperature=0.0 (deterministic) ──
+    println!("─── Session 3: With temperature=0.0 (deterministic) ───");
+    // Use the default model but with temperature override
+    // Note: temperature/thinking_budget require a model override to take effect
+    let default_model =
+        std::env::var("A3S_MODEL").unwrap_or_else(|_| "openai/kimi-k2.5".to_string());
+
+    let ws3 = TempDir::new()?;
+    let opts = SessionOptions::new()
+        .with_model(&default_model)
+        .with_temperature(0.0);
+    match agent.session(ws3.path().to_str().unwrap(), Some(opts)) {
+        Ok(s3) => {
+            let r3 = s3
+                .send("What is 2 + 2? Reply with just the number.", None)
+                .await?;
+            println!("  Response: {}", r3.text.trim());
+            println!("  Tokens:   {}", r3.usage.total_tokens);
+        }
+        Err(e) => {
+            println!("  Skipped: {e}");
+        }
+    }
+
+    Ok(())
+}