Metadata-Version: 2.3
Name: streetrace
Version: 0.1.8
Summary: StreetRace is an agentic AI coding partner designed to help engineers leverage AI capabilities directly from the command line to create software.
License: MIT License
         
         Copyright (c) 2025 krmrn42
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Requires-Python: >=3.12,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: a2a-sdk (>=0.2.4,<0.3.0)
Requires-Dist: anthropic (>=0.50.0,<0.51.0)
Requires-Dist: bashlex (>=0.18,<0.19)
Requires-Dist: boto3 (>=1.28.57,<2.0.0)
Requires-Dist: google-adk (>=0.4.0,<0.5.0)
Requires-Dist: google-genai (>=1.12.1,<2.0.0)
Requires-Dist: litellm (>=1.67.5,<2.0.0)
Requires-Dist: marko (>=2.1.3,<3.0.0)
Requires-Dist: mcp (>=1.7.1,<2.0.0)
Requires-Dist: ollama (>=0.4.8,<0.5.0)
Requires-Dist: openai (>=1.76.0,<2.0.0)
Requires-Dist: pathspec (>=0.12.1,<0.13.0)
Requires-Dist: prompt-toolkit (>=3.0.51,<4.0.0)
Requires-Dist: pydantic (>=2.11.3,<3.0.0)
Requires-Dist: pypubsub (>=4.0.3,<5.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: rich (>=14.0.0,<15.0.0)
Requires-Dist: tenacity (>=9.1.2,<10.0.0)
Requires-Dist: typed-argparse (>=0.3.1,<0.4.0)
Requires-Dist: tzlocal (>=5.3.1,<6.0.0)
Description-Content-Type: text/markdown

# StreetRace🚗💨

Today, StreetRace🚗💨 is a CLI-based assistant that can run agentic workflows, maintain
your conversation histories, allowing full customization, and using any model supported
by [BerriAI/litellm](https://github.com/BerriAI/litellm), including self-hosted ollama
models.

The goal is to enable:

1. Creating and using agents in your day-to-day SWE/SRE workflows.
2. Publishing and running your agents and other code to cloud envs.
3. Debugging, code generation, and diagnostics from CLI.

Here is a workflow that describes what StreetRace🚗💨 aims to be in v.1:

```bash
> streetrace
You: Create an agent that takes issues from our tracker API (documented in
..... @apis/my_issue_tracker.yaml), takes the latest issue with the highest priority,
..... and implements it. When complete and the implementation fully satisfies the
..... described requirements, publishes a PR on GitHub.
StreetRace: Working...
StreetRace: Your agent is created as "IssueFixer".
You: Deploy @IssueFixer and run it in a loop.
StreetRace: Working...
StreetRace: Deploying IssueFixer to yourk8shost.foo.bar...
StreetRace: IssueFixer is started and available at A2A endpoint issuefixer-001.foo.bar.
IssueFixer: There are 39 unresolved issues. Taking issue ISS007.
IssueFixer: Based on the issue description, I need to fix the app so it works.
IssueFixer: Looking for a solution...
IssueFixer: ...
IssueFixer: ISS007 is fixed, taking ISS042 now...
...
```

## Installation and usage

### Install from pip

```bash
$ pip install streetrace
```

### Install from source

The code is managed by `poetry`. If it's not already installed, follow the [poetry
install guide](https://python-poetry.org/docs/#installation).

```bash
$ git clone git@github.com:krmrn42/street-race.git
$ cd street-race
$ poetry install
$ poetry run streetrace --model=$YOUR_FAVORITE_MODEL
```

Where `$YOUR_FAVORITE_MODEL` is the
[LiteLLM provider route](https://docs.litellm.ai/docs/providers) (`provider/model`).

### Environment Setup

Follow relevant LiteLLM guides to set up environment for a specific model. For example,
for commercial providers, set your regular API key in the environment
(`ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `OPENAI_API_KEY`, etc), or `OLLAMA_API_URL` for
local Ollama models.

### Usage

`streetrace` is a CLI, and it can be installed as your dev dependency. It runs in the
current directory, keeping all file reading and modifications in the current directory.

You can optionally supply a `--path` argument to provide a different working directory
path.

```bash
$ streetrace --model=$YOUR_FAVORITE_MODEL
You: Type your prompt
```

#### Try in your environment

Currently, StreetRace includes one coding agent with a model of your choise. This agent
is a capable software engineering agent that can work with your technology stack.

You can add more context to your prompts in two ways:

1. Using @-mentions, autocomplete will suggest local files that you can add to the
   prompt.
2. Any other project context can be added in a `.streetrace` folder:
   - `SYSTEM.md` is used as your system instruction.
   - Any other files under `.streetrace` are added as initial conversation messages.

### Command Line Arguments

#### Session Management

StreetRace🚗💨 supports persistence of conversations through sessions. You can specify:

- `--app-name` - Application name for the session (defaults to the current working
  directory name)
- `--user-id` - User ID for the session (defaults to your GitHub username, Git username,
  or OS username)
- `--session-id` - Session ID to use or create (defaults to current timestamp)
- `--list-sessions` - List all available sessions for the current app and user

Examples:

```bash
# List all sessions for the current app and user
$ streetrace --list-sessions

# Create or continue a specific session
$ streetrace --session-id my-project-refactoring

# Work with a specific app name and user
$ streetrace --app-name my-project --user-id john.doe --session-id feature-x
```

If no session arguments are provided, StreetRace🚗💨 will:

1. Use the current working directory name as the app name
2. Use your detected user identity as the user ID
3. Create a new session with a timestamp-based ID

This allows you to maintain separate conversation contexts for different projects or
tasks.

If you want to work with the same agent/context across multiple runs, use the same
session ID.

#### Working with Files in Another Directory

The `--path` argument allows you to specify a different working directory for all file
operations:

```bash
$ streetrace --path /path/to/your/project
```

This path will be used as the working directory (work_dir) for all tools that interact
with the file system, including:

- `list_directory`
- `read_file`
- `write_file`
- `find_in_files`
- as a cwd in cli commands.

This feature makes it easier to work with files in another location without changing
your current directory.

### Interactive Mode

When run without `--prompt`, StreetRace🚗💨 enters interactive mode.

#### Autocompletion

- Type `@` followed by characters to autocomplete file or directory paths relative to
  the working directory.
- Type `/` at the beginning of the line to autocomplete available internal commands.

#### Internal Commands

These commands can be typed directly into the prompt (with autocompletion support):

- `/help`: Display a list of all available commands with their descriptions.
- `/exit`: Exit the interactive session.
- `/quit`: Quit the interactive session.
- `/history`: Display the conversation history.
- `/compact`: Summarize conversation history to reduce token count.
- `/reset`: Reset the current session, clearing the conversation history.

For detailed information about the `/compact` command, see
[docs/commands/compact.md](docs/commands/compact.md).

### Non-interactive Mode

You can use the `--prompt` argument to run StreetRace🚗💨 in non-interactive mode:

```bash
$ streetrace --prompt "List all Python files in the current directory"
```

This will execute the prompt once and exit, which is useful for scripting or one-off
commands.

### CLI Command Safety

StreetRace🚗💨 includes an experimental safety mechanism for CLI command execution.
Each command requested by the AI is analyzed and categorized into one of three safety
levels:

- **Safe**: Commands from a pre-configured safe list with only relative paths
- **Ambiguous**: Commands not in the safe list but without obvious risks
- **Risky**: Commands with absolute paths, directory traversal attempts, or potentially
  dangerous operations

Risky commands are blocked by default to prevent unintended filesystem operations or
system changes. This adds a layer of protection when working with AI-suggested commands.

The safety checker uses `bashlex` to parse and analyze commands and arguments, checking
for:

- Command presence in a predefined safe list
- Use of absolute vs. relative paths
- Directory traversal attempts (using `..` to move outside the working directory)

This helps ensure that StreetRace🚗💨 operates within the intended working directory and
with known-safe commands.

### Agent System

StreetRace🚗💨 includes a modular agent system that allows for specialized agents to be discovered and used.

#### Agent Discovery

The `list_agents` tool allows the assistant to discover available agents in the system.
Agents are searched for in the following locations:

- `./agents/` (relative to the current working directory)
- `../../agents/` (relative to the src/streetrace/app.py)

#### Creating Custom Agents

StreetRace supports two ways to create custom agents:

##### Option 1: Using the StreetRaceAgent Interface (Recommended)

1. Create a directory for your agent in the `./agents/` folder (e.g., `./agents/my_agent/`)
2. Create an `agent.py` file with a class that inherits from `StreetRaceAgent` and implements:

   - `get_agent_card()` - Returns metadata about the agent (name, description, capabilities)
   - `get_required_tools()` - Returns a list of tools the agent needs
   - `create_agent()` - Creates the actual agent instance with the provided model and tools

3. Add a `README.md` file with documentation for your agent

Example agent class:

```python
from streetrace.agents.street_race_agent import StreetRaceAgent
from streetrace.agents.street_race_agent_card import StreetRaceAgentCard

class MyAgent(StreetRaceAgent):
    def get_agent_card(self) -> StreetRaceAgentCard:
        return StreetRaceAgentCard(
            name="My Agent",
            description="A specialized agent that does something useful",
            capabilities=["capability1", "capability2"],
        )

    async def get_required_tools(self) -> list[str]:
        return [
            "streetrace:fs_tool::read_file",
            "streetrace:fs_tool::write_file",
        ]

    async def create_agent(self, model_factory, tools) -> BaseAgent:
        model = model_factory.get_default_model()
        return Agent(
            name="My Agent",
            model=model,
            description="My specialized agent",
            instruction="You are a specialized agent that does X, Y, and Z...",
            tools=tools,
        )
```

##### Option 2: Legacy Approach (Basic Functions)

1. Create a directory for your agent in the `./agents/` folder (e.g., `./agents/my_agent/`)
2. Create an `agent.py` file with these required functions:

   - `get_agent_metadata()` - Returns a dictionary with `name` and `description` keys
   - `run_agent(input_text: str)` - Implements the agent's functionality

3. Add a `README.md` file with documentation for your agent

#### Running Agents

The `run_agent` tool allows the primary assistant to execute specialized agents:

```python
run_agent(
    agent_name="Hello World",
    input_text="What files are in this directory?",
    model_name="default"  # Optional, defaults to the default model
)
```

This enables a hierarchical agent system where the primary StreetRace assistant can delegate tasks to specialized agents.

#### Tool Configuration

Tools available to agents are defined in the `./tools/tools.yaml` configuration file. This file specifies:

- Tool name and description
- Source type (e.g., 'local' for Python modules or 'mcp' for external services)
- Module and function name for local tools
- Whether the tool requires agent capabilities

The configuration makes it easy to add, modify, or disable tools without changing code.

#### Tool Discovery

The `list_tools` tool provides information about available tools that can be provided to agents.
This helps the assistant understand what capabilities are available in the system.

The tool returns a list of available tools with:

- Tool name
- Description
- Whether the tool requires agent capabilities

