Quickstart

# 1. Clone & enter
git clone <this-repo>
cd social_impact_crew

# 2. Virtual env
python -m venv .venv
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate

# 3. Install
pip install -e .

# 4. Add your LLM key
cp .env.example .env
# then edit .env and paste your GROQ_API_KEY (get one free at https://console.groq.com/keys)

# 5. Run
python -m social_impact_crew.main              # asks for a city
python -m social_impact_crew.main Bengaluru    # or pass it on the CLI

You'll get verbose CrewAI logs as each agent works, and the final meme printed at the bottom.

Switching the LLM

You don't need to pick a provider explicitly — just put your key in .env and the app auto-detects it. All four supported providers:

If you want to pin a specific model, set MODEL=<provider>/<model> in .env. That always wins over auto-detection. Format follows LiteLLM's provider/model convention.

Project layout

social_impact_crew/
├── pyproject.toml
├── .env.example
├── architecture.md             # Mermaid diagram + locked API contract
└── src/social_impact_crew/
    ├── main.py                 # CLI entry point + IP geolocation + OpenLIT
    ├── api.py                  # FastAPI wrapper — POST /api/run + /api/chat
    ├── crew.py                 # @CrewBase wiring
    ├── llm.py                  # provider auto-detection (BYOK) + runtime overrides
    ├── intent.py               # two-layer intent classifier (regex + LLM fallback)
    ├── personality.py          # 6 personalities × 4 languages voice blocks
    ├── preferences.py          # JSON-file user prefs (async lock + atomic write)
    ├── safety.py               # AQI safety override + prompt-injection sanitiser
    ├── config/
    │   ├── agents.yaml         # role / goal / backstory per agent
    │   └── tasks.yaml          # description / expected_output / context
    └── tools/
        └── custom_tool.py      # GeocodeTool, WeatherTool, PollutionTool
                                # + ContextVar side-channel for API capture

Running as an API

run_api                # serves on http://127.0.0.1:8000
# POST http://127.0.0.1:8000/api/run   {"city": "Chennai"}
# POST http://127.0.0.1:8000/api/chat  {"message": "hi"}
# /api/run returns {city, coords, weather, pollution, aqi_level, meme}

Frontend

The AgentVerse PWA frontend lives in its own repo:

→ github.com/sasilab/AgentVerse-Frontend

It's a single static PWA reused across every AgentVerse episode. To connect it to this backend:

1. Start this backend: run_api (serves on http://127.0.0.1:8000).
2. Clone & serve the frontend per its README.
3. Open the Settings panel in the PWA and point the API base URL at http://127.0.0.1:8000. Paste your LLM key, pick a personality and language, and you're done.

The POST /api/run contract is stable across every AgentVerse episode, so the same frontend works against any episode backend.

Observability

openlit.init() is called at the top of main.py and api.py. By default it ships traces/metrics to http://127.0.0.1:4318 (OTLP). To see them, run any OTLP collector (Jaeger, Grafana Tempo, OpenLIT UI). No collector running = silent no-op, nothing breaks.

Why these design choices

• Geocoding as a tool (not hardcoded coords) so the meme works for any city you throw at it.
• YAML configs for agents and tasks so non-coders can tweak personalities and task prompts without touching Python.
• Sequential process because the meme literally depends on the upstream data — no point in running these in parallel.
• Tools only where needed — the meme writer has no tools because its job is pure creative writing over upstream context.

License

MIT. Built for learning — fork it, remix it, make your own episode.