Skip to main content

Getting started

The Faheem Code SDK is a modular framework for building AI agents that interact with code, files, and system commands. Agents can execute bash commands, edit files, browse the web, and more.

Prerequisites​

Install the uv package manager (version 0.8.13+):

curl -LsSf https://astral.sh/uv/install.sh | sh

Installation​

Step 1: acquire an LLM API key​

The SDK requires an LLM API key from any LiteLLM-supported provider. See our recommended models for best results.

Option 1: direct provider

Bring your own API key from providers like:

Example:

export LLM_API_KEY="your-api-key"
uv run python examples/01_standalone_sdk/01_hello_world.py
Option 2: Faheem Code Cloud (recommended)

Sign up for Faheem Code Cloud, add credits to your account, and get your Faheem Code LLM API key from the API keys page. This gives you access to models verified to work well with Faheem Code, with no markup.

Example:

export LLM_MODEL="faheemcode/claude-sonnet-4-5-20250929"
uv run python examples/01_standalone_sdk/01_hello_world.py

Learn more →

Option 3: ChatGPT subscription

If you have a ChatGPT Plus or Pro subscription, you can use LLM.subscription_login() to authenticate with your ChatGPT account and access Codex models without consuming API credits.

from faheemcode.sdk import LLM

llm = LLM.subscription_login(vendor="openai", model="gpt-5.2-codex")

Learn more →

Tip: Model name prefixes depend on your provider

  • If you bring your own provider key (Anthropic/OpenAI/etc.), use that provider's model name, e.g. anthropic/claude-sonnet-4-5-20250929 Faheem Code supports dozens of models, you can choose the model you want to try.
  • If you use Faheem Code Cloud, use faheemcode/-prefixed models, e.g. faheemcode/claude-sonnet-4-5-20250929

Many examples in the docs read the model from the LLM_MODEL environment variable. You can set it like:

export LLM_MODEL="faheemcode/claude-sonnet-4-5-20250929"  # for Faheem Code Provider

Set Your API Key:

export LLM_API_KEY=your-api-key-here

Step 2: install the SDK​

Option 1: install via PyPI
# Core SDK + built-in tools — install together so their versions stay aligned
pip install -U faheemcode-sdk faheemcode-tools

# Optional: sandboxed workspaces in Docker or remote servers.
# List every package in one command so they all resolve to the same version.
pip install -U faheemcode-sdk faheemcode-tools faheemcode-workspace faheemcode-agent-server
Option 2: install from source
# Clone the repository
git clone https://github.com/SMART-National-Solution/faheem-code-sdk.git
cd software-agent-sdk

# Install dependencies and setup development environment
make build

Step 3: run your first agent​

Here's a complete example that creates an agent and asks it to perform a simple task:

import os

from faheemcode.sdk import LLM, Agent, Conversation, Tool
from faheemcode.tools.file_editor import FileEditorTool
from faheemcode.tools.task_tracker import TaskTrackerTool
from faheemcode.tools.terminal import TerminalTool

llm = LLM(
    model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
    api_key=os.getenv("LLM_API_KEY"),
    base_url=os.getenv("LLM_BASE_URL", None),
)

agent = Agent(
    llm=llm,
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
        Tool(name=TaskTrackerTool.name),
    ],
)

cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)

conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()
print("All done!")

Run the example:

# Using a direct provider key (Anthropic/OpenAI/etc.)
uv run python examples/01_standalone_sdk/01_hello_world.py
# Using Faheem Code Cloud
export LLM_MODEL="faheemcode/claude-sonnet-4-5-20250929"
uv run python examples/01_standalone_sdk/01_hello_world.py

You should see the agent understand your request, explore the project, and create a file with facts about it.

Core concepts​

Agent: An AI-powered entity that can reason, plan, and execute actions using tools.

Tools: Capabilities like executing bash commands, editing files, or browsing the web.

Workspace: The execution environment where agents operate (local, Docker, or remote).

Conversation: Manages the interaction lifecycle between you and the agent.

Basic workflow​

  1. Configure LLM: Choose model and provide API key
  2. Create Agent: Use preset or custom configuration
  3. Add Tools: Enable capabilities (bash, file editing, etc.)
  4. Start Conversation: Create conversation context
  5. Send Message: Provide task description
  6. Run Agent: Agent executes until task completes or stops
  7. Get Result: Review agent's output and actions

Try more examples​

The repository includes 24+ examples demonstrating various capabilities:

# Simple hello world
uv run python examples/01_standalone_sdk/01_hello_world.py

# Custom tools
uv run python examples/01_standalone_sdk/02_custom_tools.py

# With skills
uv run python examples/01_standalone_sdk/03_activate_microagent.py

# See all examples
ls examples/01_standalone_sdk/

Next steps​

Explore documentation​

Build custom solutions​

Get help​